Ribbon customization (file cms-ribbon-*.xml)

In Ametys, the configuration of the ribbon (the upper part of the graphic interface) is specific to each type of site.

It is defined in the WEB-INF/param/cms-ribbon-[siteType].xml (e.g: cms-ribbon-default.xml).

Example of a ribbon
for a "corporate" website

Example of a
ribbon for a "blog" type site

This file defines the list of accessible buttons and menus, as well as their organization. It is therefore this file that must be modified to add, delete or move a button or menu.

Note
Depending on his rights, a contributor will have access to all or some of the Ribbon elements. Here, for example, is access to the demo application with 3 different rights profiles:

 

Ribbon organization

The file WEB-INF/param/cms-ribbon-[siteType].xml defines the tools and actions accessible from the Ribbon.

Ribbon elements are organized in tabs (tab) and groups (group).

Some tabs are context-sensitive. They appear or disappear depending on the current context: opening a tool, selecting content, etc.

 

Extract from file cms-ribbon-*.xml

<ribbon  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://ametys.org/cms/3.0/ribbon.xsd">
    <tabs>
        <tab label="RIBBON_TABS_TAB_HOME_LABEL">
            <groups>
                <group label="RIBBON_TABS_TAB_HOME_GROUPS_GROUP_TOOL_LABEL" icon="">
                    ...
                </group>
                <group label="RIBBON_TABS_TAB_HOME_GROUPS_GROUP_ADVANCED_TOOL_LABEL" icon="">
					...
                </group>
				...
            </groups>
        </tab>
		<tab label="RIBBON_TABS_TAB_RIGHTS_HANDLE_LABEL">
			 ...
		</tab>
		...
		<import>plugin:cms://ribbon/cms-ribbon-content.xml</import>
	</tabs>
</ribbon>

The tabs

Each <tab> defines a new tab in the Ribbon.

There are two types of tabs: permanent tabs and context-sensitive tabs.

Permanent tab

A permanent tab is a tab that is visible regardless of the current context. It is simply defined by a label.

Declaration of the "Home" tab

<tab label="RIBBON_TABS_TAB_HOME_LABEL">
	...
</tab>

The wording (label) is a i18n key. The default catalog is the application catalog (WEB-INF/i18n/application_*.xml). For more information on internationalization, please visit the page Internationalization.

Contextual tab

A context-sensitive tab is a tab that appears and disappears according to the current context. For example, the "Page" tab is visible when a page is selected, and the "Glossary" tab is visible when the "Glossary" tool is opened.

Visually, such a tab is colored and belongs to a group of contextual tabs.

For example, when editing a table, two contextual tabs "Table" and "Advanced" appear, grouped together under the "Table tools" label.

Technically, such a tab is associated with a logic (mainly to answer the question: "when is it visible?"). Each contextual tab "logic" is defined by an extension point org.ametys.cms.workspace.ribbon.RibbonTabsManager.

The declaration is therefore as follows:

<tab label="plugin.web:RIBBON_TABS_TAB_PAGE_LABEL" id="org.ametys.cms.page.Tab" contextualColor="2" contextualGroup="A" contextualLabel="plugin.web:RIBBON_TABS_TAB_PAGE_LABEL">
	...
</tab>

The wording (label) is a key i18n as in the permanent tab.

The identifier (id) is the extension identifier used to manage the tab display logic. It is therefore possible to use the same identifier several times in a file.

The color "contextualColor"is the color to be used for the contextual tab. This is a numerical code, but the actual color depends on the theme used.
In the default Ametys theme, the following colors are available:

  1. Red
  2. Orange
  3. Yellow
  4. Green
  5. Blue
  6. Violet

Context group identifier "contextualGroup"is a character string that serves as a unique identifier.
All tabs in the same group must share the same "contextualGroup" and be placed side by side in this file.
The color of the group is determined by the color of the first tab defined in that group: a group can therefore contain tabs of different colors.

The context group label "contextualLabel"is a key i18n like the label. As with the color, only the label on the 1st tab of the group is taken into account for the group.

Groups

A group allows you to group together a set of buttons on the same tab.

The size of the group and its elements can be adapted to the width of the contributor's screen.
This is why 3 configurations (large, medium, small) are defined for each group. Depending on the width of the screen, one or other of the configurations will be used to optimize the available space.

Here's an example of how the "Page" tab displays in 3 screen resolutions:

 

