Customizing Primary Views for Site Preferences

This is a developer-level activity.

Site preferences are used to configure the appearance, behavior, and connectivity of the FileNet P8 Platform client applications, such as altering the appearance of document lists, choosing which properties to display for various views, and restricting access to administrative applications and security information. Site preferences are configured in Workplace by members of the Application Engine Administrators role using the Site Preferences Tool. This tool presents the site preferences using views which provide access to groups of preferences, such as Object Store settings, Bootstrap settings, or Access Role settings. In addition, the tool also supports organizing multiple views into one or more labeled groups, such as Workplace Preferences (labeled as "Information" prior to the FileNet P8 4.0.0 release), or some other custom grouping.

The following is a screenshot of the Site Preferences Tool showing the primary view for the Bootstrap settings. In this picture, Workplace Preferences, Other Preferences, and WebDAV Preferences are group labels, while the other navigable items, such as General, Primary Views, and My Workplace are primary views for site preference settings.

Workplace Site Preferences Primary Views

NOTE  Do not confuse the configuration of "primary views for site preferences" with "site preferences for Primary Views." The latter refers to the ability of an administrator to modify the site preference settings associated with the Primary Views offered by Workplace. As demonstrated in the screenshot above, Primary Views is a view of site preference settings corresponding to the configuration of available UI views within Workplace. For more information, see Plugging in a Primary View.

In FileNet P8 4.0, the ability to configure the primary views for site preference settings is made available through the use of the SitePreferencesPrimaryViews.xml descriptor file which is located in the <AE_install_path>/Workplace/WEB-INF folder. By modifying the objects in this file, an administrator can specify which settings appear in a particular view, provide a name for a view, organize views into labeled groups, and provide translated labels for different locales. In addition, using the Web Application Toolkit, developers can create custom views which may also be specified in this XML file.

This topic shows you how to create and add a custom primary view of site preference settings for display in Workplace. Starting with an overview of creating a custom primary view, the topic explains how to register the view in the Workplace site preferences primary views descriptor file.

Creating a Custom Primary View for Site Preference Settings

Creating a primary view for Workplace site preference settings requires an understanding of the Web Application Toolkit framework and base modules on which the Workplace application is built. This section outlines the general steps you would take to create a new primary view.

NOTE  Configuration settings for views defined outside of FileNet applications are not automatically included in the descriptor file. If you have implemented pre-defined views, you must manually add them to SitePreferencesPrimaryViews.xml. After modifying the file, redeploy Workplace.

To create a custom primary view for site preference settings:

  1. To implement a custom primary view for site preference settings, you must write a java class that extends the WcmUiModule class, which optionally implements the WcmViewPanelInterface interface. Your class implementation must be located in the Workplace application class search path. When a primary view has been defined, but the implementation class for the view cannot be found, Workplace displays a message in place of the view. Both WcmUiModule and WcmViewPanelInterface are part of the Web Application Toolkit and are located in <AE_install_path>/Workplace/WEB-INF/lib/p8toolkit.jar.

    public static class MyView extends WcmUiModule implements WcmViewPanelInterface
    {
      public void render() throws Exception {
        ...
      }
      public boolean isApplyButtonRequired() throws Exception {
        return false;
      }
      public boolean isModified() throws Exception {
        return false;
      }
      public void panelFinish(HttpServletRequest request,
                              HttpServletResponse response) throws Exception {
        . . .
      }
      public void panelSave(HttpServletRequest request,
                            HttpServletResponse response) throws Exception {
        . . .
      }
    }
  2. If you want to leverage the pencil icon that appears to the left of a modified view label, the view class has to implement the isModified() method of WcmViewPanelInterface. When this method returns true, the container will display the pencil icon.
  3. In the SitePreferencesPrimaryViews.xml descriptor file, add the appropriate XML elements for a custom primary view as described in Configuration Settings. The WcmWorkplaceController class will load this file when the Workplace application runs for the first time. If you modify SitePreferencesPrimaryViews.xmlafter Application Engine and Workplace installation, you must reload it from Workplace to avoid restarting AE.

Site Preferences Primary Views Descriptor File

SitePreferencesPrimaryViews.xml contains the primary views for pages of site preference settings. The file is located in the <AE_install_path>/Workplace/WEB-INF folder. SitePreferencesPrimaryViews.xml follows the Workplace Preferences XML Schema, Preferences.xsd, located in <AE_install_path>/Workplace/WEB-INF/xml.

NOTES  

The basic structure of the XML document is a list of groupLabel and sitePreferencesPrimaryView objects. Each sitePreferencesPrimaryView object specifies the fully-qualified java class that is responsible for rendering the primary view, the label to apply to the view, and label translations for supported locales.

Views are implicitly grouped by defining each view object after the label for the group object to which it belongs. For example, in the xml fragment below, the object definition for the "Object Stores" view appears after the label definition for the "Workplace Preferences" group, but before the label definition for the "Other Preferences" group. In this manner, the "Object Stores" view is implicitly defined as a member of the "Workplace Preferences" group.

The following Configuration Settings section defines the elements necessary for creating a custom primary view page or group label.

<object key="sitePreferencesPanelConfig" version="4.0">
  <list key="sitePreferencesPrimaryViews">

    <!-- Group Label for "Workplace Preferences" (was "Information") -->
    <object key="groupLabel">

      <label key="label"
        localizationKey="server.SitePreferencesPrimaryViews_xml.WorkplacePreferences"
