There are many places inside ECMS which are built basing on the UI Extensions framework as described in [Extend eXo applications|../../../developer-guide/html/DEV.ExtendeXoApplications.html], so you can add your own actions packaged in external jars to them. They are:

* *Action bar*

!images/actionbar.png|align="center" width="120mm" fo:scalefix="1" html:scalefix="0"!

* *Side bar*

!images/sidebar.png|align="center" width="50mm" fo:scalefix="1" html:scalefix="0"!

* *Admin control panel*

!images/admin_control_panel.png|align="center" width="50mm" fo:scalefix="1" html:scalefix="0"!

* *Context menu in the main working area*

!images/context_menu.png|align="center" width="50mm" fo:scalefix="1" html:scalefix="0"!

* *File viewer*

!images/file_viewer.png|align="center" width="80mm" fo:scalefix="1" html:scalefix="0"!

h1. How to add an action extension {anchor:id=CONTref.ExtendUIExtension.HowToAddActionExtension}

This section shows you how to add own actions to the ECMS. In the following example, you are going to add a new action on the ECMS action toolbar to view the node path.

Follow the below process to add a new action to the action toolbar:

{docbook}
<para>
<citetitle>
<emphasis role="bold">
Create a new project for action extension
</emphasis>
</citetitle>
</para>
{docbook}

Create a Maven project which has the following directory structure:

!images/folder_structure.png|align="center" width="80mm" fo:scalefix="1" html:scalefix="0"!

Navigating in the project's folder, you will see the following structure:

* _pom.xml_: The project's POM file.
* _src/main/java/.../ExampleActionComponent.java_: A simple action supporting user to view the wiki markup of a page.
* _src/main/resources/conf/portal/configuration.xml_: The configuration file to register your actions with the _org.exoplatform.webui.ext.UIExtensionManager_ service.

Here is the content of the _pom.xml_ file:

{code:xml}<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
 <modelVersion>4.0.0</modelVersion>

 <groupId>com.acme</groupId>
 <artifactId>example</artifactId>
 <version>1.0-SNAPSHOT</version>
 <packaging>jar</packaging>

 <name>example</name>
 <url>ECMS action example</url>

 <properties>
   <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
 </properties>
 <dependencies>
   <dependency>
     <groupId>org.exoplatform.portal</groupId>
     <artifactId>exo.portal.webui.core</artifactId>
     <version>3.2.5-PLF-SNAPSHOT</version>
     <scope>provided</scope>
   </dependency>
   <dependency>
     <groupId>org.exoplatform.commons</groupId>
     <artifactId>exo.platform.commons.webui.ext</artifactId>
     <version>1.1.9-SNAPSHOT</version>
     <scope>provided</scope>
   </dependency>
   <dependency>
     <groupId>org.exoplatform.ecms</groupId>
     <artifactId>exo-ecms-core-webui-explorer</artifactId>
     <version>2.3.8-SNAPSHOT</version>
   </dependency>
 </dependencies>
 <build>
   <plugins>
     <plugin>
       <groupId>org.apache.maven.plugins</groupId>
       <artifactId>maven-compiler-plugin</artifactId>
       <configuration>
         <source>1.5</source>
         <target>1.5</target>
       </configuration>
     </plugin>
   </plugins>
 </build>
</project>{code}


{docbook}
<para>
<citetitle>
<emphasis role="bold">
Create new action and its corresponding listener
</emphasis>
</citetitle>
</para>
{docbook}

Edit the _ExampleActionComponent_ class as below:

{code:java}
package com.acme;

import javax.jcr.Node;

import org.exoplatform.ecm.webui.component.explorer.UIJCRExplorer;
import org.exoplatform.ecm.webui.component.explorer.control.listener.UIActionBarActionListener;
import org.exoplatform.web.application.ApplicationMessage;
import org.exoplatform.webui.config.annotation.ComponentConfig;
import org.exoplatform.webui.config.annotation.EventConfig;
import org.exoplatform.webui.core.UIComponent;
import org.exoplatform.webui.event.Event;

