.. description des renkan

##############################

Description de l'outils renkan

##############################

Introduction

============

Renkan est un outil d'édition et d'affichage de carte mentale.

Il a été conçu de façon modulaire et avec une claire separation entre la partie cliente en javascript et la partie serveur.

En particulier la partie du client en charge des communications avec le serveur (chargement des projets, gestion de la persistance) est totalement modulaire et configurable.

Cela permet d'adapter facilement le client à l'api de sauvegarde du serveur.

Les sources et la documentation Renkan peuvent être trouvées dans le dépot de code suivant : https://www.iri.centrepompidou.fr/dev/hg/renkan.

Modèle de donnée serveur (HDALab)

=================================

Le modèle de donnée du coté serveur est simple.

En effet le serveur ne cherche pas à interpréter le contenu d'un renkan.

Il se content de sauvegarder le contenu qui lui est transmis par le client et dans l'autre sens de transmettre directement au client le contenu sauvegardé en base.

Toute l'interprétation du modèle se fait dans le client.

Classe renkanmanager.models.Renkan

----------------------------------

*class* ``renkanmanager.models.``\ **Renkan** :

    Classe de base d'un renkan.

    Champs de l'objet:

      - **owner** (`object`) : Le propriétaire (créateur) du renkan.

      - **rk_id** (`str`) : id du renkan.

      - **content** (`str`) : contenu du renkan (la chaine JSON brute).

      - **title** (`str`) : titre du renkan.

      - **image** (`str`) : chemin vers l'image miniature du renkan.

      - **creation_date** (`datetime`) : date de création.

      - **modification_date** (`datetime`) : date de modification.

Classe hdalab.models.renkan.HdalabRenkan

----------------------------------------

.. autoclass:: hdalab.models.renkan.HdalabRenkan

  :noindex:

Format renkan

=============

Un renkan a le format suivant:

  exemple ::

    {

        "id": "f4d002b7-d4fd-486c-8898-6c6ceebc3354",

        "schema_version": 2, #version of schema, latest is 2.

        "title": "Example of Renkan with movies",

        "description": "A long description",

        "created": "2013-03-18T11:32:40.253+01:00",

        "updated": "2014-02-04T15:12:56.619+01:00",

        "nodes": [

            {

                "id": "node-2013-05-08-72c911bafdf9932c-0001",

                "title": "Une femme mène l'enquête",

                "description": "La caméra suit la femme qui marche\nJeu avec la caméra qui se substitue au spectateur",

                "uri": "http://ldt.iri.centrepompidou.fr/ldtplatform/ldt/front/player/lyceehulst_3extraits/c8a61ee4-b33c-11e2-802c-00145ea4a2be#id=s_DCA8D184-EFC2-314B-0F6B-84043E8F9984",

                "style": { #optional

                    "color": "#ff7f00", #line color, optional (null)

                    "thickness": 1, #thickness of the line, optional (1)

                    "dash": false, #dashed line, optional (false)

                },

                "position": {

                    "x": -547.0499881440252,

                    "y": -221.5401229374163

                },

                "image": "http://ldt.iri.centrepompidou.fr/static/site/ldt/css/imgs/video_sequence.png",

                "size": 0,

                "project_id": "f4d002b7-d4fd-486c-8898-6c6ceebc3354",

                "created_by": "de68xf75y6hs5rgjhgghxbm217xk",

                "type": "...",

                "hidden": false,

                "shape": "circle",

            },

            ...

        ],

        "edges": [

            {

                "id": "edge-2013-05-08-72c911bafdf9932c-0002",

                "title": "",

                "description": "",

                "uri": "",

                "style": { #optional

                    "color": "#ff7f00", #line color, optional (null)

                    "thickness": 1, #thickness of the line, optional (1)

                    "dash": false, #dashed line, optional (false)

                    "arrow": true,  #draw the arrow, optional (true)

                },

                "from": "node-2013-04-30-a81adec6694db5f4-0032",

                "to": "node-2013-05-08-72c911bafdf9932c-0001",

                "project_id": "f4d002b7-d4fd-486c-8898-6c6ceebc3354",

                "created_by": "de68xf75y6hs5rgjhgghxbm217xk"

            },

            ...

        ],

        "users": [ #optional

            {

                "userId": "user-2015-05-05-72c911bafdf9932c-0001",

                "color": "#cc9866",

                "username": "user1",

                "anonymous": true

            },

        ...

        ],

        "space_id": "17f968e4-2640-4319-aa61-b5b8b527ebb4", #Optional

        "views": [ #Optional

            {

                "zoom_level": 0.8275032552816195,

                "offset_x": 832.0104075533723,

                "offset_y": 402.8917139487223

            }

        ]

    }

On retrouve une documentation un peu plus détaillée à l'url suivante : https://www.iri.centrepompidou.fr/dev/hg/renkan/file/tip/client/README.md .

Système de chutier

==================

Renkan propose un système de "chutier". C'est un système de liste d'élément ouvert à gauche d'un renkan en édition.

On le voit à gauche sur l'image suivante :

.. image:: _static/img/renkan/renkan_edition.png

Ce système permet d'ajouter rapidement des resources fiches ou tag par "glisser/déposer".

