Utility plug-ins

Utility plug-ins give us more control over how markup is inserted into the web content. For example, we can use comparisons to conditionally determine when to insert markup or we can add comments that can be viewed only by content authors.

Comment plug-in

Use the Comment plug-in to insert comments you want only content authors to view. All text written between the plug-in start and end tags is treated as comment. This text is not processed, but is omitted when the web content is rendered. Example:

[Plugin:Comment] This is a comment [/Plugin:Comment]

Equals plug-in

Use the Equals plug-in to insert markup into the web content only if the values of two text attributes match. The plug-in provides the two attributes text1 and text2. All markup between the start and end tags is rendered as part of your web content only if the values of these two attributes match.

The following sample renders the markup between the plug-in start and end tags only if the rendered content is currently in a workflow stage named Review.

[Plugin:Equals text1="Review" text2="[Property type='content' 
               context='current' field='currentstage']"] 
Document in review.
[/Plugin:Equals]

NotEquals plug-in

Use the NotEquals plug-in to insert markup into the web content only if the values of two text attributes do not match. The plug-in provides the two attributes text1 and text2. All markup between the start and end tags is rendered with the web content only if the values of these two attributes do not match.

The following sample renders the markup between the start and end tags only if thetype element of the rendered content does not have the value Internal:

[Plugin:NotEquals text1="Internal" text2="[Element type='content' 
                  context='current' key='type']"] 
Public document
[/Plugin:NotEquals]

Locale plug-in

Use the Locale plug-in to add locale information to the web content or to insert markup into the web content depending on the current locale. This plug-in determines the preferred supported locale in the current context.

The Locale plug-in uses the following attributes:

acceptLanguage

Enables you to define one or more preferred locales that can be selected by the portal in a specific context. Attribute values must conform to the syntax specification of the Accept-Language header field of the HTTP/1.1 protocol. For details on this header field, see the Accept-Language section of the RFC2616 specification.

If the acceptLanguage attribute is not defined, the portal considers all available supported locales as equally acceptable when determining the preferred supported locale for the selected context.

pattern

Enables you to define the output format for the locale that is printed by the Locale plug-in.

Attribute values specify a pattern that can include the following placeholders:

• {language}: Placeholder for the lowercase, two-letter language code of a locale as defined by the ISO-639 standard.

• {country}: Placeholder for the uppercase, two-letter country code of a locale as defined by the ISO-3166 standard.

• {variant}: Placeholder for the vendor-specific or browser-specific variant of a locale.

If the pattern attribute is not defined, the following pattern is used: {language}-{country}-{variant}.

printLocale

Enables you to define whether the preferred supported locale that is determined by the Locale plug-in is inserted into the web content. The attribute can have the following values:

• true: The preferred supported locale is written to the markup of the page.

• false: The preferred supported locale is not written to the markup of the page.

By combining this attribute with the acceptLanguage attribute, users can define content to be rendered only in the following circumstances:

• If a specific locale is applicable in the current context

• If one locale of a specific set of locales is applicable in the current context

Although the body of the Plugin tag is printed if an acceptable locale is supported, the preferred supported locale is not displayed when this attribute is set to false.

If the printLocale attribute is not defined, a value of true is used.

If the Locale plug-in specifies body content, the markup between the start and end tags is rendered only if the preferred supported locale is determined. If no supported locale applies in the current context, the Locale plug-in does not insert markup into content.

Examples:

• When adding the Locale plug-in to the web content without defining additional attributes, the preferred supported locale in the current context is inserted into the web content. The default format of {language}-{country}-{variant} is used (for example, es-ES-WIN):

  [Plugin:Locale]
  

• The pattern attribute enables you to define the output format of the preferred supported locale. The following sample renders the locale using a custom format and omits the variant element (for example, es_ES):

  [Plugin:Locale pattern="{language}_{country}"]
  

• The following sample renders the language code of the preferred supported locale in the current context (for example, da). Only languages of Nordic countries are accepted as a result. If none of the specified locales is supported in the current context, nothing is printed to the web content. For example, if the user configures the web browser or the portal user profile to use only the English language (en), the Locale plug-in does not return any locale.

  [Plugin:Locale acceptLanguage="da,fo;q=0.8,fi;q=0.6,is;q=0.4,no;q=0.2,sv;q=0.2" pattern="{language}"]
  

• We can prevent the preferred supported locale from being rendered with the printLocale attribute. This sample inserts the body of the Plugin tag into the web content only if the preferred supported locale matches one of the specified Nordic languages. The determined locale is not added to the web content.

  [Plugin:Locale acceptLanguage="da,fo;q=0.8,fi;q=0.6,is;q=0.4,no;q=0.2,sv;q=0.2" printLocale="false"]
       <div>This markup is displayed only if the current context supports a locale 
       that represents one of the specified Nordic languages.</div>
   [/Plugin:Locale]
  

