Toolbar for front-office editing

This documentation describes how to integrate toolbars for front-office editing (version 1.8.x and higher).

In version 1.8.x, plugin Front-Edition provides 2 additional XSL helpers to facilitate integration:

  • insert a floating toolbar for actions related to the current page (add content, label, rename, move, program the page ....)
  • insert an action toolbar (modify, tag, validate, unpublish, etc.) and status toolbar linked to a content zoneitem

Contents

  1. Prerequisites
  2. Page toolbar
    1. Toolbar integration
    2. Setting the "Add content" menu
    3. Setting the "Add a page" button
    4. Toolbar content settings
    5. Edition mode
  3. Content toolbar
    1. Toolbar integration
    2. Toolbar configuration
      1. Setting toolbar content ("items" parameter)
      2. Setting workflow actions ("workflow-actions" parameter)
      3. Status and type settings ("workflow-steps" parameter)
  4. Graphical customization of toolbars
  5. A little extra for the fo edition (fo edition without dublin core)

Prerequisites

As with all other front-office editing modes, front-edition scripts must be loaded and the XSL file providing front-edition helpers must be imported. See prerequisites in the Integration Manual

In addition, the default icons used by toolbars are FontAwesome 5 Free icons. Your charter must therefore include fontawesome:

<link rel="stylesheet" href="{ametys:pluginResourceURL('fontawesome-free', 'css/all.css')}" />

Page toolbar

The toolbar dedicated to the current page enables the following actions by default:

  • Enable/disable input (switch to edit mode)
  • Add a subpage
  • Adding content to a zone
  • Manage page
    • Label
    • Rename
    • Move (within parent page)
    • Program
    • Delete

The toolbar appears as a floating bar on the right of the page.

The list of buttons/menus, their labels and icons, and their organization in the toolbar are configurable.

If a menu contains only one available action, it automatically becomes a button.

Toolbar integration

The toolbar is added to a page template by calling up the following template XSL :

<xsl:call-template name="ametys-front-edition-page-toolbar"/>

As with all other front-office editing modes, front-edition scripts must be loaded and the XSL file providing front-edition helpers must be imported. See prerequisites in the Integration Manual

By default, the toolbar operates in "edit mode", i.e. actions on the page are only available when you switch to edit mode.

Without further customization, the toolbar will look like this:

  • if the "edition" mode is not active, it includes a single button to activate this mode:

  • if "edition" mode is active, the bar shows the buttons/menu available to the logged-in user

Setting the "Add content" menu

Adding content to the page depends on the page's zones and the project's content/workflow types.

In order to add the possibility of adding content to the page, it is therefore necessary to configure the toolbar by listing, for each zone of the page, the types of content that can be added, using the "add-contents-config" parameter .

This parameter is presented in the form of a table, with the following information for each entry:

  • contentType: the type of content that can be added
  • zoneName: the name of the zone in which it will be added
  • label: button label (e.g. Add a news item in the central zone)
  • icon: button icon. Optional.
  • workflowName: the associated workflow. Optional, default is "content".
  • initActionId: the initial workflow action. Optional, default 1

Example of how to add the actions "Add an article in the central zone" and "Add a news item in the left zone" to the toolbar.

<xsl:call-template name="ametys-front-edition-page-toolbar">
 <xsl:with-param name="add-contents-config">[
   {"contentType": "org.ametys.web.default.Content.article", "icon": "fas fa-file-alt", "zoneName": "default", "label": "Ajouter un article dans la zone centrale"},
     {"contentType": "org.ametys.plugins.news.Content.news", "icon": "fas fa-file-alt", "zoneName": "top-left", "label": "Ajouter une actualité dans la zone de gauche"}
   ]</xsl:with-param>
</xsl:call-template>

The toolbar then integrates an "Add content" menu with a list of defined actions:

The action label can be a key i18n:

<xsl:call-template name="ametys-front-edition-page-toolbar">
 <xsl:with-param name="add-contents-config">[
   {"contentType": "org.ametys.web.default.Content.article", "icon": "fas fa-file-alt", "zoneName": "default", "label": "<i18n:text i18n:key="SKIN_FO_TOOLBAR_ADD_CONTENT_TO_DEFAULT" i18n:catalogue="skin.{$skin}"/>"},
     {"contentType": "org.ametys.plugins.news.Content.news", "icon": "fas fa-file-alt", "zoneName": "top-left", "label": "<i18n:text i18n:key="SKIN_FO_TOOLBAR_ADD_CONTENT_TO_TOP_LEFT" i18n:catalogue="skin.{$skin}"/>"}
  ]</xsl:with-param>
