Creating Portlets - Documentation topics on: creating portlets,jsp portlet,portlet,portlets,struts,struts portlet,velocity,velocity portlet,.

Creating Portlets

There are three main types of portlets typically created in dotCMS, the Velocity, Struts or JSP Portlet. It is possible to create other types of portlets though i.e... Spring Portlet

JSP Portlets

All new dotCMS portlets have been created as a JSP portlet. You can see the Site Search Manager portlet as an example

To configure a JSP portlet you must configure your portlet in the portlet-ext.xml on a plugin like this:

  <portlet>
    <portlet-name>EXT_SITESEARCH</portlet-name>
    <display-name>Site Search Manager</display-name>
    <portlet-class>com.liferay.portlet.JSPPortlet</portlet-class>
    <init-param>
        <name>view-jsp</name>
        <value>/portlet/ext/sitesearch/site_search.jsp</value>
    </init-param>
  </portlet>

Struts Portlet

This is how most of the dotCMS portlets are configured. It is more complex then the Velocity portlet though. You do get the advantages of using Struts. You can take advantage of Struts Actions and Struts Forwards. We recommend that you only use the Struts Portlet if you really feel you need these features or desire to use JSPs for the View component of your portlet. 

To configure the struts portlet you must first configure your portlet in the portlet-ext.xml

<portlet>
    <portlet-name>EXT_STRUTS_HELLO_WORLD</portlet-name>
    <display-name>Struts Hello World Example</display-name>
    <portlet-class>com.liferay.portlet.StrutsPortlet</portlet-class>
    <init-param>
      <name>view-action</name>
      <value>/ext/strutshello/view_hello</value>
    </init-param>
    <expiration-cache>0</expiration-cache>
    <supports>
      <mime-type>text/html</mime-type>
    </supports>
    <resource-bundle>com.liferay.portlet.StrutsResourceBundle</resource-bundle>
    <security-role-ref>
      <role-name>CMS Administrator</role-name>
    </security-role-ref>
    <security-role-ref>
      <role-name>CMS User</role-name>
    </security-role-ref>
  </portlet>

Basically the view-action maps to your struts-config-ext.xml within your plugin.

<action path="/ext/strutshello/view_hello" type="com.dotmarketing.plugins.hello.world.portlet.struts.ViewHelloWorld">
  <forward name="portlet.ext.plugins.hello.world.struts" path="portlet.ext.plugins.hello.world.struts">
  <forward name="portlet.ext.plugins.hello.world.struts.max" path="portlet.ext.plugins.hello.world.struts.max">
</forward></forward></action>

Next you would need to set up the Struts forwards in the tiles-defs-ext.xml

<definition name="portlet.ext.plugins.hello.world.struts" extends="portlet_default">
  <put name="portlet_content" value="/plugins/hello.world/strutshelloworld/view.jsp">
</put></definition>

<definition name="portlet.ext.plugins.hello.world.struts.max" extends="portlet_default">
  <put name="portlet_content" value="/plugins/hello.world/strutshelloworld/view_hello.jsp">
</put></definition>

Finally you must configure the liferay-portlet-ext.xml

<portlet id="EXT_STRUTS_HELLO_WORLD" struts-path="ext/strutshello" narrow="true">

Velocity Portlets

Velocity portlets are much easier to configure then the Struts portlet. Basically you configure the portlet and point it at a file with velocity code. One thing that some members of the dotCMS team have done here is to configure this page to control or direct the flow of your application. It might be a page that has code like this

#set($action = $request.getParameter("myaction"))
#if(!$UtilMethods.isSet($action))
  #parse("/path/to/default.vtl")
#else if($action.equals("add"))
  #parse("/path/to/add.vtl")
#end

To configure your Velocity Portlet add a portlet configuration to the portlet-ext.xml

<portlet>
  <portlet-name>EXT_HELLO_WORLD</portlet-name>
  <display-name>HELLO WORLD</display-name>
  <portlet-class>com.liferay.portlet.VelocityPortlet</portlet-class>
  <init-param>
      <name>view-template</name>
      <value>/static/plugins/hello.world/portlet/view.vm</value>
  </init-param>
  <expiration-cache>0</expiration-cache>
  <supports>
    <mime-type>text/html</mime-type>
  </supports>
  <resource-bundle>com.liferay.portlet.StrutsResourceBundle</resource-bundle>
  <security-role-ref>
    <role-name>CMS User</role-name>
  </security-role-ref>
</portlet>

In this case the view.vm lives under the static_velocity/portlet directory of your plugin.

You also need to configure the liferay-portlet-ext.xml as follows

<portlet id="EXT_HELLO_WORLD" struts-path="hello_velocity" narrow="true">

For both portlets you can configure the Language files to handle the portlets name. In the hello.world example this is done directly in the Language-ext.properties file in the plugin's conf directory
javax.portlet.title.EXT_HELLO_WORLD=Test Velocity Portlet 
javax.portlet.title.EXT_STRUTS_HELLO_WORLD=Test Struts Hello World

The plugins don't currently provide a merge into the display file to categorize the portlet but this can be done by hand if needed.