Techniquement, ces fonctionalités de chutiers propres à HDALab sont définies dans le fichier `hdalab/static/hdalab/js/hdalab-renkan-bins.js`.

.. _renkan_boite_recherche_contenus:

Boite de recherche de contenus

------------------------------

.. image:: _static/img/renkan/renkan_recherche_contenus.png

Cette boite de recherche permet de lancer une requête sur 3 types de ressources:

  - recherche de tag

  - recherche de fiches

  - recherche d'article wikipedia

  +--------------------+----------------------------------------------------------+--------------------------------------+

  | type               | url de requête                                           | Vue                                  |

  +====================+==========================================================+======================================+

  | tags               | http://hdalab.iri-research.org/hdalab/a/tagsearch?       | :func:`hdalab.views.ajax.tagsearch`  |

  +--------------------+----------------------------------------------------------+--------------------------------------+

  | fiches             | http://hdalab.iri-research.org/hdalab/hdabo/searchajax/? | :class:`hdabo.views.SearchDatasheet` |

  +--------------------+----------------------------------------------------------+--------------------------------------+

  | articles wikipedia | https://fr.wikipedia.org/w/api.php?action=query...       |                                      |

  +--------------------+----------------------------------------------------------+--------------------------------------+

Le resultat de la recherche est affiché dans un nouvel onglet listant les ressources.

Boite de recherche sur les résultats

------------------------------------

.. image:: _static/img/renkan/renkan_recherche_resultats.png

Cette boite de recherche permet de rechercher et de filtrer des résultats déjà présent dans les onglets. La recherche est uniquement locale et ne lance fait pas de requête http.

Liste de ressource

------------------

.. image:: _static/img/renkan/renkan_bin_resources.png

Cet onglet liste des ressources statiques qui peuvent être utiles à l'édition du renkan.

Liste de ressource supplémentaire

---------------------------------

.. image:: _static/img/renkan/renkan_bin_plus_ressources.png

Cet onglet liste des ressources "supplémentaires".

Un renkan est souvent créé à partir du résultat d'une recherche sur la page de `recherche par facette <pages_recherche_facette>`.

Pour éviter d'avoir trop de noeuds ressources, les 8 premiers résultats de la recherche sont utilisés dans le renkan et les 10 suivants sont utilisés dans ce chutier.

(ce comportement est défini dans la méthode :func:`hdalab.views.profile.HdalabRenkanGetPut.get`).

Sauvegarde des renkan

=====================

la sauvegarde des renkan est définie dans le fichier `hdalab/static/hdalab/js/renkan-manual-save.js`.

La sauvegarde est déclenchée par une action de l'utilisateur.

Calcul des miniatures

=====================

.. image:: _static/img/renkan/renkan_liste_miniature.png

Lorsqu'un renkan est publié (le statut de l'objet :class:`hdalab.models.renkan.HdalabRenkan` passe à `PUBLISHED`) une miniature du renkan est capturée.

Cette capture se fait dans la méthode :func:`hdalab.services.renkan_capture_preview`.

On lance `PhantomJS <http://phantomjs.org/>`_ qui ouvre la page :ref:`affichage-d-un-renkan-en-plein-ecran` et effectue une capture.

Les arguments de l'appel sont les suivants ::

  phantomjs

      <chemin/vers/capture-phantomjs.js>

      http://hdalab.iri-research.org/hdalab/renkan/full/?rk_id=<id_du_renkan>

      <chemin/vers/le/thumbnail.png>

      --width=500

      --height=500

      --wait=5000

Le script de capture PhantomJS se trouve dans le fichier `src/hdalab/scripts/capture-phantomjs.js <https://www.iri.centrepompidou.fr/dev/hg/hdabo/file/tip/src/hdalab/scripts/capture-phantomjs.js>`_.

Le module `renkanmanager`

=========================

Module Django

-------------

Les fonctionnalité Renkan sont apportée par la librairie Django `renkanmanager`. Le code source de cette librairie se trouve dans le `dépot de code source du projet Renkan <https://www.iri.centrepompidou.fr/dev/hg/renkan>`_ dans le répertoire `/server/python/django/renkanmanager` (c.f. https://www.iri.centrepompidou.fr/dev/hg/renkan/file/tip/server/python/django/renkanmanager).

Gestions des fichiers applicatifs Renkan

----------------------------------------

L'ensemble des fichiers nécessaires au fonctionnement du client Renkan (javascript, css, imags, libraries) sont fournis comme `ressources statiques <https://docs.djangoproject.com/en/1.8/howto/static-files/>`_ par le module Django `renkanmanager`.

On peut en parcourir l'arborescence à l'url suivante : https://www.iri.centrepompidou.fr/dev/hg/renkan/file/tip/server/python/django/renkanmanager/static/renkanmanager .

Tous ces fichiers sont donc mis à jour lors de l'installation d'une nouvelle version de `renkanmanager`.

Une description plus précise des fichiers nécessaires à l'instanciation d'un client Renkan dans une page web peut être trouvée dans le fichier `Readme <https://www.iri.centrepompidou.fr/dev/hg/renkan/file/tip/client/README.md>`_ du client.

Des exemples d'intégration se trouvent dans le répertoire `test` du client Renkan (https://www.iri.centrepompidou.fr/dev/hg/renkan/file/tip/client/test).