From 6f3ad49abf0ff5e7d90c9bd9404e55ff84ce3a62 Mon Sep 17 00:00:00 2001 From: Benjamin Renard Date: Mon, 11 May 2020 17:29:51 +0200 Subject: [PATCH] Add doc about upgrade --- doc/LS.entities.xml | 2 + doc/LdapSaisie.docbook | 13 +- doc/upgrade/upgrade.docbook | 439 ++++++++++++++++++++++++++++++++++++ 3 files changed, 449 insertions(+), 5 deletions(-) create mode 100644 doc/upgrade/upgrade.docbook diff --git a/doc/LS.entities.xml b/doc/LS.entities.xml index 16c3623f..6eaec076 100644 --- a/doc/LS.entities.xml +++ b/doc/LS.entities.xml @@ -37,3 +37,5 @@ LSauthMethod"> LSselect"> LSsearch"> + + diff --git a/doc/LdapSaisie.docbook b/doc/LdapSaisie.docbook index 0a795edb..b9c40656 100644 --- a/doc/LdapSaisie.docbook +++ b/doc/LdapSaisie.docbook @@ -1,10 +1,10 @@ - %LS-entities; - + %conf-entities; @@ -21,10 +21,11 @@ book SYSTEM "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" + ]> - + - + LdapSaisie @@ -42,10 +43,12 @@ book SYSTEM "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" LdapSaisie Version 0.3 - + &intro; &install; +&upgrade; + &conf; diff --git a/doc/upgrade/upgrade.docbook b/doc/upgrade/upgrade.docbook new file mode 100644 index 00000000..03c3c553 --- /dev/null +++ b/doc/upgrade/upgrade.docbook @@ -0,0 +1,439 @@ + + + +Mise à jour + +Cette section de la documentation détaille la procédure de mise à jour d'une installation existante +et regroupe des informations pratiques et utiles pour des montées de versions spécifiques entrainant par +exemple une perte de rétrocompatibilité de la configuration. + + + Procédure de mise à jour + + + Installation via paquet Debian + Lors d’une installation par paquet Debian, la mise à jour est grandement facilité par le packaging: + Il vous suffit de mettre à jour le paquet ldapsaisie : +apt update +apt install ldapsaisie + + + Une fois l’application mise à jour, prêté attention aux nouveautés et point de vigilances décrite dans + la section suivante. + + + + Installation à partir des sources + Lors d’une installation par à partir des sources, le script upgradeFromGit.sh permet + d’automatiser la mise à jour, à condition que vous ayez suivi la procédure d’installation à ce sujet. + + Ce script s’occupera alors de : + + Nettoyer working-tree Git des liens symboliques des fichiers locaux + (et éventuellement du thème) mis en place lors d’une précédente exécution ; + Vider le cache des templates ; + Mettre à jour le working-tree Git via un git pull + de la mise à jour ; + Installer des liens symboliques pour les fichiers locaux. En cas de fichier remplacant + un fichier livré avec l’application, le script vous notifiera en cas de changement intervenu dans le fichier + fourni avec l’application et vous permettra de le mettre à jour simplement votre fichier local (via un + vim -d) ; + Détecter des changements dans les fichiers MO (traduction) et de + déclencher dans ce cas un rechargement du serveur web pour prise en compte ; + Option : de compiler une version locale à jour de la documentation ; + + + + Une fois l’application mise à jour, prêté attention aux nouveautés et point de vigilances décrite dans + la section suivante. + + + + + + Mise à jour 2.4.1 -> 3.0.0 + +Cette mise à jour majeure apporte de nombreuses nouveautés auxquelles il est important de prêter attention. +Cette section ne parlera pas particulièrement de ces nouveautés, mais vous pouvez consulter le fichier debian/ldapsaisie.NEWS + pour cela. Cette section listera en outre les points de vigilances à avoir et les adaptations à apporter +sur votre configuration et votre code personnalisé. + + + Fichier config.inc.php + + ajout du paramètre ConsoleTable avec pour valeur par défaut sous + Debian /usr/share/php/Console/Table.php + + ajout du paramètre public_root_url avec pour valeur par défaut sous + Debian /ldapsaisie + paramètre $GLOBALS['defaultCSSfiles'] : il est nécessaire de modifier les + URLs des fichiers listés : seul le nom du fichier doit rester, sa localisation sera détectée automatiquement. Par + exemple, $GLOBALS['defaultCSSfiles']=array('../light-blue.css'); devient + $GLOBALS['defaultCSSfiles']=array('light-blue.css');. + + + + + + Fichiers CSS + + corriger les URL des images : url(../../images/default/find.png) devient + url(../image/find). Pour identifier les fichiers CSS concernés, vous pouvez utiliser les + commandes suivantes :grep -Er 'url\(.*images' /etc/ldapsaisie/local/css +grep -Er 'url\(.*\.(png|gif|jpg)' /etc/ldapsaisie/local/css + modification CSS page fatal_error (fichier base.css) : + #fatal_error devient #error + + + + + Fichiers PHP + + LSsession :: redirect() devient LSurl :: redirect(). + Pour identifier les fichiers CSS concernés, vous pouvez utiliser la commande suivante : + grep -Er 'LSsession *:: *redirect *\(' /etc/ldapsaisie/local/ + + Les inclusions de fichiers Javascript via LSsession :: addJSscript() doivent + être adaptées : + + LSsession :: addJSscript('../../local/includes/js/LSformElement_eetelephone.js'); + devient LSsession :: addJSscript('LSformElement_eetelephone.js'); + LSsession :: addJSscript('../../local/includes/js/LSformElement_eetelephone.js'); + devient LSsession :: addJSscript('LSformElement_eetelephone.js'); + LSsession :: addJSscript('click-to-dial_view.js', 'local/includes/js/'); + devient LSsession :: addJSscript('click-to-dial_view.js'); + + + + Pour identifier les fichiers concernés, vous pouvez utiliser les commandes suivantes : + grep -Er 'LSsession *:: *addJSscript\(.*local' /etc/ldapsaisie/local/ +grep -Er 'LSsession *:: *addJSscript\(.*\.\.\/' /etc/ldapsaisie/local/ + + + Les inclusions de fichiers CSS via LSsession :: addCssFile() doivent + être adaptées : le nom du fichier CSS uniquememnt doit être conservé (pas de chemin vers le fichier). + Pour identifier les fichiers concernés, vous pouvez utiliser les commandes suivantes : + grep -Er 'LSsession *:: *addCssFile\(.*local' /etc/ldapsaisie/local/ +grep -Er 'LSsession *:: *addCssFile\(.*\.\.\/' /etc/ldapsaisie/local/ + + + LSlog vs LSdebug : L’utilisation de LSdebug + est dépriorisée en faveur de LSlog. Ce dernier ajoute désormais la notion de + logger, permettant d’identifier la source des logs. Ce mécanisme permet la configuration + d’un niveau de log spécifique pour un logger donné, ainsi que la mise en place de filtres + au niveau des handers pour ne logger par exemple que certains loggers, + ou à l’inverse en exclure d’autres. + + + Pour vos classes personnalisées : si celles-ci héritent d’une classe standard, il est fort probable + qu’il soit possible d’utiliser des méthodes fournies par cette classe pour logguer au travers un + logger dédié (voir les méthodes log_debug, log_info, + …). À défaut, il est possible d’utiliser la classe LSlog_staticLoggerClass qui facilite + l’implémentation. + + + Pour vos &LSaddons; : il est conseillé d’utiliser un logger + LSaddon_[addon] dédié. Le logger peut facilement être récupéré de la + manière suivante : LSlog :: get_logger("LSaddon_[addon]") + Cette méthode retourne une référence au logger et il est possible d’appeler directement + une méthode de log, par exemple : + LSlog :: get_logger("LSaddon_[addon]") -> debug("message"); + + + + + + + + + Fichiers templates : + + + Changement de l’inclusion des templates + + + Le cas des fichiers top.tpl et bottom.tpl +{include file='ls:top.tpl'} + +[...] + +{include file='ls:bottom.tpl'} + devient : +{extends file='ls:base_connected.tpl'} +{block name="content"} + +[...] + +{/block} + + + Pages à l’état connecté uniquement (incluant le menu, l’entête…). + + + Fichiers avec entête HTML : + + + [...] + + + [...] + +]]> + devient : +{extends file='ls:base.tpl'} +{block name="body"} +[...] +{/block} + +Au besoin, si vous avez besoin : + + + + de remplacer les fichiers CSS chargés par défaut (base.css par exemple) : ajouter + le block css : + + {include file='ls:LSsession_css.tpl'} +{/block}]]> + + Ce block contient tous les CSS, y compris ceux gérés par LSsession :: addCssFile(). + Pensez à ajouter {include file='ls:LSsession_css.tpl'} pour conserver ces derniers. + + + + d’ajouter des infos dans ]]> : ajouter le block head + (vide par défaut) : +{block name="head"} +[...] +{/block} + + + + + d’ajouter des fichiers Javascript personnalisés : ajouter le block js (vide par +défaut): +{block name="js"} +[...] +{/block} + + Ce block sera ajouté APRÈS les autres fichiers Javascript chargés (ceux par + défaut et ceux ajoutés via LSsession :: addJSscript(). + + + + + +Autres fichiers remplacés : + + blank.tpl remplacé par base.tpl + empty.tpl remplacé par base_connected.tpl + accueil.tpl remplacé par homepage.tpl + + + +Pour identifier les fichiers concernés, vous pouvez utiliser la commande suivante : +grep -Er '(accueil|blank|empty|top|bottom)\.tpl' /etc/ldapsaisie/local/ + + + + + Fichiers templates fournis par defaut : + Vérifier les modifications des fichiers templates fourni avec l’application et que vous auriez personnalisé. + Pour cela, vous pouvez utiliser la commande suivante : + + Une attention particulière doit être porté aux fichiers login.tpl et + recoverpassword.tpl qui ont particulièrement changés. + + + + Corriger les URL des images : +../../images/default/find.png devient ../image/find + +Pour identifier les fichiers concernés, vous pouvez utiliser les commandes suivantes : +grep -Er 'images' /etc/ldapsaisie/local/templates +grep -Er '\.(png|gif|jpg)' /etc/ldapsaisie/local/templates + + + + + Le cas de variable de template <literal>{$LSsession_css}</literal> et <literal>{$LSsession_js}</literal> : + Ceci est déjà géré si vous étendez bien vos templates du fichier base.tpl (pour + les pages non-connectées) ou base_connected.tpl (pour les pages connectées). + + + + {$LSsession_css} doit être remplacé par {include file='ls:LSsession_css.tpl'} + + + + + {$LSsession_js} doit être remplacé par {include file='ls:LSsession_js.tpl'} + + + + + + + + + Tous les fichiers : Modification des URLs + + + + + + view.php : + + page recherche : view.php?LSobject=LSpeople devient + object/LSpeople + page d'un objet : view.php?LSobject=LSpeople&dn=$dn devient + object/LSpeople/$dn + + + + + + + addon_view.php : + addon_view.php?LSaddon=ee&view=copyContract devient + addon/ee/copyContract + + + + + + index_ajax.php : + + +Pour les méthodes Ajax de classes : +var data = { + template: 'LSformElement_eetelephone', + action: 'make_call', + telephoneNumber: tel, + name: name, +}; +new Request({url: 'index_ajax.php', data: data, onSuccess: ...}); + +Devient : +var data = { + telephoneNumber: tel, + name: name, +}; +new Request({url: 'ajax/class/LSformElement_eetelephone/make_call', data: data, onSuccess: ...}); + + +Pour les méthodes Ajax d'addon : +var data = { + addon: 'asterisk', + action: 'LSasterisk_make_call', + telephoneNumber: tel, + name: name, + nocache: new Date().getTime() +}; +new Request({url: 'index_ajax.php', data: data, onSuccess: ...}); + +Devient : +var data = { + telephoneNumber: tel, + name: name, + nocache: new Date().getTime() +}; +new Request({url: 'ajax/addon/asterisk/LSasterisk_make_call', data: data, onSuccess: ...}); + + + + + + + + + global_search.php : + global_search.php?refresh devient search?refresh + + + + + + index.php : + index.php?LSsession_recoverPassword devient index?LSsession_recoverPassword + + + + + + create.php : + create.php?LSobject=LSpeople devient object/LSpeople/create + + + + + + modify.php : + modify.php?LSobject=LSpeople&dn=$dn devient object/LSpeople/$dn/modify + + + + + + import.php : + import.php?LSobject=LSpeople devient object/LSpeople/import + + + + + + remove.php : + remove.php?LSobject=LSpeople&dn=$dn devient object/LSpeople/$dn/remove + + Avec validation : + remove.php?LSobject=LSpeople&dn=$dn&valid devient object/LSpeople/$dn/remove?valid + + + + + + select.php : + select.php?LSobject=LSpeople devient object/LSpeople/select + + + + + + custom_action.php : + custom_action.php?LSobject=LSpeople&dn=$dn&customAction=$customAction devient + object/LSpeople/$dn/custom_action/$customAction + + Avec validation : + custom_action.php?LSobject=LSpeople&dn=$dn&customAction=$customAction&valid devient + object/LSpeople/$dn/custom_action/$customAction?valid + + + + + + custom_search_action.php : + custom_search_action.php?LSobject=LSpeople&customAction=$customAction + devient object/LSpeople/custom_action/$customAction + + Avec validation : + custom_search_action.php?LSobject=LSpeople&customAction=$customAction&valid + devient object/LSpeople/custom_action/$customAction?valid + + + + + +Pour identifier les fichiers concernés, vous pouvez utiliser la commande suivante : +grep -Er '(index|global_search|view|select|create|modify|import|remove|index_ajax|custom_action|custom_search_action|addon_view)\.php' /etc/ldapsaisie/local/ + + + + + +