Manuel d'intégration

Cette page décrit comment intégrer des actions de modification sur les pages et contenus depuis le front-office dans une charte.

  1. Avant-propos
    1. Restrictions
    2. Les différents modes de modifications
    3. Chargement des scripts nécessaires
  2. Outils front-edition
    1. Basculer en mode modification
    2. Modification des contenus
      1. Modification champs par champs d'un contenu
      2. Modification de tous les champs simultanément
      3. Workflow des contenus
    3. Outils front-edition pour les contenus
      1. Ajouter un contenu à une page
      2. Etiqueter un contenu
      3. Modifier le cycle de vie d'un contenu
      4. Déplacer un contenu au sein de sa zone
      5. Récupérer l'état de workflow courant d'un contenu
      6. Récupérer le statut d'un contenu
    4. Outils front-edition pour les pages
      1. Ajout d'une page
      2. Suppression d'une page
      3. Renommer une page
      4. Etiqueter une page
      5. Déplacer une page sous une page cible
      6. Déplacer une page vers le haut ou vers le bas
      7. Récupérer le status des contenus de la page
      8. Publication programmée d'une page
    5. Outils front-edition pour les éléments de page
      1. Supprimer un contenu/service d'une page
  3. Helpers XSL
    1. AmetysFrontEditionHelper
      1. hasFrontEditionRight
      2. hasWorkflowRight
      3. getPageStatus
      4. getZoneItemPosition
      5. getZoneSize
      6. getContentWorkflowId
      7. getContentStatus
      8. isContentLive
    2. AmetysXSLTHelper
      1. isEditionMode
  4. Intégration avancée
    1. Surcharger le rendu HTML de tous les boutons
    2. Surcharger le rendu HTML d'un bouton
    3. Personnaliser les styles de paragraphe dans l'éditeur des textes riches

Avant-propos

Restrictions

  • Les boutons d'édition front-office sont visibles uniquement sur le front.
  • Les outils de front-edition ne peuvent être intégrés que sur des pages non-cacheables
  • Les outils et scripts front-edition ne sont chargés et visibles que pour les utilisateurs ayant le droit "Modification depuis le site"

Les différents modes de modifications

Il y a 2 modes d'intégration des outils de front-edition:

  • mode wiki: les modifications effectuées depuis le front sont directement en ligne (travail sur la version Live)
  • mode edition: les modifications effectuées depuis le front n'impacte que la version brouillon (travail sur la version default)
    Dans ce mode il est nécessaire d'ajouter un bouton "passer en mode modification" pour basculer sur la version brouillon et un bouton "Publier" pour valider les modifications en ligne.

Indépendamment de ces 2 modes, il existe également 2 modes de modification des contenus:

  • mode simple: la modification des champs se fait individuellement champ par champ (mode par défaut)
  • mode complet: la modification de l'ensemble des champs se fait dans un seul formulaire

Chargement des scripts nécessaires

Le plugin fournit un fichier XSL contenant les templates XSL à appeler pour chaque action (ajout de page, ajout de contenu, ...)
Il est donc nécessaire en premier lieu d'importer ce fichier:

<xsl:import href="plugin:front-edition://stylesheets/front-edition.xsl"/>

Puis pour chaque page intégrant des outils de front-edition, il est nécessaire de faire appel au template XSL "ametys-front-edition-head" dans la section <head> du template.
Ce template XSL permet de charger les scripts JS nécessaires au fonctionnement des outils front-edition.

Ses paramètres sont les suivants:

  • start : Indique si il faut charger directement les fichiers javascripts nécessaires à l'édition (défaut : start)
    • false : Ne charge que le strict minimum, le chargement de la page n'est pas impacté. Il vous faudra insérer un bouton pour démarrer la modification front-edition. Ce bouton doit appeler AmetysFrontEdition.start(); et c'est seulement après cet appel que la modification sera possible.
    • start : Chargera les fichiers lors de la première action de modification. Le chargement de la page sera peu impacté par front-edition, mais la première modification sera lente.
    • load : Chargera les fichiers dès le chargement de la page. Le chargement de la page sera ralenti mais la première modification sera immédiate.
    • debug : Ne pas utiliser (uniquement pour le développement du plugin front-edition)
  • edition-mode-only: L'édition est limitée au mode edition (défaut : 'true'). Mettre à false() pour activer le mode wiki (modifications automatiquement en ligne)
  • editActionId : identifiant de l'action de workflow utilisée pour la modification champ par champ (défaut : 2).  Attention si le mode wiki est utilisé (edition-mode-only=false) l'action de workflow d'édition doit également validé le contenu.
  • insertAttachmentActionId : identifiant de l'action de workflow qui sera utilisé lors de l'upload de fichier joint à un contenu (défaut : 12)
  • theme [à partir de 1.6.0] : le thème ExtJS a chargé sous la forme d'un path vers un dossier (optionnel)
  • js-loading-html [à partir de 1.6.0] : paramètre avancé pour personnaliser le code HTML utilisé pour l'écran de chargement de front-edition. Par défaut il vaut <div id="front-edition-js-loading-div" class="front-edition-js-loading|front-edition-js-loaded">
  • start-callback [à partir de 1.6.1]: fonction de callback optionelle qui sera appelée après l'initialisation de front-edition

Exemple:

<xsl:call-template name="ametys-front-edition-head">
    <xsl:with-param name="start">load</xsl:with-param>
    <xsl:with-param name="editActionId">42</xsl:with-param>
    <xsl:with-param name="insertAttachmentActionId">42</xsl:with-param>
    <xsl:with-param name="edition-mode-only" select="false()"/>
</xsl:call-template>

Outils front-edition

Note
Les boutons ne s'afficheront que si vous avez les droits nécessaires liés la fonctionnalité (ex: droit d'ajouter une page) en plus du droit de modification en ligne (Front_Edition_Access_Right)

