How to add action links to a module

Action links are hooks into the user interface that can be created directly in the database without having to change any code. At most you will have to create new code to attend to the new actions.

These actions will be easily upgradeable going forward as they are saved in the database and no base code changes are required.

We have links to enhance the List View, the Detail View and some special hooks to load CSS and javascript to react to the new actions. See below for more information.

Adding a new action can be done in two ways. The first is when creating a module in it's manifest file. There is a specific section there to add custom links that looks like this:

<customlinks>
<customlink>
<linktype>DETAILVIEWWIDGET</linktype>
<linklabel>Execute</linklabel>
<linkurl><![CDATA[module=cbupdater&action=cbupdaterAjax&file=cbupdaterWidget&record=$RECORD$]]></linkurl>
<linkicon><![CDATA[]]></linkicon>
<sequence>0</sequence>
<handler_path><![CDATA[]]></handler_path>
<handler_class><![CDATA[]]></handler_class>
<handler><![CDATA[]]></handler>
</customlink>
<customlink>
<linktype>LISTVIEWBASIC</linktype>
<linklabel>GetUpdates</linklabel>
<linkurl><![CDATA[javascript:gotourl('index.php?module=cbupdater&action=getupdates')]]></linkurl>
<linkicon><![CDATA[]]></linkicon>
<sequence>0</sequence>
<handler_path><![CDATA[]]></handler_path>
<handler_class><![CDATA[]]></handler_class>
<handler><![CDATA[]]></handler>
</customlink>
</customlinks>

The above code is extracted from the coreBOSUpdater manifest.xml file. It adds a DETAILVIEWWIDGET and a LISTVIEWBASIC action. As can be seen the action has these parameters:

linktypeType of Link like DETAILVIEW etc..
linklabelLabel to use for the link when displaying (will be translated)
linkurlURL of the action link. You can use the special variables $RECORD$ which will evaluate to the current record ID and $MODULE$ which evaluates to the current module
linkiconpath to a small 16×16 icon to show before the DETAILVIEWBASIC action link
sequenceorder in which the actions should be displayed
handler_pathcurrently not used
handler_classcurrently not used
handlercurrently not used

The second form is for when we have an already installed module and we want to modify it. In this case we have to load the vtlib programming API, get a link to our module and execute the addLink() method. This looks like this:

include_once('vtlib/Vtiger/Module.php');
$module = Vtiger_Module::getInstance('Contacts');
$module->addLink('LISTVIEWBASIC', 'LBL_SELECT_ALL', 'toggleSelectAllEntries_ListView();');

or

include_once('vtlib/Vtiger/Module.php');
$mod_acc = Vtiger_Module::getInstance('Accounts');
$mod_acc->addLink('DETAILVIEWBASIC', 'Add Ticket', 'index.php?module=HelpDesk&action=EditView&parent_id=$RECORD$');

The first example adds a button to the list view of the contacts module while the second adds a link to the right action panel of accounts.

You can get a copy of the full script in the build/HelperScripts directory of coreBOS.

We have two possible options on the list view. The LISTVIEWBASIC value will add a new button on the list view exactly the same as the already existing buttons, while the LISTVIEW value will add the link to a “More actions” drop down menu.

We have three types of possible actions on the detail view screen. The DETAILVIEWBASIC option will add a link to the right action panel, at the same level as the normal existing links. The DETAILVIEW option will add the link inside a “More Actions” drop down menu. This is useful when we have many options.

Finally the DETAILVIEWWIDGET option will permit us to add a small widget (box) on the right action panel, within which we will be able to execute some actions. Very useful to add functionality to the module.

The DETAILVIEWWIDGET URL is called within the context of the application, it does not need index.php because that will be called always. You simply have to add the MVC parameters. This will normally be in the form;

module={MODULE}&action={MODULE}Ajax&file={ACTION}...

As of coreBOS January 2015 any javascript code sent with the widget content will be executed automatically making it easy to load some additional libraries and/or execute some process.

You can study the Timecontrol module stop watch widget and also the Mass Image Upload widget on Products

Three other types of links exist that will permit us to insert CSS (HEADERCSS), javascript (HEADERSCRIPT) and a global drop down menu (HEADERLINK) with actions on the upper right button bar. See the next section for more information.

LinktypeDescription
LISTVIEWBASICButton on the list view
LISTVIEWDrop down menu on the list view
DETAILVIEWDrop down menu on the right action panel in detail view
DETAILVIEWBASICLink on the right action panel in detail view
DETAILVIEWWIDGETSmall widget block section at the bottom of the right action panel on detail view. Look at the Timecontrol stopwatch for an example. It can also be a full fledged block inserted into the existing field blocks
HEADERSCRIPTThe link will be treated as a javascript type and will be imported in the head section of the HTML output page as <script type='text/javascript' src='linkurl'></script>
HEADERCSSThe link will be treated as a CSS type and will be imported in the head section of the HTML output page as <link rel='stylesheet' type='text/css' href='linkurl>
HEADERLINKYou can see these link grouped under More on the top header panel. Useful if you want to provide utility tools like Bookmarklet etc.

coreBOS Documentación