</xsl:call-template>

If the "add-contents-config" parameter consists of a single action, the "Add content" menu is replaced by a single button with the name of the defined action (choose a short title)

Setting the "Add a page" button

The page creation wizard can be configured using the "add-page-config" parameter.

The expected format is a JSON corresponding to the "config" parameter of the page creation wizard: http: //releases.ametys.org/api /release/4 .4.x/#!/api / Ametys.plugins.web.page.AddPageWizard-method-open 

For example, to reduce the wizard to a single choice of content type between "Article" and "Project news", force the "page" template:

<xsl:call-template name="ametys-front-edition-page-toolbar">
 <xsl:with-param name="add-page-config">{                 
   "force": true,           
   "show-card-type" : false,         
   "show-card-content" : true,         
   "show-card-tags" : false,         
   "default-pagetype" : "template",                 
   "default-template" : "page",                 
   "default-pagecontent-type" : "contenttype",   
 "pagecontent-card-content-filter": ["org.ametys.web.default.Content.article", "org.ametys.plugins.workspaces.Content.projectNews"],       
   "default-contenttype" :  "org.ametys.web.default.Content.article",                 
   "default-content-title" : "Nouvel article"             
   }</xsl:with-param>       
</xsl:call-template>

Please note that if this parameter is not set, the following default configuration is applied:

{
   '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
}   

In this default configuration, the page creation wizard:

  • limits the page type to "Page with templates" (no template restriction) or "Redirect to a site page",
  • limits content types to article (org.ametys.web.default.Content.article) and news (org.ametys.plugins.news.Content.news),
  • does not allow you to create a page with service selection
  • to select labels

Toolbar content settings

The label and icon used for each button or menu can be overloaded.
The position and organization of each action in the button/menu can also be overloaded.

To do this, you need to redefine the "items" parameter and know the identifiers of the toolbar actions.

The toolbar action identifiers for the page are as follows:

  • edition-mode: to activate/deactivate the "edition" mode
  • add-content: for the menu used to add content to the page
  • add-page: to add a sub-page to the current page
  • tag: to tag the page
  • rename: to rename the page
  • move: to move the page within its parent page
  • delete: to delete the page
  • schedule-publication: to schedule publication of the page

The par value of the default "items" parameter is as follows:

['edition-mode', 'add-content', 'add-page', {type: 'menu', label: "<i18n:text i18n:key="PLUGINS_FRONT_EDITION_TOOLBAR_PAGE_ACTIONS_MENU_LABEL"  i18n:catalogue="plugin.front-edition"/>", items: [ 'tag', 'rename', 'move', 'schedule-publication', 'delete']}]

In this configuration, the toolbar is arranged in the following order:

  • a button to enter or exit edition mode
  • a menu to add content to the page
  • a button to add a sub-page
  • a "Manage page" menu with other possible actions on the page: tag, rename, move, program, delete

Each action can be placed in a menu, sub-menu or directly at the root of the toolbar.

To override an action label and/or iconIn this case, we'll write the action identifier instead: {type: 'tag', label: "Libellé surchargé", icon: "fas fa-file"}

To override the label and/or content of a menu, we write :  {type: 'menu', label: "Plus..", items: ['tag', 'rename']}