@ComponentConfig(
 events = { @EventConfig(listeners = ExampleComponent.ExampleActionListener.class) 
})
public class ExampleComponent extends UIComponent {

  public static class ExampleActionListener extends UIActionBarActionListener<ExampleComponent> {
    @Override
    protected void processEvent(Event<ExampleComponent> event) throws Exception {
      UIJCRExplorer uiJCRExplorer = event.getSource().getAncestorOfType(UIJCRExplorer.class);
      Node node = uiJCRExplorer.getCurrentNode();
      event.getRequestContext()
           .getUIApplication()
           .addMessage(new ApplicationMessage("Node path:"  node.getPath(), null, ApplicationMessage.INFO));
    }
  }

}
{code}


{docbook}
<para>
<citetitle>
<emphasis role="bold">
Register new action with UIExtensionManager
</emphasis>
</citetitle>
</para>
{docbook}

Edit the _configuration.xml_ file as below:
{code:xml}<?xml version="1.0" encoding="UTF-8"?>
<configuration xmlns="http://www.exoplatform.org/xml/ns/kernel_1_2.xsd"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="http://www.exoplatform.org/xml/ns/kernel_1_2.xsd http://www.exoplatform.org/xml/ns/kernel_1_2.xsd">

 <external-component-plugins>
   <target-component>org.exoplatform.webui.ext.UIExtensionManager</target-component>
   <component-plugin>
     <name>add.action</name>
     <set-method>registerUIExtensionPlugin</set-method>
     <type>org.exoplatform.webui.ext.UIExtensionPlugin</type>
     <init-params>
       <object-param>
         <name>Example</name>
         <object type="org.exoplatform.webui.ext.UIExtension">
           <field name="type">
             <string>org.exoplatform.ecm.dms.UIActionBar</string>
           </field>
           <field name="name">
             <string>Example</string>
           </field>
           <field name="component">
             <string>com.acme.ExampleComponent</string>
           </field>
         </object>
       </object-param>
     </init-params>
   </component-plugin>
 </external-component-plugins>

</configuration>{code}

h1. Deploy new action extension {anchor:id=CONTref.ExtendUIExtension.DeployNewActionExtension}
Follow these steps to deploy your new action extension:

*1.* Build the project by using the _mvn clean install_ command.

*2.* Copy the _target/example-1.0-SNAPSHOT.jar_ file into the _TOMCAT\-HOME/lib/_ directory.

*3.* Run Tomcat and go to *Content explorer*.

*4.* Add the deployed action to the WCM View. You will get the results:

!images/extendUI_result1.png|align="center" width="120mm" fo:scalefix="1" html:scalefix="0"!

!images/extendUI_result3.png|align="center" width="120mm" fo:scalefix="1" html:scalefix="0"!

!images/extendUI_result2.png|align="center" width="120mm" fo:scalefix="1" html:scalefix="0"!

h1. Define labels and logo {anchor:id=CONTref.ExtendUIExtension.DefineLableAndLogo}

{docbook}
<para>
<citetitle>
<emphasis role="bold">
Define a label in ECM Administration
</emphasis>
</citetitle>
</para>
{docbook}

Edit the _$TOMCAT\-HOME/webapps/ecmadmin/WEB-INF/classes/locale/portlet/administration/ECMAdminPortlet\_en.xml_ file (for English which is also the default language) and add the label as below:

{code:xml}
...
 <UIViewFormTabPane>
    ...
   <label>
     <example>Example action</example>
    ...
   </label>
    ...
 </UIViewFormTabPane>
...
{code}

{docbook}
<para>
<citetitle>
<emphasis role="bold">
Define a label in the File Explorer
</emphasis>
</citetitle>
</para>
{docbook}

Edit the _$TOMCAT\-HOME/webapps/ecmexplorer/WEB-INF/classes/locale/portlet/explorer/JCRExplorerPortlet\_en.xml_ file (for English which is also the default language) and add the label as below:

