Introduction
A tool is what opens as a tab in the interface, such as : ContentTool, SearchTool, DetailTool...
This document explains how to create a new tool.
Principle
A instance of a tool object (org.ametys.uitool.tool.Tool) is attached to every tab you have opened in your interface.
Tools instances are created by a factory (org.ametys.uitool.tool.ToolFactory) that is registered by a role-name.
The purpose of this to open tools by the role you need and not by an implentation name. So you will not open a new content tab by entering
new org.ametys.cms.tool.content.ContentTool("mycontentname").open();
To open a tool, you just call the rolename throught the ToolsManager.
org.ametys.uitool.ToolsManager.getInstance().openTool("uitool-content", {id: "mycontentname"});
As a consequence you can override the ContentTool by unactivating the default factory and writing your own. Of course, factories have to be compatible (they have to deal with the same parameters).
Declare a ToolFactory
These factories are registered on an extension point that use the ClientSideElement interface.
See the ClientSideElement page for more information.
Writing a ToolFactory js class
The class has to extend the org.ametys.uitool.tool.ToolFactory class.
The class parameter "role" is mandatory ; it will define the factory role name.
Ensure that you do not have several factories using the same role name
The only two methods of a factory is open and close tool. At this point you will need to write a org.ametys.uitool.tool.Tool implementation.
Opening a tab
org.ametys.uitool.ToolsManager.getInstance().addUITool
As you can see by reading the API, the openTool method gives you parameters.
You can do what you want with the parameters but please document it.
If your are replacing a standard tool, you have to handle the same parameters.
Closing a tab
org.ametys.uitool.ToolsManager.getInstance().removeUITool
Using factories
As factories are automatically delcared, you simply have to call them
org.ametys.uitool.ToolsManager.getInstance().openTool(factoryRole, parameters);
The factory will decide to open a new tab or activate/recycle an existing one (using the getTool method)
The parameters you need to transmit depends on the factory (see the factory documentation to know more).
For example, the ContentTool needs to know what content to open, if it has to open it in read or write mode...
For example, the SearchTool needs no parameters ; but we could imagine, parameters will allow to pre-input the search form. This will authorize buttons like "Search for deleted contents" that simply have 1 line of code (opening the search with the right parameters).
Writing a tool
Events and refresh
When writing a tool you are automatically registered in the message bus.
You will need to refresh data when receiving events, but the philosophy is to do not ! :) Have a look to the following scheme.
The methods you need to call in your tool are :
- this.setTooltip : to change your tooltip
- this.refreshing : to animate the refresh status while requesting the server
- this.stopRefreshing : when finished
- this.outOfDate : to make your tool out of date. A parameter makes you choose between minor out of date (the data are still visible but a flag indicates they may be false) or major out of date (the data are no more visible)
- this.upToDate : when your tool is finally up to date
- this.activate : to make your tool visible if in background
Please read the notes for Tools on the MessageBus document : you should send in most case a null selection on close, and at least a null selection on focus.
Minor or major out of date ?
Minor out of date mode has to be set when the data you are displaying are still pertinent but may be out of date.
Major out of date mode has to be set when the data you are displaying are not pertinent.
For example, the DetailsTool is displaying information about the content X. If the content X has changed its metadata, the tool goes minor out of date. If the user is selecting content Y, the tool goes major out of date (we do not want the tool to be unsynchronize with other tools)
Resfreshing trick
Be aware about the following problems.
You are outOfDate major, but finally the user re-select the previous information. It would be nice to display it without reloading.
While refreshing the user change its selection, do not display the information received from server.
Selection message can be the same several times : do not reload each time.
Back to top