The Document Action sample shows how to add a context menu option to an entry in the Documents and Media portlet. When deploying this sample with no customizations, an additional menu option is available in the Documents and Media Admin portlet and the Documents and Media portlet. This sample creates a Blade Basic Info option that displays basic information about the entry (e.g., file name, type, version, etc.). For example, the Admin portlet provides the new option as illustrated in the images below:
Figure 1: The new *Blade Basic Info* option is available from the entry's Options menu.
Figure 2: The new option is also available from the portlet's Document Details.
Likewise, the Documents and Media portlet provides the same option after selecting Show Actions from the portlet’s Configuration menu.
Figure 3: You can access the new *Blade Basic Info* option from the Documents and Media portlet added to a page.
Figure 4: The Documents And Media portlet provides the option from its Document Detail too.
What API(s) and/or code components does this sample highlight?
This sample leverages the PortletConfigurationIcon API.
How does this sample leverage the API(s) and/or code component?
There are four Java classes used in this sample:
BladeActionConfigurationIcon: Adds the new context menu option to the Document Detail screen options () (top right corner) of the Documents and Media Admin portlet. See the Configuring Your Admin App’s Actions Menu tutorial for more details.
BladeActionDisplayContext: Adds the Display Context for the document action. More about Display Contexts are described later.BladeActionDisplayContextFactory: Adds the Display Context factory for the document action.BladeDocumentActionPortlet: Provides the portlet class, which extends the GenericPortlet. This class generates what is shown when the context menu option is selected.
A Display Context is a Java class that controls access to a portlet screen’s UI elements. For example, the Document Library would use Display Contexts to provide its screens all their UI elements. It would use one Display Context for its document edit screen, another for its document view screen, etc. A portlet ideally uses a different Display Context for each of its screens.
A screen’s JSP calls on the Display Context (DC) to get elements to render and to decide whether to render certain types of elements. Some of the DC methods return a collection of UI elements (e.g., a menu object of menu items), while other DC methods return booleans that determine whether to show particular element types. The DC decides which objects to display, while the JSP organizes the rendered objects and implements the screen’s look and feel. You don’t have to decide which elements to display in your JSP; simply call the DC methods to populate UI components with objects to render.
To customize or extend a portlet screen that uses a DC, you can extend the DC and override the methods that control access to the elements that interest you. For example, you can turn off displaying certain types of elements (e.g., actions) by overriding the DC method that makes that decision. You can add new custom elements (e.g., new actions) or remove existing elements (e.g., a delete action) from a collection of elements a DC method returns. The beauty of customizing via a DC is that you don’t have to modify the JSP. You only modify the particular methods that are related to the UI customization goals. And JSP updates won’t break the DC customizations. Replacing a JSP, on the other hand, can lead to missing an important JSP modification that a new Liferay version introduces.
As you create custom portlets, you may want to implement DCs. You can benefit from the separation of concerns that DCs provide and customers can extend your portlet DCs to specify which UI elements to display. And they don’t need to worry about missing out on the updates you make to the JSPs.
Where Is This Sample?
There are three different versions of this sample, each built with a different build tool: