Understanding Web Features

Web Features is a generic term  for a variety of preferences, privileges, settings, etc. that can be used to control the availability of functionality in MicroStrategy Web applications. Some general examples of Web Features include:

• Current context of the application

  Specific example:

  • Whether the browser supports DHTML or not
  • Whether a certain preference is on or off

• Current functionality available to the user

  Specific example:

  • Whether the user can access the history list, based on the user's privileges
  • Whether the user can view a particular report, based on the user's privileges

• Specific setting for a specific object operation

  • Specific example: Whether a report is in outline mode
  • Whether grid headers are locked on a report

The purpose of Web Features is to allow you to create conditional functionality, by basing the availability of functionality on whether a specific feature (or set of features) is true or false. In all cases, a Web Feature is either true or false.

Some examples of conditional functionality that can be associated with a Web Feature include:

• whether a shortcut is displayed on a toolbar, is active, or is selected by default 

• whether a menu entry is displayed, is active, or is selected by default (checked) 

• whether a system-picker is displayed, is active, or is selected by default (checked) 

• whether a shortcut is part of a page template 

• whether a user has access to a page 

• whether a bean is instantiated in a request 

• whether a Web component is refreshed after an iFrame request 

• whether a property is assigned to a bean 

• whether a certain block of javascript is used in a page 

• what content is included in a JSP or ASP.NET file 

• what content is included in an XML layout definition file 

In simple terms, Web Features let you create a relationship between a feature, such as the user group to which a user belongs, and a functionality, such as displaying a particular icon on the toolbar. When the application encounters the functionality, it checks to see whether the associated feature is true (or false, depending on how the condition is defined). If so, it performs the action defined by the functionality; if not, it skips the action and continues. The breadth and depth of this capability allows you to make extremely granular customizations.

There are four attributes that can be used to create feature-related conditionality. Each attribute controls a specific aspect of the conditional functionality, and each can be used with specific XML nodes.

• feature-id

  Controls whether the functionality is available  (for example, whether a shortcut or menu item is rendered)

• enable-feature-id

  Controls whether the functionality is enabled  (for example, whether a shortcut or menu item is active)

  : The name of this attribute may be confusing. It is the functionality, not the feature, that is enabled— based on whether the feature resolves as 'true' or 'false'.

• check-feature-id

  Controls whether the functionality is selected or not   (for example, whether a menu item is checked by default)

  The name of this attribute may be confusing. It is the functionality, not the feature, that is checked (selected)— based on whether the feature resolves as 'true' or 'false'.

• feature-target

  Controls whether the target attribute of a shortcut should cause a separate page to display

To create conditional functionality, you simply add one of the attributes listed above to the XML node for the functionality that is conditional and set the value of the attribute to a specific feature or set of features. If you use a set of  features, you must separate the individual features with semi-colons. If you may want the conditional functionality to be triggered when a specific feature is false, rather than true, you prefix the feature with “!”. When you include multiple features, you can mix features that must be true with those that must be false.

The example below illustrates the use of multiple features, including two that must be true and one that must be false. Assuming that the feature-id attribute for a <page> node has the following value:

feature-id="a;!b;

then the page is displayed if and only if:

• feature a is true 

• feature b is false 

• feature c is true

MicroStrategy Web provides an extensive set of default features that can be used to create conditional functionality, but you can also create your own custom Web features that do the same thing. To learn how to create your own custom Web Feature, refer to Using a Custom Web Feature to Provide Special Functionality for a User Group.

The list of out-of-the-box features that can be used as values for feature-related attributes can be found in EnumWebFeatures and EnumAppWebFeatures. To view the contents of these classes, click the API Reference link. In the bottom left pane of the topic window, click either EnumAppWebFeatures or EnumWebFeatures to display the list of features in the right-hand pane.

The following section gives a more technical explanation of how Web features are handled by the application. This is followed by the XML Nodes section which provides detailed instructions on how to use each attribute in the XML nodes where you can set feature-related conditionality and an explanation of exactly what it means when functionality is available, enabled or selected.

How WebFeatures Work

When you add a feature-related attribute to an XML node associated with a certain functionality and set it to a specific feature (or set of features), the application checks to see whether the feature (or set of features) is true or false and— based on the result and the particular attribute used— makes the associated functionality available, enables it, or selects it.

For example, if you want to display a certain menu item only if a specific feature is true, you would add a feature-id attribute to the <menus><shortcut-list-set><shortcut-list><shortcut> node for that menu item and set it equal to the specific feature. If, on the other hand, you want to place a checkmark by a certain menu item only if a specific feature is false, you would add a check-feature-id attribute to the <menus><shortcut-list-set><shortcut-list><shortcut> node for that menu item and set it equal to the specific feature, prefixing the feature value with '!'.

Every bean has a WebFeatures class associated with it, accessible through the getFeaturesManager() method. This is a separate class that includes a reference to the WebBean so it can query properties on it. This is where features related to a specific WebBean are resolved. The application uses the WebFeatures interface to determine whether a feature is enabled. It calls the isFeatureAvailable method for the corresponding WebComponent (base-bean). This method uses the following hierarchical checking scheme to determine whether a feature is enabled:

1. With GlobalFeatures: This check resolves features that are associated with the user (such as privileges and preferences) or with the application (such as whether the browser supports HTML or not) and are not bean-specific.

2. With the FeatureManager of the parent: This check resolves features that are bean-specific, when the bean is a child of another WebComponent. The application first checks to see if the parent enables the corresponding feature.

3. With the FeatureManager of the bean: This check resolves features that are bean-specific, when the bean is not a child of another WebComponent.  

Unknown features are enabled by default. If a new/unknown feature is passed to GlobalFeatures or to a FeatureManager, the isFeatureAvailable method of these classes returns true. This enables the hierarchical checking scheme to function properly. Both GlobalFeatures and a bean's FeatureManager check for a subset of the features defined in EnumWebFeatures and EnumAppWebFeatures.

There is no single object or class that uses the WebFeatures interface exclusively. It is used as required, depending on where a feature-related attribute is defined. For example, if the attribute is defined in a <page> node, the servlet verifies whether the feature is enabled. If the attribute is defined in a <shortcut> node, the Shortcut class performs the check. If it is defined in a JSP or ASP.NET file, it is the custom tag.

XML Nodes Where You Can Use Feature-related Attributes

The following section lists the nodes where you can set feature-related checks and provides a detailed explanation of the individual feature-related attributes available for each node. These nodes can be found in certain configuration files (primarily PageConfig.xml), JSP/ASP.NET files, and XML layout definition files.

Page Configuration File and other Configuration Files

The following nodes in configuration files use <shortcut-list> and <shortcut> tags. You can use feature-related attributes in either of these tags to make the associated functionality conditional.

• <menus>
• <system-pickers>
• <templates>
• <toolbars>

The <shortcut-list> and <shortcut> nodes can contain the following feature-related attributes:

• <shortcut-list>

• feature-id

  Controls whether the shortcut list is available or not. When the IsFeatureAvailable method returns false, none of the elements of the shortcut list are rendered.

  Using the following sample code, the toolbar displays only in DHTML mode:

  <toolbars>

    <shortcut-list name="default"

      <shortcut name="copy"

      ...

      <shortcut name="rename"

    </shortcut-list>

  </toolbars>

• enable-feature-id

  Available only when the shortcut list is used as one of the main entries in a menu. Controls whether the menu is enabled or not. When the IsFeatureAvailable method returns false (disabled/not enabled), all of the elements of the shortcut list are rendered, but they are not enabled.   

  Using the following sample code, the menu is displayed regardless of the mode, but the menu options respond to mouse actions only in DHTML mode.

  <menus>

    <shortcut-list name="default"

      <shortcut name="copy"

      ...

      <shortcut name="rename"

    </shortcut-list>

  </menus>

• <shortcut>

  • feature-id

    Controls whether the shortcut is available or not. When the IsFeatureAvailable method returns false (the feature is disabled), the shortcut is not rendered at all.

  • enable-feature-id

    Controls whether the shortcut is enabled or not. When the IsFeatureAvailable method returns false (the feature is disabled),  the corresponding shortcut does not respond to the mouse (e.g. no link is generated for the item). Normally, a special CSS class is assigned to the shortcut to denote this condition.

  • check-feature-id

    Controls whether the shortcut is selected or not. Depending on the context in which the shortcut is used, the application determines how this is accomplished. Normally, a special CSS class is assigned to the shortcut to denote this condition, and, in the case of menu, a checkbox image is displayed to the left of the item.

  • feature-target (available only in menus and toolbars)

    Controls whether the target attribute of a shortcut should cause a separate page to display for the URL link of the shortcut. When the IsFeatureAvailable method returns true (the feature is enabled), the target attribute is used to build the corresponding anchor and a separate page opens. When the IsFeatureAvailable method returns false, the target attribute is ignored when building the corresponding anchor and the same page is used to display the shortcut.

Using the following sample code, the lock menu option is displayed only when both the lock-grid-headers and dhtml features are available; responds to mouse-clicks only when the check-graph-mode feature is false; and is marked as selected (i.e., is checked) only when the check-lock-row-headers feature is true.

In addition to <shortcut-list> and <shortcut>, several other nodes in the pageConfig.xml file have a feature-id attribute. These are:

<event>

• feature-id

  Controls whether the event is associated with the shortcut. When the IsFeatureAvailable method returns false (when the feature is disabled), the event is not associated with the shortcut and the next event on the list is tried. The application uses the first event whose feature is enabled.

<folder-link>

• feature-id

  Controls whether a folder link is displayed in an object-browser. When the IsFeatureAvailable method returns false (the feature is disabled), the shortcut to the associated system folder is not rendered in the browser.

<javascript>

• feature-id

  Allows you to selectively include javascript only if certain conditions are met. When the IsFeatureAvailable method returns false (when the feature is disabled), the corresponding code is not included in the resulting HTML. For example, that code that initializes the lock-headers is included only if lock-headers is on.

<page>

• feature-id

  Controls whether a user has access to a page. When the IsFeatureAvailable method returns false (when the feature is disabled), the user does not see links to the page.  If the user attempts to access the page directly using Java code, the following error message is displayed:

  Access denied The following privilege is required to access the resource you requested: XXX Please contact the MicroStrategy Server Administrator to verify the required privilege is granted.

  In general, this is used to prevent end-users from accessing a page directly through the URL if they do not have the correct privileges.

<property>

• feature-id

  Controls whether a property is assigned to a bean. When the IsFeatureAvailable method returns false (when the feature is disabled), the property is not assigned to the corresponding bean. This is used to assign a property to a bean only if certain conditions are met. For example, the sample code below causes editors in the report page to be displayed as modal only if dhtml is on.

  <property name="

<web-bean>

• feature-id

  Controls whether the bean is instantiated in this request. When theIsFeatureAvailablemethod returns false (when the feature is disabled), the bean is not

<web-component>

• feature-id

  Controls whether the Web component is refreshed after an iFrame request. When theIsFeatureAvailablemethod returns false (when the feature is disabled), the Web component is not refreshed, even if the underlying bean has changed. This is used to ensure that only the necessary elements in the graphical interface are refreshed after an iFrame request.

JSP/ASP.NET Files

The <web:ifFeature tag allows you to dynamically control the content of a JSP or ASP.NET file based on the availability of the feature referenced by the name attribute in the tag.

• <web:ifFeature

  The <web:ifFeature tag checks to see if the feature is available. If so, it includes the content within the <then> tag in the JSP file; if not, it includes the content within the <else> tag. For example:

  <web:ifFeature

    <script>alert('Javascript is enabled!')/script

  </web:then><web:else>

    <b>Javascript is not supported in this browser!</b>

  </web:else></web:ifFeature

  When only the name attribute is specified, the feature is resolved by default against the PageComponent (i.e. the. To check for features associated with a specific bean, you must specify two additional attributes -type(always equal to "bean") andvalue(the name of the bean). For example:

  <web:ifFeature

    This bean can be reprompted!

  </web:then></web:ifFeature

XML Layout Definition Files

The <mstrlayout:if tag allows you to dynamically control the content of an XML layout definition file based on the availability of a feature passed as an argument to the isFeatureAvailable method.

<mstrlayout:if name="isFeatureAvailable"

Similar to JSP files, the <mstrlayout:if tag allows you to define the content of  an XML layout definition file. In this case, the feature to be used as an argument is specified by the value attribute of the <mstrlayout:argument child node. For example:

See also

• Web Feature Examples 

• User Privileges and Web Features 

• Using a Custom Web Feature to Provide Special Functionality for a User Group