8 Generating Actions Menus

This chapter describes how to generate Actions menus.

This chapter includes the following sections:

8.1 About Generating Actions Menus

In previous versions of Oracle WebCenter Content Server, when a component writer wanted to create an HTML table like those used on the search results page, HTML code had to be copied and pasted. The information in the tables was mixed with the HTML, with no separation between data and display.

The same issue was true for action menus. Data and display for the tables and menus were tightly coupled, making it impossible to perform global changes to all tables in Oracle WebCenter Content Server except for those changes done with CSS modifications. It was also difficult for components to target and modify specific aspects of both the tables and the menus.

To customize a page's action menu, a developer can override one of the following include files then modify the PageMenusData resultset. These includes are all defined in the DomainHome/resources/core/resources/std_page.idoc file:

  • custom_searchapi_result_menus_setup

  • custom_docinfo_menus_setup

  • custom_query_page_menus_setup

  • custom_audit_info_menus_setup

In addition, tables like the one used on the search results page can be created by setting up result sets of data then calling specific resource includes which use that data to display the page. Result sets can also be used to create action menus like those found on the Workflow In Queue and Search Results pages.

The action menu and HTML table display frameworks allow developers to create quick and flexible web pages that match the look and feel of the rest of the system. They also allow component writers to easily extend, add to, and override any or all of the Headline View or Thumbnail View tables on the server, and any of the action menus.

8.2 Creating Display Tables

Different display tables are used for the search results page for each display type:

  • Headline view

  • Thumbnail view

One of the first steps in any table setup is to retrieve documents to display, as Example 8-1 shows.

Example 8-1 Code to Retrieve Documents

<$QueryText = "dDocAuthor <matches> `sysadmin`"$>

8.2.1 Headline View Tables

The following example shows how to create a Headline View table. The concepts discussed here are also used to create the other table types.

The initial step in this process is to create a result set that describes the columns of the table, as Example 8-2 shows.

Example 8-2 ResultSet to Describe Table Columns

<$exec rsCreateResultSet("ColumnProperties",

<$exec rsAppendNewRow("ColumnProperties")$>
<$ColumnProperties.id = "dDocName"$>
<$ColumnProperties.width = "150px"$>
<$ColumnProperties.headerLabel = lc("wwDocNameTag")$>
<$ColumnProperties.rowAlign = "center"$>

<$exec rsAppendNewRow("ColumnProperties")$>
<$ColumnProperties.id = "dDocTitle"$>
<$ColumnProperties.width = "auto"$>
<$ColumnProperties.headerLabel = lc("wwTitle")$>
<$ColumnProperties.rowAlign = "left"$>

<$exec rsAppendNewRow("ColumnProperties")$>
<$ColumnProperties.id = "actions"$>
<$ColumnProperties.width = "75px"$>
<$ColumnProperties.headerLabel = lc("wwActions")$>
<$ColumnProperties.rowAlign = "center"$>

A result set called ColumnProperties is created. Each row in the table corresponds to a column on the table to be created. Each column can have several attributes associated with it. Some of the more common attributes are:

  • id: This is a mandatory attribute. Each column in the table being created must have an ID associated with it. The ID is used later to determine what will be displayed in every row.

  • width: The width of the column. This can be any CSS width declaration such as 100px, 15em, or auto, which causes the column to auto-size, filling as much of the table as possible.

  • headerLabel: The text to be displayed in the header of this column.

  • rowAlign: An indication of whether the contents should be left, right, or center aligned.

  • headerURL: Used to link the column header text to a URL.

The next step is to specify what data will be displayed in each row of the table, as Example 8-3 shows.

Example 8-3 Data to Display in a Result Set

<$exec rsCreateResultSet("RowData","dDocName,dDocTitle,actions")$>
<$exec rsAppendNewRow("RowData")$>
<$RowData.dDocName = "<$dDocName$>"$>
<$RowData.dDocTitle = "<$dDocTitle$>"$>
<$RowData.actions = "<$include doc_info_action_image$>"$>

The ColumnProperties result set technically has a row for each column in the table, while in RowData, there is only one row. Data entered into this result set is of the following form:

<$RowData.%COLUMN_ID% = "%IDOCSCRIPT%"$>

Each column in the RowData result set refers to an actual column that will appear in the final table. Each column in this result set has a corresponding "ID" in the ColumnProperties result set declared earlier. An Idoc Script expression is assigned to each cell in this result set. It will then be evaluated during the display of each row as it is written to the HTML document.

Next the resource include must be created to display each row in the table.

<$include create_slim_table_row_include$>

Calling this resource include creates the slim_table_row_include resource include. Instead of parsing and evaluating the RowData result set for each row in the table, it is done once.

Use the following steps to set multiple row includes (for example, for a single table which displays different rows for different types of items):

  1. Delete and re-create the RowData result set.

  2. Set rowIncludeName to the name of the resource include to create.

  3. Include create_slim_table_row_include again.

Example 8-4 shows code that displays the table.

Example 8-4 Code to Display a Table

<$include slim_table_header$>
<$loop SearchResults$>
  <$include slim_table_row_include$>
<$include slim_table_footer$>

To make the table look like the table on the search results page, set the following value in the script:

<$UseRowHighlighting = true$>

One special customization with the Headline View table allows any component writer or administrator to easily override how the data in any column is presented. Example 8-5 shows a custom include that can be declared from within a component.

Example 8-5 Custom Include Declaration in a Component

<@dynamichtml slim_table_title@>

If dDocTitle:slimTableCellInclude=slim_table_title is added to the IntradocDir/config/config.cfg file or set from within a script, all Headline View tables with a column ID of dDocTitle are displayed using the defined custom include. This overrides the RowData for these columns.

8.2.2 Thumbnail View Tables

The table for the Thumbnail View is created differently. The ColumnProperties and RowData result sets are not constructed. Instead, the number of columns are set, and an Idoc Script include name is used to paint each cell, as Example 8-6 shows. This is less easy to customize and less data-driven than the other methods, but this type of table is also much less structured.

Example 8-6 Code for Cells in a Thumbnail View Table

<$numDamColumns = 4$>
<$damCellIncludeName = "my_sample_dam_cell"$>
<$include dam_table_header$>
<$loop SearchResults$>
  <$include dam_table_item$>
<$include dam_table_footer$>

8.3 Customizing Actions Menus

The first step in customization is to add the Actions menu icon to the Actions column. Example 8-7 incorporates an action menu into each row of the Headline View sample table used previously.

Example 8-7 Code to Incorporate Actions Menus in Rows

<$RowData.actions = "<$include action_popup_image$>" &
  " <$include doc_info_action_image$>"$>

This inserts the action image into the appropriate column. However, clicking it does nothing because the actual menu is not written to the HTML page. Example 8-8 shows code that creates the data to be used to construct this menu.

Example 8-8 Data to Construct an Actions Menu

<$exec rsCreateResultSet("PopupProps",

<$exec rsAppendNewRow("PopupProps")$>
<$PopupProps.label = lc("wwCheckOut")$>
<$PopupProps.function = "<$HttpCgiPath$>?IdcService=CHECKOUT" &
  "&dID=<$dID$>&dDocName=<$url(dDocName)$>" & 
<$PopupProps.class = "document"$>
<$PopupProps.id = "checkout"$>

<$exec rsAppendNewRow("PopupProps")$>
<$PopupProps.label = lc("wwGetNativeFile")$>
<$PopupProps.function = "<$HttpCgiPath$>?IdcService=GET_FILE" &
  "&dID=<$dID$>&dDocName=<$url(dDocName)$>" & 
<$PopupProps.ifClause = "showNativeFileLink"$>
<$PopupProps.class = "document"$>
<$PopupProps.id = "getNativeFile"$>

<$exec rsAppendNewRow("PopupProps")$>
<$PopupProps.label = lc("wwTest")$>
<$PopupProps.function = "javascript:alert('<$js(dDocName)$>');"$>
<$PopupProps.ifClause = "showTestAction"$>
<$PopupProps.class = "debug"$>
<$PopupProps.id = "alertDocName"$>

This code creates a result set called PopupProps, where each row corresponds to an action in the menu being created. Each action can have several attributes associated with it. Some of the more common attributes follow:

  • label: A string displayed as the label for the action.

  • function: The URL or JavaScript method to be associated with this action.

  • class: A classification for this action. It can be something as simple as "search", "document", "workflow", or even the name of your component. It places the action into a group so that it can be quickly enabled or disabled with the rest of the actions within that same group.

  • id: Another method of classification, much more specific than "class". This method should be unique to the application, and you can use it to hide certain actions from appearing within the menus.

  • ifClause: An optional attribute evaluated every time that action is about to be written to the HTML document. If the clause evaluates to FALSE, the action is not displayed.

  • isDisabled: If set to 1, the action is never displayed.

  • linkTarget: Used to make this link open a page in a different window. This attribute points to any anchor tag target.

After the data is set, it can be used to create an Idoc Script resource that writes this Actions menu, as Example 8-9 shows.

Example 8-9 Resource to Write an Actions Menu

<$include create_action_popup_container_include$>

This resource works like create_slim_table_row_include. It constructs a new Idoc Script resource called action_popup_container_include. To rename it, you could set <$actionPopupContainerIncludeName = new_include_name$> in the script.

Example 8-10 shows code to have this include called for each row of the Headline View table.

Example 8-10 Code to Call an Include for Each Row of a Table

<$exec rsCreateResultSet("PopupData", "actions")$>
<$exec rsAppendNewRow("PopupData")$>
<$PopupData.actions="<$include action_popup_container_include$>"$>

This code creates a PopupData result set similar to the RowData result set. It is structured in the same way, and is used as a location to print the action menu containers which are hidden until a user clicks on the action image.

The table created now has Acitons menus, similar to those normally seen on the search results page whenever the appropriate image is clicked.

Editing these actions is done by adding and deleting rows from the PopupProps result set or editing rows that already exist. In addition to this type of customization, actions can be hidden by setting the disabledActionPopupClasses and disabledActionPopupIds variables. These can be set in the config/config.cfg file or in the Idoc Script itself, as Example 8-11 shows.

Example 8-11 Code to Hide Items in an Actions Menu

<$disabledActionPopupClasses = "workflow,folders"$>
<$disabledActionPopupIds = "getNativeFile,alertDocName"$>

Setting these variables causes any actions whose class is either workflow or folders, or whose ID is getNativeFile or alertDocName, to always be hidden. Using these variables enable Oracle WebCenter Content Server administrators and component writers to hide specific actions either globally or for specific pages.

Component writers also can override a number of Idoc Script resource includes to modify functionality in this area on either a global or targeted scale. The following includes are just a few of the available resource includes:

  • custom_add_to_action_popup_data

  • custom_modify_action_popup_data

  • classic_table_row_pre_display

  • slim_table_row_pre_display

  • custom_row_pre_display