{code:xml}...
 <UIActionBar>
    ...
   <tooltip>
     <example>Example action</example>
    ...
   </tooltip>
    ...
 </UIActionBar>
...{code}

{docbook}
<para>
<citetitle>
<emphasis role="bold">
Define Logos
</emphasis>
</citetitle>
</para>
{docbook}

Edit the _$TOMCAT-HOME/webapps/ecmexplorer/skin/icons/24x24/DefaultStylesheet.css_ file (for the default Skin) and add the icon definition as below
(in this case, the "ManageUnLock" icon is re-used but you could add your own picture into the _$TOMCAT\-HOME/webapps/ecmexplorer/skin/icons/24x24/DefaultSkin_ directory):

{code:xml}.ExampleIcon{
  width: 24px; height: 24px;
  background: url('DefaultSkin/ManageUnLock.gif') no-repeat left center; /* orientation=lt */
  background: url('DefaultSkin/ManageUnLock.gif') no-repeat right center; /* orientation=rt */
}{code}

h1. Filter your action {anchor:id=CONTref.ExtendUIExtension.FilterYourAction}

With the UI Extension framework, you can use internal and external (existing) filters. The internal filters are parts of the business logic of your component. For example, if your component is only dedicated to articles, you will add an internal filter to your component that will check the type of the current document. The external filters are mainly used to add new filters that are not related to the business logic, to your component. A good example is the _UserACLFilter_ which allows you to filter by access permissions.

It is very simple to apply a filter in an UI component:

