2 Understanding the Oracle WebCenter WSRP Producer for .NET Configuration File

This chapter describes contents of the Oracle WebCenter WSRP Producer for .NET configuration file, wsrp-producer.xml.

The set up of a Web Part or .NET application as a WSRP portlet is not complete until the wsrp-producer.xml configuration file is filled out properly. Understanding this file is critical.

Open the wsrp-producer.xml file installed in <installdir>\wsrpdefault for reference.

Section 2.1, "Portlet Nodes"
Section 2.2, "Portlet Content Transformation Rulesets"

2.1 Portlet Nodes

Each Web Part or .NET web application you wish to expose as a portlet must have its own <portlet> node. Portlet nodes can include the following elements:

Portlet handle: The <handle> must be a string that uniquely identifies the portlet. Alphanumeric characters are suggested for this portlet property.
Supported locale: The <supported-locale> must be a comma-delimited list of supported locales. The typical format is [2 char language code] "-" [2 char country code] (for example, en-US). This information is sent to the WSRP consumer portal during registration. These values also drive the localization for core properties of the portlet such as title and description.
Localized portlet information: The <description>, <display-name>, <title>, and <short-title> properties are localized according to the "lang" attribute value specified. Each value is returned as a LocalizedString for the corresponding WSRP values of description, displayName, title, and shortTitle. See the PortletDescription type in the WSRP specification for more details on these properties.

Supported modes: The <supports> element includes several sub-elements:

Portlet modes: The <portlet-modes> element defines URLs (typically a relative path) for relevant WSRP portlet modes. The Oracle WebCenter WSRP Producer for .NET handles portlet modes as follows:

Table 2-1 Portlet Modes

Portlet mode	Action
wsrp:view	Render the portlet.
wsrp:edit	Render the portlet editor.
wsrp:help	Render a web page for help.
wsrp:preview	This mode is treated the same as wsrp:view.
urn:javax:portlet:mode:custom:edit_defaults	This WSRP custom mode is for Oracle WebCenter Portal customization.

Any mode not on this list will be treated like wsrp:view mode. See the sections that follow for examples of each portlet mode.

MIME type: The <mime-type> element defines a MIME type supported by the portlet. If all MIME types are supported, pass in "*". See the MarkupType type in the WSRP specification for more information on this setting.

User profile information: The <user-profile> element allows you to define user profile information in <profile-item> elements for use in portlets. For more information on using this element, see Section 5.8, "Adding User Profile Data."
Portlet content transformation: The <RuleSetRef> section allows you to associate existing transformation rules (defined outside the portlet node) with a portlet. Use the ID defined in the associated <RuleSet> element. Multiple rulesets can be referenced by placing the IDs in the appropriate order in a comma-delimited string. To add your own transformation rules, add a <RewriterConfig> element and follow the same structure defined for the <Rules> element. Existing rules can be combined with custom rules as shown in the example below:
```
<RuleSetRef>Default</RuleSetRef>
<RewriterConfig>
  <Rules>
    <RewriterRule>
      <LookFor>test.csv</LookFor>
      <ChangeTo>download.csv</ChangeTo>
      <ChangeToAbsolute>false</ChangeToAbsolute>
      <ApplyTo>*</ApplyTo>
      <MakeResource>false</MakeResource>
    </RewriterRule>
  </Rules>
</RewriterConfig >
```
Note:
If custom rules are combined with existing rulesets, custom rules will be applied in order of listing after all of the referenced rulesets.

In the above example, the portlet will apply all rules associated with the "Default" rule set and then replace any occurrences of "test.csv" with "download.csv".

For details on rulesets, see the next section.

2.2 Portlet Content Transformation Rulesets

The Oracle WebCenter WSRP Producer for .NET utilizes regular expressions to transform relative URLs to absolute URLs and to URLs proxied through the WSRP consumer if necessary. Specific transformation rules are defined in the wsrp-producer.xml file in <RuleSet> elements and referenced in each portlet. Rulesets are a way of clustering a group of markup transformation rules.

By default, there is a single default ruleset that ensures that hrefs are transformed and proxied as WSRP resources, but "src" URL references (images and javascript) are transformed but not proxied. To use different transformation settings, create a new ruleset as described below. For an example of using rulesets in a portlet, see Section 5.5, "Using Markup Transformation."

Note:

It is strongly recommended that you not modify the default ruleset.

2.2.1 Creating Custom Rules

As noted in the previous section, custom rules can be defined within the portlet node or outside the portlet node in a <RuleSet> element. Rulesets can be very useful if you have a set of portlets that should use the same rules. Instead of copying the URL transformation rules for each portlet, you can create a single ruleset and reference the ID in each portlet. The syntax rules for the <RewriterConfig> element are the same for both locations. (If the rule is defined within an individual portlet node, the <RuleSet> element is omitted.)

The <RewriterConfig> element contains a <Rules> element that contains <RewriterRule> elements, which define transformation rules using the elements in the following table.

Table 2-2 Transformation Rule Elements

Element	Value/Description
`<LookFor>`	Required. Defines the URL to search for using text and/or regular expressions. For example, `<LookFor>(activeSrc\":\")([^\"]+)</LookFor>` indicates that the transformer should look for URLs like "activeSrc":"./test/foo/bar.js" or "activeSrc":"test2/bas.html" for replacement. `<LookFor>` must be the first element in the `<RewriterRule>` element.
`<ChangeToAbsolute>`	Required. If set to true, transforms any URL identified with the `<LookFor>` element into an absolute URL. (Typically, the transformation you wish to perform on an URL is to make it an absolute URL since a relative URL does not make sense when proxied through a WSRP consumer.)
`<MakeResource>`	Required. If set to true, ensures that the URL is proxied by the WSRP consumer. While this is important for resources that you wish to protect, applying this option liberally can have significant performance ramifications since the WSRP consumer must rewrite the URL and browser caching cannot be relied upon. Use the `<ApplyTo>` to ensure that only those URLs you wish to proxy are included.
`<ApplyTo>`	Limits the URLs that are transformed and proxied using a comma-delimited list of keywords. (All URLs returned by the `<LookFor>` element will be transformed to absolute URLs if `<ChangeToAbsolute>` is included in the rule.)
`<ChangeTo>`	Changes the text returned by the `<LookFor>` element to the provided text. (This is not used for URL transformation, but allows you to use the `<RewriterRule>` element to change any text within the portlet, and can include regular expressions.) For example, the entry below redirects traffic from myhost to myhost.mycompany.com instead: <RewriterRule> <LookFor>myhost[\:][0-9] </LookFor> <ChangeTo>myhost.mycompany.com</ChangeTo> </RewriterRule>