Elvis 4 action plug-ins - configuration

Configuration settings for an action plug-in are defined in the action.config.xml file, which contains general plug-in information (A), advanced action settings (B) and plug-in specific settings (C).

plug-in specific settings are documented for each individual plug-in.

Configuration file

<?xml version="1.0" encoding="UTF-8"?>
<plugin>
    <info>
        (A)
    </info>
    <action>
        (B)
    </action>
    <config>
        (C)
    </config>
</plugin>

Advanced plug-in configuration (B)

Generic action config settings are advanced and intended to be configured by plug-in developers. The action plug-in configuration is quite extensive, this section contains a brief explanation for each setting.

<action>
(1)     <url>...</url>
(2)     <icon16Url>...</icon16Url>
(3)     <icon24Url>...</icon24Url>
(4)     <userInterface>...</userInterface>
(5)     <menuAssignments>...</menuAssignments>
(6)     <userAgents>...</userAgents>
(7)     <enabledExpression>...</enabledExpression>
(8)     <filterExpression>...</filterExpression>
(9)     <requiredPermissionMask>...</requiredPermissionMask>
(10)    <requiredRoles>...</requiredRoles>
(11)    <flattenContainersInSelection>...</flattenContainersInSelection>
(12)    <removeContainersFromSelection>...</removeContainersFromSelection>
(13)    <keyBindings>...</keyBindings>
(14)    <messages>...</messages>
</action>

• (1) url - required. Web page that will be loaded when the plug-in is executed. The main page and it's resources can be hosted inside the plug-in folder, but it can also be on an external server as HTML, PHP, ASP, JSP, etc.
• (2) icon16Url - required. Plug-in icon image URL, 16x16 pixels, currently not used, defined for future reference.
• (3) icon24Url - required. Plug-in icon image URL, 24x24 pixels, used for the plug-ins' toolbar button.
• (4) userInterface - required. Controls where the plug-in URL is opened: in a tab, a dialog or in an external web browser.
• (5) menuAssignments - required. Controls from which menu(s) the plug-in is available, this can be combination of: the application menu, the main button toolbar, the asset context menu and the folder context menu.
• (6) userAgents - optional. Platform specific user agent used when loading the URL in a tab or dialog. Replaces the default AIR user agent.
• (7) enabledExpression - optional. Expression to check if the current asset or folder selection is valid. For example, the plug-in is only available when there is just one asset selected.
• (8) filterExpression - optional. Expression to validate an individual asset or folder. For example, the plug-in exclusively works with video assets.
• (9) requiredPermissionMask - optional. Permission mask validation to check if the current asset or folder selection is valid. For example, a user needs EDIT permission on the selection to perform the action.
• (10) requiredRoles - optional. Required roles for the plug-in to become visible. Standard and custom roles can be configured. For example, a user needs ROLE_DOWNLOAD or ROLE_CUSTOM_ACTION_MYACTION to perform the action.
• (11) flattenContainersInSelection - optional. If true, load container assets (like collections) and provide a "flat" selection of unique assets in the elvisContext. Default value is true.
• (12) removeContainersFromSelection - optional. If true, remove all container assets (like collections) from the selection in the elvisContext. Default value is true.
• (13) keyBindings - optional. Platform specific keyboard bindings.
• (14) messages - required. Button labels, menu labels, tooltips, etc. configurable per locale.

Examples

Minimal action plug-in configuration

<action>
    <url>${pluginBaseUrl}l/index.html</url>
    <icon16Url>${pluginBaseUrl}/icon16.png</icon16Url>
    <icon24Url>${pluginBaseUrl}/icon24.png</icon24Url>
    
    <userInterface>
        <tab/>
    </userInterface>
    
    <menuAssignments>
        <menuAssignment id="toolBar" order="5"/>
    </menuAssignments>
    
    <messages>
        <entries locale="en_US">
            <entry key="button.label">My action label</entry>
            <entry key="button.tooltip">My action tooltip info</entry>
            <entry key="title">My action tab or dialog title</entry>
        </entries>
    </messages>
    
</action>

Action plug-in configuration with all options

<action>
    <url>${pluginBaseUrl}/index.html</url>
    <icon16Url>${pluginBaseUrl}/icon16.png</icon16Url>
    <icon24Url>${pluginBaseUrl}/icon24.png</icon24Url>
    
    <userInterface>
        <dialog width="900" height="900"/>
    </userInterface>
    
    <menuAssignments>
        <menuAssignment id="applicationMenu" order="3"/>
        <menuAssignment id="toolBar" order="5"/>
        <menuAssignment id="assetContextMenu" order="1"/>
        <menuAssignment id="folderContextMenu" order="3"/>
    </menuAssignments>
    
    <userAgents>
        <userAgentMacOSX>Mozilla/5.0 (Macintosh; Intel Mac OS X 10_6_8) AppleWebKit/535.1 (KHTML, like Gecko) Chrome/14.0.835.186 Safari/535.1</userAgentMacOSX>
        <userAgentWindows>Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/535.1 (KHTML, like Gecko) Chrome/14.0.835.186 Safari/535.1</userAgentWindows>
    </userAgents>

    <enabledExpression>elvisContext.hasFilteredSelection()</enabledExpression>
    
    <filterExpression>item.hasAssetDomain("video") || item.hasAssetDomain("image")</filterExpression>
    
    <requiredPermissionMask>VP-------</requiredPermissionMask>
    
    <requiredRoles>
        <role>ROLE_DOWNLOAD</role>
        <role>ROLE_CUSTOM_ACTION_MY_DIALOG</role>
    </requiredRoles>

    <keyBindings>
        <keyBinding os="Windows" key="h" modifiers="CTRL,SHIFT,ALT"/>
        <keyBinding os="MacOSX" key="h" modifiers="CMD,SHIFT,ALT"/>
    </keyBindings>
    
    <flattenContainersInSelection>true</flattenContainersInSelection>
    
    <removeContainersFromSelection>true</removeContainersFromSelection>
    
    <messages>
        <entries locale="en_US">
            <entry key="button.label">My action label</entry>
            <entry key="button.tooltip">My action tooltip info</entry>
            <entry key="title">My action tab or dialog title</entry>
        </entries>
        <entries locale="nl_NL">
            <entry key="button.label">Mijn actie dialoog</entry>
            <entry key="button.tooltip">Mijn actie tooltip informatie</entry>
            <entry key="title">Mijn actie tab of dialoog titel</entry>
        </entries>
    </messages>
    
</action>