<group label="plugin.cms:RIBBON_TABS_TAB_CONTENT_EDIT_GROUPS_GROUP_GENERAL_LABEL" icon="" priority="-10">
    <large>
        <control id="org.ametys.web.edition.Save"/>
        <control id="org.ametys.web.edition.UnSave"/>
        <layout size="small">
            <control id="org.ametys.cms.edition.Undo"/>
            <control id="org.ametys.cms.edition.Redo"/>
        </layout>
    </large>
    <medium>
        <control id="org.ametys.web.edition.Save"/>
        <layout size="small">
            <control id="org.ametys.web.edition.UnSave"/>
            <control id="org.ametys.cms.edition.Undo"/>
            <control id="org.ametys.cms.edition.Redo"/>
        </layout>
    </medium>
    <small>
        <control id="org.ametys.web.edition.Save"/>
        <layout size="very-small">
            <control id="org.ametys.web.edition.UnSave"/>
            <control id="org.ametys.cms.edition.Undo"/>
            <control id="org.ametys.cms.edition.Redo"/>
        </layout>
    </small>
</group>

The wording (label) is a i18n key, as for tabs.

The icon (icon) is an icon representing the extremely small group. This feature is not currently in use.

Priority (priority) of the group allows you to give more weight to certain groups. The default value is "0", and in the event of a tie, the left-hand groups have priority.
By default, in the case of low resolution, groups of lines will be reduced first; this value allows you to change this behavior.

Only size <medium> is mandatory. If not configured <large> or <small>is <medium> which is used as is.
If you specify more than one size, the list of buttons must be identical in all 3 configurations. For example, a button cannot be available in "large" view only.
To avoid confusing contributors, it is strongly recommended that buttons remain visually in the same order, regardless of size.

Each configuration (large, medium, small) defines the organization and placement of buttons or menus.

Large button
<control id="org.ametys.web.blankpage"/>
<control id="org.ametys.web.linkpage"/>
<control id="org.ametys.web.templatesmenu"/>
 
Small button
(icon + text)

Using the <layout> with size="small".
The align="top" (default) or align="middle" defines vertical alignment.

<layout size="small" align="top">
	<control id="org.ametys.web.blankpage"/>
	<control id="org.ametys.web.linkpage"/>
	<control id="org.ametys.web.templatesmenu"/>
</large>
 
Very small button
(icon only)

Using the <layout> with size="very-small".
The align="top" (default) or align="middle" defines vertical alignment.

<layout size="very-small" align="top">
	<control id="org.ametys.web.blankpage"/>
	<control id="org.ametys.web.linkpage"/>
	<control id="org.ametys.web.templatesmenu"/>
</large>

The buttons are displayed in the order in which they are described in the file, but please bear in mind that, depending on their rights, some contributors may not see all the buttons.

More complex arrangements

Like the HTML tables, it's possible to have slightly more complex button layouts.

The "cols"on the <layout> allows you to specify that you wish to work on several columns, and in this case you can specify the "colspan" attribute on a control to indicate that it takes up several locations.

The order of the buttons is left to right, then top to bottom.

Si vous faites simplement plusieurs colonnes de boutons, mettez plusieurs fois <layout> sans préciser de colonne. Le <layout> a plusieurs colonnes ne doit être utilisé que pour jouer sur les "colspan".

Here's an example of what not to do:

<layout align="top" size="very-small" cols="2">
	<control id="org.ametys.web.pageaccess.SetAccess"/>
	<control id="org.ametys.web.userinterface.Attachments"/>
	<control id="org.ametys.web.userinterface.Robots"/> 
	<control id="org.ametys.translationflagging.SetTranslation"/>
	<control id="org.ametys.web.page.Properties"/>
</layout>

It's better to do this, to obtain the same visual result (note the change of order in the buttons between the two examples):

<layout align="top" size="very-small">
	<control id="org.ametys.web.pageaccess.SetAccess"/>
	<control id="org.ametys.web.userinterface.Robots"/> 
	<control id="org.ametys.web.page.Properties"/>
</layout>
<layout align="top" size="very-small">
	<control id="org.ametys.web.userinterface.Attachments"/>
	<control id="org.ametys.translationflagging.SetTranslation"/>
</layout>

You'll find a useful example of colonization with "colspan" in the next section on toolbars.

Toolbars

In a <layout> buttons can be grouped together as a toolbar using the <toolbar>

