Introduction
A contextual tab, is a tab in the ribbon that appears and desappears following the current selection. For example, when you select a content in a search result window, the 'Content' tab appears.
Contextual tabs are colored and can be grouped (in the following picture, "Contextual tab 2" and "Contextual tab 2bis" are grouped under the same "Outil de test" label). 
To read this document, you should read firt the MessageBus tutorial.
Please read the "2007 Microsoft Office Fluent UI Design Guidelines - License" to know the rules that applies to contextual tabs, such as :
- contextual tabs should always been after any non contextual tab
- contextual group label sould be like "XXXX Tool"
- ...
Structure
A contextual tab is a tab with some logic and some extra parameters (color and group label)
Configuration for extra parameters
A contextual tab is, first of all, a tab. That means that you should start your creation by configuring your tab as any fixed tab.
<tab label="RIBBON_TABS_TAB_CONTENT_LABEL">
Then you must add the id attribute, the contextualColor attribute and optionnaly the contextualGroup and contextualLabel attributes.
<tab label="RIBBON_TABS_TAB_CONTENT_LABEL" id="org.ametys.cms.content.Tab" contextualColor="1" contextualGroup="A" contextualLabel="RIBBON_TABS_TAB_CONTENT_GROUP_LABEL">
The contextualColor is an integer between 1 and 6 to choose the color you want. The exact color depends on the ribbon skin. On the Ametys skin the colors are :
- red
- orange
- yellow
- green
- blue
- violet
If you want to group several contextual tabs, you MUST place them together and specify
- contextualGroup, all tabs sharing a group must have the same value here.
- contextualLabel, the first tab should have the i18n key to use for the label.
The mandatory id attribute should refers to the identifier of the "logic" you want to use for your contextual tab. See under.
Logic
The logic of a contextual tab has to be declared in a plugin.xml and described in javascript.
Declaration
You have to extend the extension point :
org.ametys.cms.workspace.ribbon.RibbonTabsManager
The purpose of this declaration is to determine a JS class (with script files to import and parameters if needed). As a consequence, the RibbonTabManager uses ClientSideElement.
Here is a sample of declaration, using the static declaration.
<extension id="org.ametys.cms.content.Tab"
point="org.ametys.cms.workspace.ribbon.RibbonTabsManager"
class="org.ametys.cms.workspace.impl.StaticContextualClientSideElement">
<action class="Ext.ametys.uitool.ContentTab"/>
<scripts>
<file>js/ContentTab.js</file>
</scripts>
</extension>
Javascript class
The js class has to inherit the org.ametys.ribbon.control.RibbonTab class.
Contextual tabs are automatically registered to the MessageBus : so you only have to add a onMessage method.
In your onMessage method, you may write your logic to display or hide the tab depending on the events.
To show or hide the tab, you have just to do :
MyClass.prototype.onMessage = function (messages)
{
for (var i=message.length-1; i >=0; i--)
{
if (...)
{
this.hide();
return;
}
if (...)
{
this.show();
return;
}
}
}
Existing implementations
Selection tab
The selection tab (org.ametys.cms.ribbon.tab.SelectionTab) is a contextual tab with the following logic : it looks for "selection" event and match the target type (and optionnaly the subtarget type) These parameters are regexp.
Here is a sample of declaration of a tab that displays when a page is selected.
<extension id="org.ametys.cms.page.PageTab"
point="org.ametys.cms.workspace.ribbon.RibbonTabsManager"
class="org.ametys.cms.workspace.impl.StaticContextualClientSideElement">
<action class="org.ametys.cms.ribbon.tab.SelectionTab">
<param name="target-type">^page$</param>
</action>
<scripts>
<file>js/org/ametys/cms/ribbon/tab/SelectionTab.js</file>
</scripts>
</extension>
Here is a sample of declaration of a tab that is visible only when a content is selected and have a sub-selection that is a form.
(this kind of event is for sample thrown by the ContentTool during an edition)
<extension id="org.ametys.cms.content.EditionTab"
point="org.ametys.cms.workspace.ribbon.RibbonTabsManager"
class="org.ametys.cms.workspace.impl.StaticContextualClientSideElement">
<action class="org.ametys.cms.ribbon.tab.SelectionTab">
<param name="target-type">^content$</param>
<param name="target-subtype">^form$</param>
</action>
<scripts>
<file>js/org/ametys/cms/ribbon/tab/SelectionTab.js</file>
</scripts>
</extension>
Tool tab
The tool tab (org.ametys.cms.ribbon.tab.ToolTab) is a contextual tab with the following logic : it is visible when the configured tool has the focus.
You can confifure the tool id (parameter 'tool-id') or the tool factory id (parameter 'factory-id').
Here is a sample of declaration of a tab that is visible only when a ContentTool has the focus.
<extension id="org.ametys.cms.content.ContentToolTab"
point="org.ametys.cms.workspace.ribbon.RibbonTabsManager"
class="org.ametys.cms.workspace.impl.StaticContextualClientSideElement">
<action class="org.ametys.cms.ribbon.tab.ToolTab">
<param name="target-type">uitool-content</param>
</action>
<scripts>
<file>js/org/ametys/cms/ribbon/tab/ToolTab.js</file>
</scripts>
</extension>
Becareful! Even if at first sight you may think that SelectionTab and ToolTab are the same for a content, this is not true.
Using a selection tab, the tab will be visible when the current selection is a content. For example :
- when the content is selected in search result without opening it
- when the content is open and then you give the focus the DetailsTool.
Using a tool tab, the tab will only be visible when the ContentTool has the focus. For example, it will not appears in the two preceding samples.
Keep in mind, that you should use a SelectionTab when the selection does matter (such as for content) and a ToolTab when the buttons are directly linked to the tool and not the selection : for example, if the buttons in the tab may appears on the tool it self (and are positionned in the ribbon for design purposes)
Back to top