• We can also combine the Locale plug-in with other plug-ins. The following example shows how we can use the Matches plug-in with the Locale plug-in. The markup in the body of the Matches plug-in is rendered in the content only if the preferred supported locale represents a Spanish language.

  Plugin:Matches pattern="es(.*)" text="[Plugin:Locale]"] 
      <div>This markup appears only if the preferred supported locale in the 
      current context represents a Spanish language. Neither the country code 
      nor the variant are important as long as the language code of the 
      locale is "es".</div>
  [/Plugin:Matches]
  

Matches plug-in

Use the Matches plug-in to conditionally insert markup into the web content by evaluating a regular expression against a passed text value. The plug-in provides two attributes: text and pattern. All markup between the plug-in start and end tags is rendered only if the value of the text attribute matches the regular expression in the pattern attribute.

We can also have negative pattern matching. In this case, the markup of the body of the plug-in tag is rendered only if the text does not match the regular expression. To use negative pattern matching, set the negative-match attribute to true.

The regular expression dialect used by the plug-in is defined by the Java language class java.util.regex.Pattern.

Examples:

• The following sample renders the markup between the start and end tags only if the rendered content is currently in a workflow stage whose name contains the word Review.

  [Plugin:Matches text="[Property type='content' context='current' 
                  field='currentstage']" pattern=".*Review.*"] 
  Document in review
  [/Plugin:Matches]
  

  To have the case of the character for the matching ignored, prefix the control sequence (?i) to the regular expression. The following sample also matches workflow stage names such as review:

  [Plugin:Matches text="[Property type='content' context='current' 
                  field='currentstage']" pattern="(?i).*review.*"] 
  Document in review
  [/Plugin:Matches]
  

• The following sample renders the markup between the start and end tags only if the rendered content is currently in a workflow stage whose name does not contain the word Review:

  [Plugin:Matches text="[Property type='content' context='current' 
       field='currentstage']" negative-match="true" pattern=".*Review.*"] 
  Document not in review
  [/Plugin:Matches]
  

• We can also use capture groups for regular expressions. To access the value of a group, use the MatchedGroup plug-in. We can use this plug-in only between the start and end tags of the Matches plug-in. It provides the attribute group to retrieve a capture group by its index. For example, to access the first word in a list of comma-separated words, use the plug-in as follows:

  [Plugin:Matches pattern="(.*)(,)(.*)" text="key1,key2"] 
  First key is: [Plugin:MatchedGroup group="1"]
  [/Plugin:Matches]
  

ThemeCapability plug-in

Use the ThemeCapability plug-in to retrieve the list of available theme capabilities of the page that is currently rendered. These capabilities are described in Basic artifacts and their relation. The plug-in returns the capabilities, in no specific order, as a string of name-value pairs that are separated by commas.

Here is an example of a string that is returned when the [Plugin:ThemeCapability] tag is rendered on a page that uses the full profile theme:

{analytics_aggregator=8.0, portal.livetext.hcard=8.0, widget_container=2.1, active_site_analytics=8.0, 
portal.livetext.action=8.0, open_ajax_hub=2.0, dojo=1.7, mashups.enabler=3.0.0.1, content_mapping.picker=8.0, 
cp_tagging_rating=8.0, oneUI=3.0.1, portal.livetext.adr=8.0, mashups.builder=3.0.0.1, 
federated_documents.picker=8.0, portal.livetext.c2a=8.0}

We can use the Matches plug-in to check for the availability of specific theme capabilities and then dynamically add markup to the rendered content. The following sample adds a string (... Dojo is available ...) to the markup only if the dojo theme capability is available in the current rendering context:

[Plugin:Matches text="[Plugin:ThemeCapability]" pattern=".*dojo=.*"] 
... Dojo is available ...
[/Plugin:Matches]

ToolbarState plug-in

Use the ToolbarState plug-in to retrieve the state of the site toolbar that is provided with the Portal 8.0 theme. The plug-in renders the following strings to indicate the current state of the toolbar:

open

Indicates that the toolbar is expanded as a result of the page being in edit mode.

closed

Indicates that the toolbar is collapsed as a result of the page being in view mode.

unknown

Indicates that no page mode is selected. This state can occur, for example, directly after log-in.

Example:

[Plugin:ToolbarState]

We can use the Equals plug-in to check for the current state of the toolbar and then dynamically add markup to the rendered content. The following sample adds a component (web content templates/edit) to the markup only if the site toolbar is currently expanded:

[Plugin:Equals text1="open" text2="[Plugin:ToolbarState]"]
    [Component name="web content templates/edit"]
[/Plugin:Equals]

Parent: Render plug-ins provided with Web Content Manager

Related:

Basic artifacts and their relation

Related:

Accept-Language header in RFC2616 specification