Basculer en mode modification

Pour insérer un bouton permettant de basculer en mode modification (et inversement), appelez le template "ametys-front-edition-insert-toggle-edition-mode-button".
Les paramètres sont les suivants:

  • class : classe css qui sera ajoutée au bouton. Par défaut front-edition-toggle-edition-mode

Exemple:

<xsl:if test="edition:hasFrontEditionRight()">
    <xsl:call-template name="ametys-front-edition-insert-toggle-edition-mode-button" />
</xsl:if>

Pour rappel il existe 2 modes de modifications: le mode wiki qui travaille sur la version validée du site, le mode edition qui travaille sur la version brouillon du site.
Ce bouton n'est nécessaire que lorsque l'on souhaite utiliser le mode edition.

Modification des contenus

Pour permettre la modification des champs d'un contenu, il suffit d'ajouter un attribut "data-ametys-metadata" sur l'élement html affichant le champ.

L'attribut "data-ametys-metadata" contient l'identifiant du contenu et le chemin de la métadonnée, séparés par un point virgule ;

A la fin du chargement de front-edition, un bouton "modifier" sera automatiquement ajouté aux champs modifiables (en tenant compte des droits de l'utilisateur connecté) pour permettre leur modification.

La classe css "ametys-front-edition-possible" est automatiquement ajouté sur tous les éléments html avec l'attribut "data-ametys-metadata" pour lesquels la modification est possible. Au survol la classe "ametys-front-edition-hover" est également ajoutée.
Un <button class="ametys-front-edition-button">Modifier</button> est ajouté dans l'élément.


Pour rendre ce bouton visible uniquement au survol, ajoutez simplement la règle css suivante :

.ametys-front-edition-button { display: none }
.ametys-front-edition-hover .ametys-front-edition-button { display: inline-block }

Exemple pour modifier le titre du contenu:

<div class="content-title rs-editable__pseudo-text" data-ametys-metadata="{@id};title"><xsl:value-of select="metadata/title"/></div>  

Le code HTML généré sera:

<div class="content-title rs-editable__pseudo-text ametys-front-edition-possible" data-ametys-metadata="content://a0a38c54-e6d4-48ec-a519-0f60cc5e7a8b;title">
    <button class="ametys-front-edition-button">
        <span class="ametys-front-edition-button-text">Modifier</span>
    </button>
    Titre du contenu
</div> 

Comment autoriser la modification des champs vides ?

Seul un champ affiché peut être modifié.

Pour pouvoir modifier un champ vide, il est nécessaire d'ajouter un "placeholder", uniquement pour les utilisateurs autorisés à modifier ce champ.

Pour se faire, 

  • si on est en mode édition (travail sur la version brouillon):
    on affiche les placeholders sans tenir compte des droits de l'utilisateur courant. Cette solution est simple à mettre en place.

    Exemple:

<xsl:choose>
    <xsl:when test="metadata/title != ''">
        <span class="content-title summary" data-ametys-metadata="{@id};title"><xsl:value-of select="metadata/title"/></span> 
    </xsl:when>
    <xsl:when test="ametys:isEditionMode()">
        <!-- Placeholder -->
        <span class="content-title summary" data-ametys-metadata="{@id};title">Ajouter un titre</span> 
    </xsl:when>
</xsl:choose>
  • si on est en mode wiki (travail sur la version validée):
    les placeholders sont toujours présents mais cachés dans le code HTML et doivent être affichés en javascript pour les utilisateurs ayant droit.

    Exemple de mise en place à partir de la version 1.6.1+
<xsl:choose>
    <xsl:when test="metadata/title != ''">
        <span class="content-title summary" data-ametys-metadata="{@id};title"><xsl:value-of select="metadata/title"/></span> 
    </xsl:when>
    <xsl:otherwise>
        <!-- Placeholder (caché par défaut) -->
        <span style="display: none" class="content-title summary front-edition-placeholder" data-ametys-metadata="{@id};title">Ajouter un titre</span> 
    </xsl:otherwise>
</xsl:choose>

Le plugin doit être chargé en spécifiant une fonction de callback à l'appel existant. Cette fonction JS va ici rendre visible les "placeholder" qui contiennent le bouton de modification  (identifié par la classe css "ametys-front-edition-button").

<xsl:call-template name="ametys-front-edition-head">
    <xsl:with-param name="start">load</xsl:with-param>
    ...
    <xsl:with-param name="start-callback">function() { $j('.front-edition-placeholder .ametys-front-edition-button').parent('.front-edition-placeholder').show(); }</xsl:with-param>
</xsl:call-template>

Note importante
La taille du champ du formulaire permettant la modification de la donnée sera la même que la taille de l'élément html portant l'attribut "data-ametys-metadata".
Il est donc conseillé d'ajouter cet attribut sur des éléments <div> plutôt que des <span> et de prévoir une largeur minimun (et une hauteur minimun pour les champs de type texte riche ou texte multiligne).

A ce jour, les types supportés par la modification front-office sont les suivants :

  • STRING
  • DATE
  • DATETIME
  • RICH_TEXT
  • CONTENT
  • FILE

Depuis la version 1.11 (Ametys 4.6) il existe un widget image qui est pris par défaut pour les type FILE ayant le filtre "image" activé. Ce widget dispose d'un paramètre "shape" qui peut prendre :
- la valeur "circle" si le widget doit s'afficher de manière ronde, pour une photo de profil par exemple.
- la valeur "square" si le widget doit être forcé en image carré
- la valeur "rectangle" par défaut pour une image sans taille forcée

Widget et paramètres

Depuis la version 1.11 (Ametys 4.6), il est possible de spécifier un widget avec l'attribut "data-ametys-widget" pour remplacer la valeur par défaut. Seuls les widgets prévus par le plugin Front Edition sont disponibles.

Depuis la version 1.11 (Ametys 4.6), il est possible de spécifier des paramètres de widgets avec l'attribut "data-ametys-widget-params" sous la forme d'un JSON. Attention, au sein d'une XSL à échapper les caractères accolades.

<div data-ametys-metadata="{/view/content/@id};illustration/image" 
  data-ametys-widget-params="{{ &quot;shape&quot;: &quot;circle&quot; }}">

Modification champs par champs d'un contenu

Il n'y a rien de plus à faire pour utiliser ce mode de modification.
Les champs du contenu sont modifiés individuellement et les modifications sont enregistrées à la chaque modification.

Modification de tous les champs simultanément

Dans ce mode, il faut ajouter un bouton "Modifier" général et masquer les boutons "Modifier" individuels.

Le template "ametys-front-edition-edit-content-button" affiche un bouton permettant de modifier tous les champs visibles d'un contenu dans un même formulaire et d'afficher une barre d'outils avec les actions de workflow pouvant être effectuées.

Les paramètres sont les suivants.

  • content-id : identifiant du contenu à modifier
  • workflow-ids : liste des actions de workflow à rendre disponible. Par défaut [2]
    • Soit une liste d'entiers [2, 4, 5], les nom des boutons seront les noms des actions définies dans le workflow
    • Il est aussi possible de surcharger les noms d'actions :  [{id:2,text:'<xsl:value-of select="$workflow-2-text" />'}, 42]. Le texte doit être décodé dans la balise (voir exemple ci dessous)
  • button-text : texte/html du bouton
  • title-i18n : clef i18n à utiliser pour le tooltip du bouton
  • class : classe css à ajouter au bouton. Par défaut front-edition-edit-content
  • edition-mode-only : false() pour autoriser le bouton même en dehors du mode édition (par défaut à true())

Exemple avec une surcharge du texte pour l'action de modification

<xsl:variable name="workflow-2-text">                 
    <xsl:value-of select="ametys:escapeJS(ametys:translate(concat('skin.', ametys:skin(), ':FRONT_EDITION_SAVE_CONTENT')))" />                 
</xsl:variable>                 
<xsl:call-template name="ametys-front-edition-edit-content-button">                 
    <xsl:with-param name="content-id" select="@id"/>                 
    <xsl:with-param name="workflow-ids">[{id:2,text:'<xsl:value-of select="$workflow-2-text" />'}, 42]</xsl:with-param>                 
</xsl:call-template>                 

Pour masquer les boutons de modification individuels il suffit de rajouter une règle css:

.ametys-front-edition-button { display: none; }

Workflow des contenus

Pour les contenus pour lesquelles on souhaite autoriser une modification depuis le front-office, il est fortement conseillé d'ajouter dans le workflow une action permettant :

  • soit de valider automatiquement le contenu à chaque modification si la version courante est la version validée
  • soit de garder le contenu à l'état brouillon si la version courante est une version brouillon

Voici un exemple d'action avec résultat conditionnel, en supposant que "1" est l'état brouillon et "3" l'état validé:

<action id="42" name="plugin.default-workflow:WORKFLOW_ACTION_EDIT_FO">                 
    <restrict-to>                 
        <conditions type="AND">                 
            <condition type="avalon">                 
                <arg name="role">org.ametys.cms.workflow.ContentCheckRightsCondition</arg>                 
                <arg name="right">Workflow_Rights_Edition_Online</arg>                 
            </condition>                 
            <condition type="avalon">                 
                <arg name="role">org.ametys.cms.workflow.LockCondition</arg>                 
            </condition>                 
        </conditions>                 
    </restrict-to>                 
    <pre-functions>                 
        <function type="avalon">                 
            <arg name="role">org.ametys.cms.workflow.EditContentFunction</arg>                 
        </function>                 
    </pre-functions>                 
    <results>                 
        <!-- Modification et validation -->                 
        <result old-status=" " status=" " step="3">                 
            <conditions type="AND">                 
                <condition type="avalon">                 
                    <arg name="role">org.ametys.cms.workflow.ContentCurrentStepCondition</arg>                 
                    <arg name="step">3</arg>                 
                </condition>                 
                <condition type="avalon">                 
                    <arg name="role">org.ametys.cms.workflow.ValidateMetadataCondition</arg>                 
                </condition>                 
            </conditions>                 
            <post-functions>                 
                <!-- edition -->                 
                <function type="avalon">
                    <arg name="role">org.ametys.cms.workflow.extensions.ExtensibleFunction</arg>
                    <arg name="extension-point">org.ametys.cms.workflow.extensions.PostContentEditionFunctionsExtensionPoint</arg>
                </function>                
                <function type="avalon">                 
                    <arg name="role">org.ametys.cms.workflow.SetCurrentStepIdAndNotifyFunction</arg>                 
                </function>                 
                <function type="avalon">                 
                    <arg name="role">org.ametys.cms.workflow.CreateVersionFunction</arg>                 
                </function>                 
                <!-- validation -->                 
                <function type="avalon">
                    <arg name="role">org.ametys.cms.workflow.extensions.ExtensibleFunction</arg>
                    <arg name="extension-point">org.ametys.cms.workflow.extensions.PostContentValidationFunctionsExtensionPoint</arg>
                </function>                
                <function type="avalon">                 
                    <arg name="role">org.ametys.web.workflow.ValidateContentFunction</arg>                 
                </function>                 
                <function type="avalon">                 
                    <arg name="role">org.ametys.cms.workflow.ValidationStepFunction</arg>                 
                </function>                 
            </post-functions>                 
        </result>                 
        <!-- Modification uniquement -->                 
        <unconditional-result old-status=" " status=" " step="1">                 
            <post-functions>                 
                <!-- edition -->                 
                <function type="avalon">
                    <arg name="role">org.ametys.cms.workflow.extensions.ExtensibleFunction</arg>
                    <arg name="extension-point">org.ametys.cms.workflow.extensions.PostContentEditionFunctionsExtensionPoint</arg>
                </function>                   
                <function type="avalon">                 
                    <arg name="role">org.ametys.cms.workflow.SetCurrentStepIdAndNotifyFunction</arg>                 
                </function>                 
                <function type="avalon">                 
                    <arg name="role">org.ametys.cms.workflow.CreateVersionFunction</arg>                 
                </function>                 
            </post-functions>                 
        </unconditional-result>                 
    </results>                 
</action>                 

Outils front-edition pour les contenus

Important
Les outils décrits dans ce chapitre ne doivent pas être appelés depuis la vue du content car cette vue est mise en cache et cela peut engendrer de graves effets de bord. (cf https://issues.ametys.org/browse/FRONTEDIT-78 )

Pour les appeler, mettez votre code dans zone-item-before ou zone-item-after de votre template (voir Ecriture d'un gabarit)

Ajouter un contenu à une page

Pour insérer un bouton permettant d'ajouter un contenu, utilisez le template "ametys-front-edition-add-content-button" avec les paramètres suivants:

  • page-id : identifiant de la page
  • content-types : type(s) de contenu à créer. Si plusieurs types sont à déclarer sur le même contenu, les séparer par des point-virgule ;
  • zone-name : nom de la zone dans laquelle ajouter le contenu. Par défaut : default
  • content-title : titre par défaut du contenu
  • init-workflow-action-id : identifiant de l'action de workflow d'initialisation. Par défaut : 1
  • workflow-name : nom du workflow lié à ce contenu. Par défaut : content
  • locale : langue du contenu
  • button-text : texte/html du bouton
  • title-i18n : clef i18n à utiliser pour le tooltip du bouton
  • class : classe css à ajouter au bouton. Par défaut front-edition-add-content
  • edition-mode-only : false() pour autoriser le bouton même en dehors du mode édition (par défaut à true())

Exemple du bouton permettant de créer un nouvel article:

<xsl:if test="ametys:isEditionMode()">
    <xsl:call-template name="ametys-front-edition-add-content-button">
        <xsl:with-param name="page-id" select="/cms/page/@id"/>
        <xsl:with-param name="content-types" select="'org.ametys.web.default.Content.article'"/>
        <xsl:with-param name="zone-name" select="'right'"/>
        <xsl:with-param name="content-title"><i18n:text i18n:key="FRONT_EDITION_EMPTY_ARTICLE_TITLE" i18n:catalogue="skin.{$skin}"/></xsl:with-param>
        <xsl:with-param name="locale" select="$lang"/>
        <xsl:with-param name="button-text"><i18n:text i18n:key="FRONT_EDITION_NEW_ARTICLE" i18n:catalogue="skin.{$skin}"/></xsl:with-param>
    </xsl:call-template>
</xsl:if>

Etiqueter un contenu

Pour insérer un bouton permettant d'étiqueter un contenu, utilisez le template "ametys-front-edition-insert-tag-content-button" avec les paramètres suivants:

  • content-id : identidiant du contenu à étiqueter
  • button-text : texte/html du bouton
  • title-i18n : clef i18n à utiliser pour le tooltip du bouton
  • class : classe css à ajouter au bouton. Par défaut front-edition-tag-content
  • edition-mode-only : false() pour autoriser le bouton même en dehors du mode édition (par défaut à true())

Exemple:

<xsl:if test="ametys:isEditionMode() and $contentId">
    <xsl:call-template name="ametys-front-edition-insert-tag-content-button">
        <xsl:with-param name="content-id" select="$contentId" />
        <xsl:with-param name="button-text"><i18n:text i18n:key="FRONT_EDITION_ACTION_TAG_CONTENT_LABEL" i18n:catalogue="skin.{$skin}"/></xsl:with-param>
    </xsl:call-template>
</<xsl:if>

Modifier le cycle de vie d'un contenu

Pour insérer un bouton permettant d'effectuer une action de workflow sur un contenu, utilisez le template "ametys-front-edition-content-workflow-button" avec les paramètres suivants:

  • content-id : identifiant du contenu sur lequel exécuter l'action de workflow
  • workflow-id : identifiant de l'action workflow à exécuter
  • workflow-text : texte à afficher (par défaut, libellé de l'action définie dans le workflow)
  • title-i18n : clef i18n à utiliser comme titre du bouton
  • class : classe css à ajouter au bouton. Par défaut front-edition-workflow-action
  • edition-mode-only : false() pour autoriser le bouton même en dehors du mode édition (par défaut à true())

Exemple d'ajout de 2 boutons pour dépublier ou publier un contenu en fonction de son état courant:

<xsl:if test="ametys:isEditionMode() and $contentId">
    <!-- get content status -->
    <xsl:variable name="status">
        <xsl:call-template name="ametys-front-edition-get-content-validation-status">
            <xsl:with-param name="content-id" select="$contentId"/>
        </xsl:call-template>
    </xsl:variable>

    <xsl:choose>
        <xsl:when test="$status = 'validated'">
            <!-- inseration d'un bouton "dépublier"
            <xsl:call-template name="ametys-front-edition-content-workflow-button">
                <xsl:with-param name="content-id" select="$contentId"/>
                <xsl:with-param name="workflow-id" select="'10'"/>
                <xsl:with-param name="workflow-text"><i18n:text i18n:key="FRONT_EDITION_ACTION_UNPUBLISH_CONTENT_LABEL" i18n:catalogue="skin.{$skin}"/></xsl:with-param>
                <xsl:with-param name="title-i18n">skin.<xsl:value-of select="$skin"/>:FRONT_EDITION_ACTION_TO_DRAFT_TITLE</xsl:with-param>
                <xsl:with-param name="class">front-edition-workflow-action-validated</xsl:with-param>
            </xsl:call-template>
        </xsl:when>
        <xsl:otherwise>
            <!-- insertion d'un bouton "publier" -->
            <xsl:call-template name="ametys-front-edition-content-workflow-button">
                <xsl:with-param name="content-id" select="$contentId"/>
                <xsl:with-param name="workflow-id" select="'4'"/>
                <xsl:with-param name="workflow-text"><i18n:text i18n:key="FRONT_EDITION_ACTION_PUBLISH_CONTENT_LABEL" i18n:catalogue="skin.{$skin}"/></xsl:with-param>
                <xsl:with-param name="title-i18n">skin.<xsl:value-of select="$skin"/>:FRONT_EDITION_ACTION_TO_PUBLISH_TITLE</xsl:with-param>
                <xsl:with-param name="class">front-edition-workflow-action-draft</xsl:with-param>
                </xsl:call-template>
        </xsl:otherwise>
    </xsl:choose>
</xsl:if>

Déplacer un contenu au sein de sa zone

Pour insérer un bouton permettant de déplacer un contenu dans sa zone, utilisez le template "ametys-front-edition-move-content-button" avec les paramètres suivants:

  • zone-item-id : identifiant du zoneItem à déplacer
  • zone-name : nom de la zone parente dans laquelle déplacer le contenu
  • offset : -1 pour monter d'un niveau, 1 pour descendre d'un niveau
  • button-text : texte/html du bouton
  • title-i18n : clef i18n à utiliser pour le tooltip du bouton
  • class : classe css à ajouter au bouton. Par défaut front-edition-move-content-up ou front-edition-move-content-down selon le sens de l'offset
  • edition-mode-only : false() pour autoriser le bouton même en dehors du mode édition (par défaut à true())

Récupérer l'état de workflow courant d'un contenu

Pour récupérer l'identifiant de l'état du workflow d'un contenu, utilisez le template "ametys-front-edition-get-content-workflow-step" avec les paramètres suivants:

  • content-id : identifiant du contenu
  • prefix : texte qui préfixera le retour (optionnel)

Retourne l'identifiant l'état du workflow pour ce contenu, préfixé par prefix

Récupérer le statut d'un contenu

Pour récupérer le statut d'un contenu, utilisez le template "ametys-front-edition-get-content-validation-status" avec les paramètres suivants:

  • content-id : identifiant du contenu
  • prefix : texte qui préfixera le retour

Retourne "[prefix]validated" si le contenu est validé ou "[prefix]draft" sinon.

Exemple:

<xsl:variable name="status">
    <xsl:call-template name="ametys-front-edition-get-content-validation-status">
         <xsl:with-param name="content-id" select="$contentId"/>
     </xsl:call-template>
</xsl:variable>

Outils front-edition pour les pages

Ajout d'une page

Pour insérer un bouton permettant l'ajout d'une page, utilisez le template XSL "ametys-front-edition-insert-create-page-button". Les principaux paramètres sont les suivants:

Exemple

<xsl:call-template name="ametys-front-edition-insert-create-page-button">                 
    <xsl:with-param name="page-id" select="@sitemap:id"/>                 
    <xsl:with-param name="callback">someAwesomeCallBackFunction</xsl:with-param>                 
    <xsl:with-param name="config">{                 
        "force": true,                
        "show-card-type" : false,         
        "show-card-content" : false,         
        "show-card-tags" : false,         
        "default-pagetype" : "template",                 
        "default-template" : "page3col",                 
        "default-pagecontent-type" : "contenttype",                 
        "default-contenttype" :  "org.ametys.plugins.news.Content.news",                 
        "default-content-title" : "Jolie nouvelle actualité",                 
        "default-contenttype-label" : "Actualité"                 
    }</xsl:with-param>                 
</xsl:call-template>                 

La configuration par défaut est

{                 
    'pagetype-template' : true,                 
    'pagetype-redirection-cms' : true,                 
    'pagetype-redirection-http' : false,                 
    'pagetype-blank' : false,                 
    'pagecontent-card-content-filter' :                 
    [                 
        'org.ametys.plugins.news.Content.news',                 
        'org.ametys.web.default.Content.article'                 
    ],                 
    'pagecontent-service' : false                 
}                 

Il n'est pas nécessaire de tout re-déclarer, si un seul paramètre est à changer, il suffit de le passer lui dans la conf (une fusion de la conf passée et de la conf par défaut est faite).

Avant Ametys 4.3, il suffisait de spécifier "force":true pour n'afficher que la carte de choix du titre de la page, il faut maintenant spécifier explicitement l'ensemble des cartes à masquer, la liste est : show-card-type, show-card-content, show-card-tags.
force sert à forcer l'application des valeurs par défaut, dans la plupart des cas il est utile de le mettre quand on masque des cartes

Exemple 1: création d'une page et d'un contenu Actualité avec sélection d'étiquette parmi une liste restreinte

<xsl:call-template name="ametys-front-edition-insert-create-page-button">
    <xsl:with-param name="page-id" select="$rootNewsPageId"/>
    <xsl:with-param name="title-i18n"><xsl:value-of select="concat('skin.', $skin, ':SKIN_HOME_NEWS_CAROUSEL_ADD_NEWS_BTN_TITLE')"/></xsl:with-param>
    <xsl:with-param name="button-text"><h2 class="ametys-truncate" data-lines="2"><i18n:text i18n:key="SKIN_HOME_NEWS_CAROUSEL_ADD_NEWS" i18n:catalogue="skin.{$skin}"/></h2><span class="ametys-portlet__content_newproj_icn"><i class="fas fa-pen"></i></span></xsl:with-param>
    <xsl:with-param name="edition-mode-only" select="false()"/>
    <xsl:with-param name="class">ametys-portlet__content_newproj</xsl:with-param>
    <xsl:with-param name="callback">function(page)
    {
        var path = AmetysFrontEdition.CONTEXT_PATH + "/" + AmetysFrontEdition.LOCALE + "/" +         page.getPath() + ".html";
        window.location.href = path;
    }
    </xsl:with-param>
    <xsl:with-param name="config">{
        "title": "<xsl:value-of select="ametys:escapeJS(ametys:translate(concat('skin.', $skin, ':SKIN_HOME_NEWS_CAROUSEL_ADD_NEWS_DIALOG_TITLE')))"/>",
        "force": true,
        "workflowInitActionId": "14", 
        "show-card-content" : false, 
        "show-card-type" : false, 
        "show-card-tags" : true,
        "pagecontent-card-tags-categories-filter":         ["provider_org.ametys.plugins.workspaces.categories.CategoryTagProvider", "NEWS_CATEGORIES"],
        "pagecontent-card-tags-categories-filter-only-subcategories": false,
        "default-pagetype" : "template",
        "default-template" : "page",
        "default-zone" : "default",
        "default-pagecontent-type" : "contenttype",
        "default-contenttype" : "org.ametys.plugins.news.Content.news",
        "default-content-title" : "<xsl:value-of select="ametys:escapeJS(ametys:translate(concat('skin.', $skin, ':SKIN_HOME_NEWS_CAROUSEL_ADD_NEWS_DEFAULT_TITLE')))"/>",
        "default-contenttype-label" : "<xsl:value-of select="ametys:escapeJS(ametys:translate(concat('skin.', $skin, ':SKIN_HOME_NEWS_CAROUSEL_ADD_NEWS_CONTENT_TYPE_LABEL')))"/>",
        "pagecontent-service" : false}
     </xsl:with-param>
</xsl:call-template>

Dans cet exemple:

  • Le titre de la boite de dialogue est surchargée
  • Le type de contenu à créer est imposé (actualité)
  • L'assistant sera composé de 2 pages: une pour définir le titre de la page à créer, une seconde pour sélectionner des étiquettes parmi une liste d'étiquettes filles de l'étiquette "NEWS_CATEGORIES" et parmi une liste des étiquettes du provider d'étiquettes "org.ametys.plugins.workspaces.categories.CategoryTagProvider"

Suppression d'une page

Pour insérer un bouton permettant la suppression d'une page, utilisez le template XSL "ametys-front-edition-insert-delete-page-button".
Les paramètres sont les suivants:

  • page-id: identifiant de la page à supprimer
  • page-title: titre de la page à indiquer dans la boîte de dialogue
  • button-text: texte du bouton
  • title-i18n: clef i18n à utiliser pour le tooltip du bouton
  • class: classe css à ajouter au bouton. Par défaut front-edition-delete-page
  • edition-mode-only: false() pour autoriser le bouton même en dehors du mode édition (par défaut à true())

Si la page contient des contenus, ces derniers seront automatiquement supprimés sauf s'ils sont partagés.

<xsl:call-template name="ametys-front-edition-insert-delete-page-button">
    <xsl:with-param name="page-id" select="ametys:pageId()"/>
    <xsl:with-param name="button-text"><span class="btn-icon docicon-delete"></span><span class="btn-txt"><i18n:text i18n:key="SKIN_FO_EDITION_PAGE_DELETE" i18n:catalogue="skin.{$skin}"/></span></xsl:with-param>
    <xsl:with-param name="edition-mode-only" select="false()"/>
</xsl:call-template>

Renommer une page

Pour insérer un bouton permettant le renommage d'une page, utilisez le template XSL "ametys-front-edition-insert-rename-page-button".
Les paramètres sont les suivants:

  • page-id : identifiant de la page à renommer
  • button-text : texte/html du bouton
  • title-i18n : clef i18n à utiliser pour le tooltip du bouton
  • class : classe css à ajouter au bouton. Par défaut front-edition-rename-page
  • edition-mode-only : false() pour autoriser le bouton même en dehors du mode édition (par défaut à true())

Exemple

<xsl:call-template name="ametys-front-edition-insert-rename-page-button">
    <xsl:with-param name="page-id" select="ametys:pageId()"/>
    <xsl:with-param name="button-text"><span class="btn-icon docicon-rename g-font-size-16 g-mr-10"></span><span class="btn-txt"><i18n:text i18n:key="SKIN_FO_EDITION_RENAME" i18n:catalogue="skin.{$skin}"/></span></xsl:with-param>
    <xsl:with-param name="edition-mode-only" select="false()"/>
</xsl:call-template>

Etiqueter une page

Pour insérer un bouton permettant l'étiquetage d'une page, utilisez le template XSL "ametys-front-edition-insert-tag-page-button".
Les paramètres sont les suivants:

  • page-id : identidiant de la page à tagger
  • button-text : texte/html du bouton
  • title-i18n : clef i18n à utiliser pour le tooltip du bouton
  • class : classe css à ajouter au bouton. Par défaut front-edition-tag-page
  • edition-mode-only : false() pour autoriser le bouton même en dehors du mode édition (par défaut à true())

Exemple:

<xsl:call-template name="ametys-front-edition-insert-tag-page-button">
    <xsl:with-param name="page-id" select="ametys:pageId()"/>
    <xsl:with-param name="button-text"><span class="btn-icon docicon-tag g-font-size-16 g-mr-10"></span><span class="btn-txt"><i18n:text i18n:key="SKIN_FO_EDITION_TAG" i18n:catalogue="skin.{$skin}"/></span></xsl:with-param>
    <xsl:with-param name="title-i18n" select="concat('skin.', $skin, ':SKIN_FO_EDITION_TAG')"/>
    <xsl:with-param name="edition-mode-only" select="false()"/>
</xsl:call-template>

Déplacer une page sous une page cible

Pour insérer un bouton permettant de déplacer une page dans l'arborescence vers une page cible, utilisez le template XSL "ametys-front-edition-insert-move-page-button".
Les paramètres sont les suivants:

  • page-id : identidiant de la page à déplacer
  • page-parent-id : identifiant de la nouvelle page parente
  • page-new-pos : position de la page dans son nouveau parent (entier)
  • button-text : texte/html du bouton
  • class : classe css à ajouter au bouton
  • link-title-i18n : clef i18n à utiliser comme titre du bouton
  • edition-mode-only : false() pour autoriser le bouton même en dehors du mode édition (par défaut à true())

Ce template n'est à utiliser que pour changer de parent, pour un déplacement au sein du même parent (ré-ordonnancement), il est conseillé d'utiliser les 2 templates ci-après.

Déplacer une page vers le haut ou vers le bas

Pour insérer un bouton permettant de déplacer une page vers le haut ou vers le bas tout en conservant son parent, utilisez respectivement les template XSL "ametys-front-edition-insert-move-page-up-button" et "ametys-front-edition-insert-move-page-down-button".

Les paramètres sont les suivants:

  • page-id : identifiant de la page à déplacer
  • page-parent-id : identifiant de la page parente
  • page-pos : position actuelle de la page (servira à valider l'affichage ou non du bouton, et calculera la future position) (le compte des pages commence à 1 et non à zéro)
  • number-of-pages: nombres de pages filles sous la page parente
  • button-text : texte/html du bouton
  • title-i18n : clef i18n à utiliser pour le tooltip du bouton
  • class : classe css à ajouter au bouton. Par défaut front-edition-move-page-up
  • edition-mode-only : false() pour autoriser le bouton même en dehors du mode édition (par défaut à true())

Exemple:
Dans l'exemple ci-dessous, un menu "Déplacer" comprend 2 items pour déplacer la page vers le haut ou le bas

<xsl:variable name="currentPage" select="/cms/inputData/sitemap//page[@sitemap:current = 'true']"/>
<xsl:variable name="parentId" select="$currentPage/parent::*[local-name() = 'page' or local-name() = 'sitemap']/@sitemap:id"/>
<xsl:variable name="currentPos" select="count($currentPage/preceding-sibling::page) + 1"/>
<xsl:variable name="nbPages" select="count($currentPage/../page)"/>

<xsl:if test="$nbPages &gt; 1">
    <li class="morelist__has-submenu">
        <a href="#!">
            <span class="btn-icon docicon-move g-font-size-16 g-mr-10"></span>
            <span class="btn-txt">Déplacer la page</span>
        </a>
        <ul class="list-unstyled user__panel__dropdown g-brd-around g-brd-secondary-light-v2 g-bg-white rounded g-py-7 u-shadow-v1-3 sub-morelist">
            <xsl:call-template name="ametys-front-edition-insert-move-page-up-button">
                <xsl:with-param name="page-id" select="$currentPage/@sitemap:id"/>
                <xsl:with-param name="page-parent-id" select="$parentId"/>
                <xsl:with-param name="page-pos" select="$currentPos"/>
                <xsl:with-param name="number-of-pages" select="$nbPages"/>
                <xsl:with-param name="button-text"><span class="move-up-icon"></span><span>vers le haut</span></xsl:with-param>
                <xsl:with-param name="class">g-py-5 g-px-20 g-font-size-14</xsl:with-param>
                <xsl:with-param name="edition-mode-only" select="false()"/>
            </xsl:call-template>

            <xsl:call-template name="ametys-front-edition-insert-move-page-down-button">
                <xsl:with-param name="page-id" select="$currentPage/@sitemap:id"/>
                <xsl:with-param name="page-parent-id" select="$parentId"/>
                <xsl:with-param name="page-pos" select="$currentPos"/>
                <xsl:with-param name="number-of-pages" select="$nbPages"/>
                <xsl:with-param name="button-text"><span class="move-down-icon"></span><span>vers le bas</xsl:with-param>
                <xsl:with-param name="class">g-py-5 g-px-20 g-font-size-14</xsl:with-param>
                <xsl:with-param name="edition-mode-only" select="false()"/>
            </xsl:call-template>
        </ul>
    </li>
</xsl:if>

Récupérer le status des contenus de la page

Pour récupérer le status des contenus d'une page, utilisez le template XSL "ametys-front-edition-get-page-status".

Les paramètres sont les suivants:

  • page-id: identifiant de la page
  • prefix: préfix qui sera ajouté en début de chaîne (optionel)

Ce template retourne [prefix]validated|draft|mixed en fonction du status des contenus de la page:

  • validated : tous les contenus de la page sont validés
  • draft : tous les contenus de la page sont des brouillons
  • mixed : la page contient des contenus validés et des brouillons
  • "" : rien n'est retourné si aucun contenu n'est trouvé.

Publication programmée d'une page

Disponible à partir de front-edition 1.7

Pour insérer un bouton permettant lla publication programmée d'une page, utilisez le template XSL "ametys-front-edition-insert-schedule-publication-button". Le seul paramètre est le suivant :

  • page-id : identifiant de la page à programmer (par défaut : identifiant de la page courante)
  • button-text : texte/html du bouton
  • title-i18n : clef i18n à utiliser pour le tooltip du bouton
  • class : classe css à ajouter au bouton. Par défaut front-edition-schedule-publication

Exemple

<xsl:call-template name="ametys-front-edition-insert-schedule-publication-button">                 
    <xsl:with-param name="page-id" select="@sitemap:id"/>               
</xsl:call-template>                 

 

Outils front-edition pour les éléments de page

Supprimer un contenu/service d'une page

Pour insérer un bouton permettant la suppression d'un contenu ou d'un service dans une page (zoneitem), appelez le template "ametys-front-edition-remove-zoneitem-button" avec les parmètres suivants:

  • page-id : identifiant de la page
  • zone-name : nom de la zone dans laquelle un zoneItem sera supprimé
  • zone-item-id : identifiant du zoneitem à supprimer
  • button-text : texte/html du bouton
  • title-i18n : clef i18n à utiliser pour le tooltip du bouton
  • class : classe css à ajouter au bouton. Par défaut front-edition-remove-content
  • edition-mode-only : false() pour autoriser le bouton même en dehors du mode édition (par défaut à true())

Exemple :

<xsl:call-template name="ametys-front-edition-remove-zoneitem-button">                                    
    <xsl:with-param name="page-id" select="ametys:pageId()"/>                                    
    <xsl:with-param name="zone-name" select="'right'"/>                                    
    <xsl:with-param name="zone-item-id" select="ametys:zoneItemId()"/>                                
</xsl:call-template>                 

Helpers XSL

AmetysFrontEditionHelper

La classe org.ametys.plugins.frontedition.AmetysFrontEditionHelper fournit quelques méthodes pour récupérer des arguments utiles aux templates mais peuvent aussi servir lors de l'intégration pour décider d'appeler ou non certains templates (essentiellement hasFrontEditionRight)

hasFrontEditionRight

Deux signature possibles:

  • boolean hasFrontEditionRight(String rightId, String pageId, boolean editionModeOnly)
    Permet de vérifier si un droit est accessible à l'utilisateur (pour vérifier si l'utilisateur peut modifier une page ou un contenu par exemple)
  • boolean hasFrontEditionRight()
    Vérifie uniquement si l'utilisateur dispose du droit Front_Edition_Access_Right dans le contexte général

hasWorkflowRight

Deux signature possibles:

  • boolean hasWorkflowRight(int actionId, String contentId, boolean checkEditionMode)
  • boolean hasWorkflowRight(List<Integer> actionIds, String contentId, boolean checkEditionMode)

Vérifie que l'utilisateur peut faire une action de workflow (peut aussi vérifier si l'on est en mode édition)

getPageStatus

String getPageStatus(String pageId)

Retourne le status des contenus d'une page (draft/validated ou mixed si il y a des deux)

getZoneItemPosition

long getZoneItemPosition(String zoneItemId, String pageId)

Récupère la position d'un zoneItem dans une page

getZoneSize

long getZoneSize(String zoneName, String pageId)

Récupère le nombre de zoneItem dans une zone

getContentWorkflowId

long getContentWorkflowId(String contentId)

Récupère le workflow step id pour un content

getContentStatus

String getContentStatus(String contentId)

Récupère "validated" ou "draft" (brouillon) selon si le contenu possède une version validée (Live) ou non.

isContentLive

boolean isContentLive(String contentId)

Comme au dessus, mais retourne true si le contenu possède une version validée (Live)

AmetysXSLTHelper

La classe org.ametys.web.transformation.xslt.AmetysXSLTHelper fournit une méthode utile pour l'utilisation de front-edition.

isEditionMode

boolean isEditionMode()

Lié à l'utilisation du template ametys-front-edition-insert-toggle-edition-mode-button qui passe du mode normal (utilise le LIVE depuis le front) et le mode edition (utilise le workspace DEFAULT, et permet donc d'accéder aux contenus qui sont en brouillon, aux pages vides).
Cette fonction retourne TRUE si on est dans le front ET en mode edition. (en preview, false sera toujours retourné)

Intégration avancée

Surcharger le rendu HTML de tous les boutons

Chaque template gère son affichage en passant par le template ametys-front-edition-insert-button-simple à qui est passé les paramètres suivants :

  • button-text
  • javascript-function
  • class
  • title-i18n

Voici le code actuel de ce template qui peut être à réécrire pour personnaliser l'affichage général de tous les boutons

<xsl:template name="ametys-front-edition-insert-button-simple">                 
    <xsl:param name="button-text"/>                 
    <xsl:param name="javascript-function"/>                 
    <xsl:param name="class"/>                 
    <xsl:param name="title-i18n"/>
                
    <a class="{$class}" title="{$title-i18n}" i18n:attr="title" href="javascript:void(0)" onclick="{$javascript-function}"><span><xsl:copy-of select="$button-text"/></span></a>                 
</xsl:template>                 

 

Surcharger le rendu HTML d'un bouton

Tous les templates cités plus haut sont ceux à appeler, mais par soucis de modularité, chacun de ces templates en appelle un intermédiaire afin de permettre à une skin de le réécrire afin de modifier le rendu graphique si besoin.

Hormis ametys-front-edition-move-content-button, tous les templates ayant leur nom terminant par -button disposent d'un template intermédiaire du même nom, mais terminant par -button-simple.

Pour ametys-front-edition-move-content-button, il y a 2 niveaux intermédiaires, les templates à réécrire si besoin sont ametys-front-edition-move-content-button-up-simple et ametys-front-edition-move-content-button-down-simple

Tous ces templates intermédiaires demandent les mêmes paramètres :

  • button-text
  • javascript-function
  • title-i18n
  • class

Et ils appellent le template final d'affichage d'un bouton : ametys-front-edition-insert-button-simple (en lui passant ces mêmes paramètres)

Personnaliser les styles de paragraphe dans l'éditeur des textes riches

A partir de la version 1.7.0

La liste des styles de paragraphes est automatiquement mise en forme en copiant les styles suivant de la CSS de l'éditeur riche :

font-family font-size font-weight font-style text-decoration text-transform color background-color border border-radius outline text-shadow

Vous pouvez tout de même surcharger ce comportement dans les CSS de l'éditeur avec le prefixe ".tox-menu" à vos règles CSS.
Par exemple :

.htmleditor-1,
.tox-menu .htmleditor-1 { 
... 
}

 

A partir de la version 1.5.4, il était possible de personnaliser cette liste de façon manuelle en préfixant par ".mce-container.mce-menu". Ceci est maintenant obsolète.

Faire attention que la css soit bien importée côté front

Retour en haut

Front Edition