{code:java}public class ExampleComponent extends UIComponent {

    private static final List<UIExtensionFilter> FILTERS = Arrays.asList(new UIExtensionFilter[] {new MyUIFilter()});

@UIExtensionFilters
public List<UIExtensionFilter> getFilters() {
return FILTERS;
}
...{code}

h2. Use existing filters {anchor:id=CONTref.ExtendUIExtension.UseExistingFilter}

There are many useful built-in filters in ECMS:

* {{org.exoplatform.webui.ext.filter.impl.UserACLFilter}}: Filter all nodes that do not have any permission on the current context.
* {{org.exoplatform.webui.ext.filter.impl.FileFilter}}: Filter all nodes that do not exist in the given MIME type list.
* {{org.exoplatform.ecm.webui.component.explorer.control.filter}}: This package includes the following filters.

|| Filters || Description||
|{{CanAddCategoryFilter}}|Filter nodes to which it is impossible to add categories.|
|{{CanCutNodeFilter}}|Filter nodes which cannot be cut.|
|{{CanAddNodeFilter}}|Filter nodes to which it is impossible to add nodes.|
|{{CanDeleteNodeFilter}}|Filter nodes that cannot be deleted.|
|{{CanRemoveNodeFilter}}|Filter nodes that cannot be removed.|
|{{CanEnableVersionFilter}}|Filter nodes which do not allow versioning.|
|{{CanSetPropertyFilter}}|Filter nodes that cannot be modified.|
|{{HasMetadataTemplatesFilter}}|Filter nodes that do not have metadata templates.|
|{{HasPublicationLifecycleFilter}}|Filter all nodes that do not have the publication plugins.|
|{{HasRemovePermissionFilter}}|Filter nodes that do not have the *Remove* permission.|
|{{IsFavouriteFilter}}|Filter nodes that are not favorite.|
|{{IsNotFavouriteFilter}}|Filter nodes that are favorite.|
|{{IsNotNtFileFilter}}|Filter nodes that are of _nt\:file_. |
|{{IsHoldsLockFilter}}|Filter nodes which do not hold lock.|
|{{IsNotHoldsLockFilter}}|Filter nodes which are holding lock.|
|{{IsNotRootNodeFilter}}|Filter the root node.|
|{{IsInTrashFilter}}|Filter nodes that are not in the trash node.|
|{{IsNotInTrashFilter}}|Filter nodes that are in the trash node.|
|{{IsNotSameNameSiblingFilter}}|Filter nodes that allow the same name siblings.|
|{{IsMixCommentable}}|Filter nodes that do not allow commenting.|
|{{IsMixVotable}}|Filter nodes that do not allow voting.|
|{{IsNotSimpleLockedFilter}}|Filter nodes that are locked.|
|{{IsNotSymlinkFilter}}|Filter nodes that are symlinks.|
|{{IsNotCategoryFilter}}|Filter nodes that are of the category type.|
|{{IsNotSystemWorkspaceFilter}}|Filter actions of the system-typed workspace.|
|{{IsNotCheckedOutFilter}}|Filter nodes that are checked out.|
|{{IsTrashHomeNodeFilter}}|Filter nodes that are not trash ones.|
|{{IsNotTrashHomeNodeFilter}}|Filter a node that is the trash one.|
|{{IsNotEditingDocumentFilter}}|Filter nodes that are being edited. |
|{{IsPasteableFilter}}|Filter nodes where the *paste* action is not allowed.|
|{{IsReferenceableNodeFilter}}|Filter nodes that do not allow adding references.|
|{{IsNotFolderFilter}}|Filter nodes that are folders.|
|{{IsCheckedOutFilter}}|Filter nodes that are not checked out.|
|{{IsVersionableFilter}}|Filter nodes which do not allow versioning.|
|{{IsVersionableOrAncestorFilter}}|Filter nodes and ancestor nodes which do not allow versioning.|
|{{IsDocumentFilter}}|Filter nodes that are not documents.|
|{{IsEditableFilter}}|Filter nodes that are not editable.|

h2. Create your own filters {anchor:id=CONTref.ExtendUIExtension.CreateYourOwnFilters}

Beside using existing ones, you can also create new filters. See the example code below:

{code:java}public class MyUIFilter implements UIExtensionFilter {

/**
* This method checks if the current node is of the right type
*/
public boolean accept(Map<String, Object> context) throws Exception {
// Retrieve the current node from the context
   Node currentNode = (Node) context.get(Node.class.getName());
return currentNode.isNodeType("exo:article");
}

/**
* This is the type of the filter
*/
public UIExtensionFilterType getType() {
return UIExtensionFilterType.MANDATORY;
}

/**
* This is called when the filter has failed
*/
public void onDeny(Map<String, Object> context) throws Exception {
System.out.println("This document has been rejected");
}
}{code}

h1. Other toolbars {anchor:id=CONTref.ExtendUIExtension.OtherToolbars}

Working with other toolbars is quite similar to _UIActionbar_, except configurations and resources.

{docbook}
<para>
<citetitle>
<emphasis role="bold">
Side bar
</emphasis>
</citetitle>
</para>
{docbook}

* *Sample configuration*

{code:xml}<object-param>
 <name>Example</name>
 <object type="org.exoplatform.webui.ext.UIExtension">
   <field name="type"><string>org.exoplatform.ecm.dms.UISideBar</string></field>
   <field name="name"><string>Example</string></field>
   <field name="rank"><int>110</int></field>
   <field name="component"><string>com.acme.ExampleActionComponent</string></field>
 </object>
</object-param>{code}

Resources are located at  _$TOMCAT\-HOME/webapps/ecmexplorer/WEB-INF/classes/locale/portlet/explorer/JCRExplorerPortlet\_en.xml_ (for English which is also the default language):

{code:xml}...
 <UISideBar>
    ...
   <label>
     <example>Example action</example>
    ...
   </label>
    ...
 </UISideBar>
...{code}

{docbook}
<para>
<citetitle>
<emphasis role="bold">
Admin control panel
</emphasis>
</citetitle>
</para>
{docbook}

* *Sample configuration*

{code:xml}<object-param>
 <name>Example</name>
 <object type="org.exoplatform.webui.ext.UIExtension">
   <field name="type"><string>org.exoplatform.ecm.dms.UIECMAdminControlPanel</string></field>
   <field name="rank"><int>110</int></field>
   <field name="name"><string>Example</string></field>
   <field name="category"><string>Ontologies</string></field>
   <field name="component"><string>com.acme.ExampleActionComponent</string></field>
 </object>
</object-param>{code}

The "category" field specifies the category where your extension action is performed. There are 4 options:

* Ontology

!images/Ontologies.png|align="center" width="60mm" fo:scalefix="1" html:scalefix="0"!

* ContentPresentation

!images/ContentPresentation.png|align="center" width="60mm" fo:scalefix="1" html:scalefix="0"!

* Content Type

!images/ContentType.png|align="center" width="60mm" fo:scalefix="1" html:scalefix="0"!

* Advanced Configuration

!images/AdvancedConfigurations.png|align="center" width="60mm" fo:scalefix="1" html:scalefix="0"!

Resources are located at _$TOMCAT\-HOME/webapps/ecmadmin/WEB-INF/classes/locale/portlet/administration/ECMAdminPortlet\_en.xml_ (for English which is also the default language):

{code:xml}...
 <UIECMAdminControlPanel>
    ...
   <label>
     <example>Example panel</example>
    ...
   </label>
    ...
 </UIECMAdminControlPanel>
...{code}

{docbook}
<para>
<citetitle>
<emphasis role="bold">
Context menu
</emphasis>
</citetitle>
</para>
{docbook}

* *Sample configuration*

{code:xml}<object-param>
 <name>Example</name>
 <object type="org.exoplatform.webui.ext.UIExtension">
   <field name="type"><string>org.exoplatform.ecm.dms.UIWorkingArea</string></field>
   <field name="rank"><int>105</int></field>
   <field name="name"><string>Example</string></field>
   <field name="category"><string>ItemContextMenu_SingleSelection</string></field>
   <field name="component"><string>com.acme.ExampleActionComponent</string></field>
 </object>
</object-param>{code}

The "category" field specifies the category where your extension action is performed. There are many options:

* {{ItemContextMenu\_SingleSelection}}: This menu has only one item when Trash Folder is right-clicked.
* {{ItemContextMenu}}: The menu appears when the user selects one or many items.
* {{GroundContextMenu}} & {{ItemGroundContextMenu}}: The menu appears when the user right-clicks the ground of node.

Resources are located at _$TOMCAT\-HOME/webapps/ecmexplorer/WEB-INF/classes/locale/portlet/explorer/JCRExplorerPortlet\_en.xml_ (for English which is also the default language):

{code:xml}<UIWorkingArea>
    ...
   <label>
     <example>Example action</example>
    ...
   </label>
    ...
</UIWorkingArea>{code}

{docbook}
<para>
<citetitle>
<emphasis role="bold">
File Viewer
</emphasis>
</citetitle>
</para>
{docbook}

* *Sample configuration*

{code:xml}<object-param>
 <name>Example</name>
 <object type="org.exoplatform.webui.ext.UIExtension">
   <field name="type"><string>org.exoplatform.ecm.dms.FileViewer</string></field>
   <field name="rank"><int>100</int></field>
   <field name="name"><string>Example</string></field>
   <field name="category"><string>FileViewer</string></field>
   <field name="component"><string>com.acme.ExampleActionComponent</string></field>
   <field name="extendedFilters">
     <collection type="java.util.ArrayList">
       <value>
         <object type="org.exoplatform.webui.ext.filter.impl.FileFilter">
           <field name="mimeTypes">
             <collection type="java.util.ArrayList">
               <value><string>foo/bar</string></value>
             </collection>
           </field>
         </object>
       </value>
      </collection>
    </field>
 </object>
</object-param>{code}

Resources are located at _$TOMCAT\-HOME/webapps/ecm-wcm-extension/WEB-INF/classes/locale/ecm/views\_en.xml_ (for English which is also the default language):

{code:xml}<File>
   <view>
     <example>Example view</example>
    ...
   </view>
 </File>{code}