The action/menu label can be a key i18n: {type: 'menu', label: "<i18n:text i18n:key="SKIN_TOOLBAR_MENU_LABEL" i18n:catalogue="skin.{$skin}/>", items: ['tag', 'rename']}

Customization examples

Here's an example of how to customize the toolbar, reorganizing it as follows:

  • the "Add page" button is moved up one level and renamed "Add subpage".
  • the "Label" action is added directly to the toolbar (out of the menu)
  • the "Manage page" menu is renamed "More...".
  • moving the page is no longer possible (deletion of the 'move' action)
<xsl:call-template name="ametys-front-edition-page-toolbar">
 <xsl:with-param name="items">['edition-mode', {type: 'add-page', label: 'Ajouter une sous-page'}, 'add-content', 'tag', {type: 'menu', label: "Plus...", items: ['rename', 'schedule-publication', 'delete']}]</xsl:with-param>
  <xsl:with-param name="add-contents-config">[
   {"contentType": "org.ametys.web.default.Content.article", "icon": "fas fa-file-alt", "zoneName": "default", "label": "<i18n:text i18n:key="SKIN_FO_TOOLBAR_ADD_CONTENT_TO_DEFAULT" i18n:catalogue="skin.{$skin}"/>"},
     {"contentType": "org.ametys.plugins.news.Content.news", "icon": "fas fa-file-alt", "zoneName": "top-left", "label": "<i18n:text i18n:key="SKIN_FO_TOOLBAR_ADD_CONTENT_TO_TOP_LEFT" i18n:catalogue="skin.{$skin}"/>"}
  ]</xsl:with-param>
</xsl:call-template>

Edition mode

The page toolbar to be inserted in edition mode only or not.

By default the "edition-mode-only" parameter is set to true(), so actions on the page are only available if you switch to edit mode.

This parameter can be set to false() to make the toolbar and actions available outside edition mode.
To do this, override the "items" parameter and remove the "edition-mode" action from the toolbar.

Note that page programming is only available in edition mode.

Content toolbar

The default content toolbar consists of :

  • the current state of the content preceded by the states that led to that state (e.g. Proposed -> Validated)
  • a list of possible workflow actions (propose, validate, unpublish, etc.)
  • possible actions on content: modify, label, move within the zone, remove content from the zone

The list of actions depends on the user's rights and the current state of the content.

The list of buttons/menus, their labels and icons, and their organization in the toolbar are configurable.

If a menu contains only one available action, it automatically becomes a button.

Toolbar integration

The content toolbar must be added to the page template by calling the XSL template "ametys -front-edition-content-toolbar" from the "zone-item-before" template.

Example of integration using the toolbar with default buttons/menus for the main zone, and a more reduced toolbar for secondary zones (Edit button with a simple icon and grouping of all actions in a single menu):

<xsl:template name="zone-item-before">
  <xsl:param name="position"/>
  <xsl:param name="count"/>
  <xsl:param name="zone-name"/>
  <xsl:param name="level"/>
  <xsl:param name="inherited"/>
  <xsl:param name="id"/>
  <xsl:param name="type"/>
  <xsl:param name="content-id"/>
  <xsl:param name="service"/>
  <xsl:param name="content-type"/>
  
  <xsl:if test="$type = 'CONTENT'">       
    <xsl:choose>
    <xsl:when test="$zone-name = 'aside-top' or $zone-name = 'aside-bottom'">
          <!-- Small version of toolbar -->
          <xsl:call-template name="ametys-front-edition-content-toolbar">
            <xsl:with-param name="content-id" select="$content-id"/>
            <xsl:with-param name="zone-name" select="$zone-name"/>
            <xsl:with-param name="zone-item-id" select="@id"/>
            <xsl:with-param name="items">[{type: 'edit', label: ''}, 'current-step', {type: 'menu', label: '', icon: 'fas fa-ellipsis-v', items: ['workflow-action-3', 'workflow-action-4', 'workflow-action-7', 'workflow-action-10', 'tag', 'move', 'remove']}]</xsl:with-param>
          </xsl:call-template>
      </xsl:when>
      <xsl:otherwise>
          <!-- Default toolbar for default zone -->
          <xsl:call-template name="ametys-front-edition-content-toolbar">
            <xsl:with-param name="content-id" select="$content-id"/>
            <xsl:with-param name="zone-name" select="$zone-name"/>
            <xsl:with-param name="zone-item-id" select="@id"/>
          </xsl:call-template>
      </xsl:otherwise>
    </xsl:choose> 
  </xsl:if>
</xsl:template>

The toolbar should never be integrated directly into content rendering, as XSL content is cached.

Toolbar configuration

The XSL helper call has several parameters. The first 3 are mandatory, while the following parameters all have default values that can be overridden:

  • content-id: content identifier
  • zone-item-id: zone item identifier
  • zone-name: parent zone name
  • edit-view-name: name of the view when you want to modify the content in a dialog box. Default "defaut-edition".
  • items: list of buttons/menus and their organization in the toolbar
  • workflow-actions: list of workflow actions authorized from the front office
  • workflow-steps: list of workflow states with their type
  • excluded-actions-outside-edition-mode: identifiers for workflow actions that should not appear outside edition mode. By default [10], for the unpublish action
  • edition-mode-only: true() to display toolbar only in edition mode, false() otherwise. Defaults to true().

Setting toolbar content ("items" parameter)

This parameter defines both the buttons/actions available and their organization (button/menu, position) in the toolbar.

Known button identifiers are as follows:

  • current-step: to display a non-clickable button representing the current state. Only available in "edition" mode
  • status-history: to display states preceding the current state, significant for explaining the current state (e.g.: content was proposed before being validated)
  • workflow-actions: to display the full list of workflow actions available to the user and the current content
  • worflow-action-X: to display a button to perform action X
  • edit: "Modify" button to change content in a popup
  • tag: button for "tagging" content
  • move-up: button to move content up (within its zone)
  • move-down: button to move content down (within its zone)
  • move: shortcuts for inserting a menu with move-up and move-down actions
  • remove: button for deleting zone contents
  • menu: keyword for organizing actions in a menu

The default value for this parameter is:

['edit', 'status-history', 'current-step', {type: 'menu', items: ['workflow-action-3', 'workflow-action-4', 'workflow-action-7']}, 'workflow-action-10', {type: 'menu', label: '<i18n:text i18n:key="PLUGINS_FRONT_EDITION_TOOLBAR_MORE_MENU_LABEL" i18n:catalogue="plugin.front-edition"/>', items: ['tag', 'move', 'remove']}]

In this configuration, the toolbar displays in order:

  • an "Edit" button to modify content in a popup window
  • the current state of the content, preceded by the states of the same type that led to this state
  • an "Actions" menu with Propose, Validate and Reject actions (only actions available for the current state and user are visible)
  • an "Unpublish" button (visible only in edition mode and if an online version exists)
  • a "More..." menu with Tag, Move and Remove content actions

If this default organization is suitable, the helper can be called up without specifying this parameter.

Each action can be placed in a menu, sub-menu or directly at the root of the toolbar.

To override an action label and/or iconIn this case, we'll write the action identifier instead: {type: 'tag', label: "Libellé surchargé", icon: "fas fa-file"}

To override the label and/or content of a menu, we write :  {type: 'menu', label: "Plus..", items: ['tag', 'remove']}

The action/menu label can be a key i18n: {type: 'menu', label: "<i18n:text i18n:key="SKIN_TOOLBAR_MENU_LABEL" i18n:catalogue="skin.{$skin}/>", items: ['tag', 'remove']}

Example of customization:

For example, to move the Label action directly to the toolbar with an unlabeled button next to "Modify", and put all workflow actions in a "Lifecycle" sub-menu of the "More..." menu between the Move and Remove content actions, we would write

['edit', {type: 'tag', label: ''}, 'current-step', {type: 'menu', label: '<i18n:text i18n:key="PLUGINS_FRONT_EDITION_TOOLBAR_MORE_MENU_LABEL" i18n:catalogue="plugin.front-edition"/>', items: ['move', {type: 'menu', label: 'Cycle de vie', items: ['workflow-actions']}, 'remove']}]

 

Setting workflow actions ("workflow-actions" parameter)

By default, the workflow actions authorized from the front office are those of the standard workflow: propose (3), validate (4), refuse (7) and unpublish (10). They are available with a default icon for each.

When using "workflow-actions" in the "items" parameter, the list of available actions depends on :

  • the list of workflow actions allowed in this "workflow-actions" parameter
  • user rights
  • current content status

If a workflow action is not available (insufficient right, content status does not allow it), the button does not appear.

You can override the list of workflow actions available by default by redefining the "workflow-actions" parameter.

The expected value is an array containing the workflow action identifiers, or an object representing the workflow action with any overloads.

Examples:

  • [2, 4, 7]: to restrict the list of available actions to Propose, Validate and Refuse, retaining the default labels and icons.
  • [2, 4, {"id": 7, "icon":"fas fa-times"}, {"id": 10, "label": "Dépublier la version en ligne"}] : pour surcharger l’icône par défaut pour l'action de refus (7) et le libellé pour l'action de dépublication (10)

Please note that since this parameter is sent to the server, the syntax with the use of double quotes in JSON must be respected.

Status and type settings ("workflow-steps" parameter)

For status buttons, the toolbar has 3 types of status:

  • neutral: for a button that appears in gray with a status icon (e.g. Draft)
  • positive: for a button that appears in green with a checkmark (e.g. Suggested, Validated)
  • negative: for a button that appears in red with a cross (no negative state in standard workflow)

The default value of this parameter corresponds to the standard workflow for Draft (1), Proposed (2) and Released (3) states:

{"1": {"type": "neutral", "icon": "fas fa-file-alt"}, "2": {"type": "positive"}, "3": {"type": "positive"}}

We need to define an icon for neutral states.

To define a different label from the one defined in the workflow, use, for example "1": {"type": "neutral", "label": "En cours de modification", "icon": "fas fa-file-alt"}

The current status is only displayed in "edition" mode.

Please note that since this parameter is sent to the server, the syntax with the use of double quotes in JSON must be respected.

Graphical customization of toolbars

plugin front-edition provides default scss for toolbar rendering.

The page toolbar is a floating bar, appearing on the right-hand side of the page.
When scrolled, the toolbar shrinks, showing only the button/menu icons.

It is redeployed to the click.

Action buttons are purple by default, with rounded corners.
Status buttons are gray, green or red.
The font used is "Roboto, sans serif".

To override the main color and font used by toolbars, simply import a SCSS file with, for example:

$ametys-front-edition-primary: #e8590c;
$ametys-front-edition-font-family: "Poppins Medium",sans-serif;;

@import "plugin:front-edition://resources/scss/toolbar.scss";

The SCSS must be loaded after the front-edition SCSS. Import it after calling the "ametys-front-edition-head" template.

The following SCSS variables are available and can be overloaded:

 $ametys-front-edition-primary: #9575cd !default;
 $ametys-front-edition-font-family: Roboto, sans-serif !default;
 $ametys-front-edition-font-size: 14px !default;
 $ametys-front-edition-btn-bgcolor: $ametys-front-edition-primary !default;
 $ametys-front-edition-btn-color: #fff !default;
 $ametys-front-edition-menu-color: #2f2f2f !default;
 $ametys-front-edition-btn-neutral-bgcolor: #e5e7eb !default;
 $ametys-front-edition-btn-neutral-color:#374151 !default;
 $ametys-front-edition-btn-positive-bgcolor: #deedd5 !default;
 $ametys-front-edition-btn-positive-color:#6fbe44 !default;
 $ametys-front-edition-btn-negative-bgcolor: #ff9595 !default;
 $ametys-front-edition-btn-negative-color:#fc7d85 !default;
 $ametys-front-edition-disabled-color:#c1c1c1 !default;

You can take customization a step further by redefining the CSS classes used by toolbars.

A little extra for the fo edition (fo edition without dublin core)

It's possible to create a content view for FO editing, to avoid having to use contact and dublin core properties.

Example: WEB-INF\param\content-types\_override\org.ametys.plugins.news.Content.news.xml

<cms:content-type xmlns:cms="http://www.ametys.org/schema/cms">      
     <!-- edition-fo view -->
     <cms:metadata-set name="edition-fo" type="view">
         <cms:metadata-ref name="title" />
         <cms:metadata-ref name="document-subtitle" />
         <cms:metadata-ref name="start-date" />
         <cms:metadata-ref name="end-date" />
         <cms:metadata-ref name="illustration">
             <cms:metadata-ref name="image" />
             <cms:metadata-ref name="alt-text" />
         </cms:metadata-ref>
         <cms:metadata-ref name="abstract" />
         <cms:metadata-ref name="content" />
         <cms:label i18n="true">plugin.web:PLUGINS_WEB_VIEW_MAIN</cms:label>
         <cms:description i18n="true">plugin.web:PLUGINS_WEB_VIEW_MAIN_DESC</cms:description>
     </cms:metadata-set>     
</cms:content-type>

In the zone-item-before template, add an edit-view-name parameter with the value of the view name. Please note that this view must be available for all FO content types.

Example

<xsl:call-template name="ametys-front-edition-content-toolbar">
             <xsl:with-param name="content-id" select="$content-id"/>
             <xsl:with-param name="zone-name" select="$zone-name"/>
             <xsl:with-param name="zone-item-id" select="@id"/>
             <xsl:with-param name="edit-view-name">edition-fo</xsl:with-param>
</xsl:call-template>
Back to top