In a toolbar, the "very-small" size is always used.

<layout cols="2" align="middle" size="small">
	<control id="org.ametys.cms.edition.character.Style" colspan="2"/>
	<toolbar>
		<control id="org.ametys.cms.edition.character.Bold"/>
		<control id="org.ametys.cms.edition.character.Italic"/>
		<control id="org.ametys.cms.edition.character.Sub"/>
		<control id="org.ametys.cms.edition.character.Sup"/>
	</toolbar>
	<toolbar>
		<control id="org.ametys.cms.edition.character.AlignLeft"/>
		<control id="org.ametys.cms.edition.character.AlignCenter"/>
		<control id="org.ametys.cms.edition.character.AlignRight"/>
		<control id="org.ametys.cms.edition.character.AlignJustify"/>
	</toolbar>
</layout>
<layout align="middle" size="small">
	<toolbar>
		<control id="org.ametys.cms.edition.character.UnorderedList"/>
		<control id="org.ametys.cms.edition.character.OrderedList"/>
		<control id="org.ametys.cms.edition.character.Outdent"/>
		<control id="org.ametys.cms.edition.character.Indent"/>
	</toolbar>
	<toolbar>
		<control id="org.ametys.cms.edition.Abbreviation"/>
		<control id="org.ametys.cms.edition.Acronym"/>
		<control id="org.ametys.glossary.editor.AddDefinition"/>
		<control id="org.ametys.cms.edition.Quote"/>
		<control id="org.ametys.cms.edition.Language"/>
	</toolbar>
</layout>

 

 

 

Imports

The <import> allows you to import XML files describing a part of the ribbon.

This makes it possible to import tabs defined in other xml files, without increasing the size of the file. cms-ribbon-*.xml and share certain configurations (between 2 types of site, for example).

Theurl import form is as follows plugin:[nom_plugin]://[chemin_du_fichier_relatif_au_plugin].xml

<!-- Cms -->
<import>plugin:cms://ribbon/cms-ribbon-content.xml</import>

<!-- Web -->
<import>plugin:web://ribbon/cms-ribbon.xml</import>

<!-- Inline Media -->
<import>plugin:inlinemedia://cms-ribbon.xml</import>

 

Examples of ribbon modifications

If you want to change the way ribbon icons are displayed, you'll need to modify this cms-ribbon-default file.xml :

  • vous pouvez supprimer un bouton pour qu'il n'apparaisse plus du tout : par exemple le bouton "Fermer sans enregistrer" ; pensez à le supprimer de toutes les tailles (<large>, <medium> et <small>)
<group label="plugin.cms:RIBBON_TABS_TAB_CONTENT_EDIT_GROUPS_GROUP_GENERAL_LABEL" icon="" priority="-10">
	<large>
    	<control id="org.ametys.web.edition.Save"/>
        <layout size="small">
        	<control id="org.ametys.cms.edition.Undo"/>
            <control id="org.ametys.cms.edition.Redo"/>
        </layout>
    </large>
    <medium>
    	<control id="org.ametys.web.edition.Save"/>
        <layout size="small">
            <control id="org.ametys.cms.edition.Undo"/>
            <control id="org.ametys.cms.edition.Redo"/>
        </layout>
    </medium>
    <small>
    	<control id="org.ametys.web.edition.Save"/>
        <layout size="very-small">
       	 	<control id="org.ametys.cms.edition.Undo"/>
        	<control id="org.ametys.cms.edition.Redo"/>
     	</layout>
    </small>
</group>
  • you can change the format of a button, depending on the size of the window: for example, the "Reset" button should always be very small:
<group label="plugin.cms:RIBBON_TABS_TAB_CONTENT_EDIT_GROUPS_GROUP_GENERAL_LABEL" icon="" priority="-10">
	<medium>
    	<control id="org.ametys.web.edition.Save"/>
       	<control id="org.ametys.cms.edition.Undo"/>
        <layout size="very-small">
            <control id="org.ametys.cms.edition.Redo"/>
        </layout>
    </medium>
    <small>
    	<control id="org.ametys.web.edition.Save"/>
        <layout size="very-small">
       	 	<control id="org.ametys.cms.edition.Undo"/>
        	<control id="org.ametys.cms.edition.Redo"/>
     	</layout>
    </small>
</group>

 

 

Back to top

Setup and integration manual