>

        <!-- Default -->
        <resource>Workplace Preferences</resource>
        <!-- Translations for supported locales -->
        <resource locale="en_US">Workplace Preferences</resource>
        <resource locale="fr_FR">Workplace Préférences</resource>
        <resource locale="de_DE">Workplace Vorzüge</resource>
        ...
      </label>
    </object>

    <!-- Primary Views for the Group "Workplace Preferences" -->
    <!-- General -->
    <object key="sitePreferencesPrimaryView">
      <!-- The label for the view "General" -->
      <label key="label"
        localizationKey="server.SitePreferencesPrimaryViews_xml.general">

        <resource>General</resource>
        <resource locale="en_US">General</resource>
        <resource locale="fr_FR">Général</resource>
        <resource locale="de_DE">Allgemeine Vorzüge</resource>
        ...
      </label>
      <!-- The java class responsible for rendering the view -->
      <setting key="class">
        com.filenet.wcm.apps.server.ui.info.prefs.PrefSiteGeneralInfoPage
      </setting>

    </object>
    <!-- Object Stores -->
    <object key="sitePreferencesPrimaryView">
      <label key="label"
        localizationKey="server.SitePreferencesPrimaryViews_xml.objectStores">
        <resource>Object Stores</resource>
        <resource locale="en_US">Object Stores</resource>
        <resource locale="fr_FR">L'objet Emmagasine</resource>
        <resource locale="de_DE">Objekt Speichert</resource>
        ...
      </label>
      <setting key="class">
        com.filenet.wcm.apps.server.ui.info.prefs.PrefObjectStoresInfoPage
      </setting>
    </object>
    ...

    <!—- Group Label for "Other Preferences" (My Custom Group) -->
    <object key="groupLabel">
      <label key="label"
        localizationKey="server.SitePreferencesPrimaryViews_xml.<custom>Preferences">
        <resource>Other Preferences</resource>
        ...
      </label>
    </object>

    <!-- Primary Views for the Group "Other Preferences" -->
    <!-- Primary Views-->
    <object key="sitePreferencesPrimaryView">
      <label key="label"
        localizationKey="server.SitePreferencesPrimaryViews_xml.primaryViews">
        <resource>Primary Views</resource>
        ...
      </label>
      <setting key="class">
        com.filenet.wcm.apps.server.ui.info.prefs.PrefPrimaryViewsInfoPage
      </setting>
    </object>
    ...

    <!—- Group Label for "WebDAV Preferences" -->
    <object key="groupLabel">
      <label key="label"
        localizationKey="server.SitePreferencesPrimaryViews_xml.webDAVPreferences">
        <resource>WebDAV Preferences</resource>
        ...
      </label>
    </object>

    <!-- Primary Views for the Group "WebDAV Preferences" -->
    <object key="sitePreferencesPrimaryView">
      <label key="label"
        localizationKey="server.SitePreferencesPrimaryViews_xml.general">
        <resource>General</resource>
        ...
      </label>
      <setting key="class">
        com.filenet.wcm.apps.server.ui.info.prefs.PrefWebDAVInfoPage
      </setting>
    </object>

  </list>
</object>

Configuration Settings in SitePreferencesPrimaryViews.xml

The following tables describes the XML elements required to specify a custom primary view or group label for site preference settings in the SitePreferencesPrimaryViews.xml descriptor file. Each setting is identified by its key attribute and is required, unless otherwise specified.

Primary View Configuration

Element Value
<object key="sitePreferencesPrimaryView">
  ...
</object>
Indicates that the object defines a primary view for site preference settings.
<label key="label"
  localizationKey=
    "server.SitePreferencesPrimaryViews_xml.
      general">
  <resource>
    General
  </resource>
  <resource locale="en_US">
    General
  </resource>
  <resource locale="fr_FR">
    Général
  </resource>
  <resource locale="de_DE">
    Allgemeine Vorzüge
  </resource>
  ...
</label>

The string to display in the UI as the name of the primary view, such as "Object Stores" or "My Workplace."

Based on passed in requests from the clients locales, Workplace retrieves UI strings from resource bundles.

The label element identifies the string to display in the UI, and serves as an override to the UI strings set in the property resource bundles. The resource subelements specify the override values. If your Workplace application is supporting clients of various locales, you can have one or more resource subelements with a locale attribute. The value of this attribute should use the standard ISO language and country codes as supported by browsers.

The label element is required with a localizationKey attribute. Workplace uses this attribute to look up the UI string in a resource bundle, should one not be specified in the XML.

If Workplace cannot find the localized string in the XML or resource bundle, it will fall back to the value of the resource element (that does not include a locale attribute). This element is required, while the other locale resource elements are optional.

For a detailed description of the resource lookup logic, see Lookup Precedence for Locale Resources.

<setting key="class">
  com.filenet.wcm.apps.server.ui.info.
    prefs.PrefSiteGeneralInfoPage
</setting>
Specifies the fully-qualified java class that is responsible for rendering the primary view. If the class is not found, a message is displayed in place of the view.

Group Label Configuration

Element Value
<object key="groupLabel">
  ...
</object>
Indicates that the object defines a label for a group of primary views.
<label key="label"
  localizationKey=
    "server.SitePreferencesPrimaryViews_xml.
      WorkplacePreferences">
  <resource>
    Workplace Preferences
  </resource>
  <resource locale="en_US">
    Workplace Preferences
  </resource>
  ...
</label>
The string to display in the UI as the name of the group, such as
"Workplace Preferences" or "WebDAV Preferences." For
a complete description, see the explanation in Primary View Configuration.