Registering theme modules

You can register theme modules and create and use profiles for a particular theme.

About this task

You can define global or theme-specific contributions that contain a theme module, which applies to different scopes.

Global contributions: Considered for all themes in the system by using a plugin.xml file as part of a compressed file in the portal class path, web module, or as a single file in the WEB-INF directory of a web module. Each contribution contains a single theme module with a unique ID.
Theme-specific contributions: Can be referenced only by the theme that defines them by using a JSON file within the theme.

A module defines its contributions by using a plugin.xml file. The theme module must be declared within this extension point: com.ibm.portal.resourceaggregator.module.

The following code is an example of a plugin.xml file where the module is deployed within a web application using the context root /HelloWorld.

<extension point="com.ibm.portal.resourceaggregator.module" id="TestModule18" >
    <module id="testModule18" version="1.0" > 
    <prereq id="testModuleA" />
    <capability id="capabilityA" value="1.0.0"/>
    <contribution type="head">
       <sub-contribution type="css">
            <uri value="res:/HelloWorld/css/helloWorld.css" /> 
       </sub-contribution>
       <sub-contribution type="js">
            <uri value="res:/HelloWorld/js/helloWorld_head.js" /> 
       </sub-contribution>
       <sub-contribution type="markup">
           <uri value="res:/HelloWorld/html/helloWorld_head.html" /> 
       </sub-contribution>
   </contribution>
</module> 
</extension>

The following figure depicts the XML schema for this extension point:

The following samples describe how to achieve certain setups.

Procedure

Optional: Define the version information.
1. For modules, use <module id="module_ID" version="x.y">.
2. For the module prerequisites, use <prereq id="prereq_module_ID" version="x.y"/>
3. Use the plugin.xmlfile to define different versions for modules and required module.
Optional: Define a JavaScript file. JavaScript files are defined as a subcontribution.
1. If multiple JavaScript files are included by a module, add a separate subcontribution for each JavaScript file.
```
<uri value="res:/HelloWorld/js/helloWorld_head.js"/>
```

Optional: Define an alternative JavaScript file for other locales.

Within the same subcontribution, add a second URI with the appropriate locale attribute.

<uri lang="de" value="res:/HelloWorld/js/helloWorld_head_de.js"/>

For example:

<uri lang="de" value="res:/HelloWorld/js/helloWorld_head_de.js"/>
<uri lang="el" value="res:/HelloWorld/js/helloWorld_head_el.js"/>
<uri lang="en" value="res:/HelloWorld/js/helloWorld_head_en.js"/>
<uri value="res:/HelloWorld/js/helloWorld_head_root.js" />

Optional: Define an alternative JavaScript file for debugging purposes.
1. To debug the client-side code of a theme, supply a second entry for a debug subcontribution type debug to provide a more readable version of the JavaScript file.
```
<sub-contribution type="js">
  <uri value="res:/HelloWorld/js/helloWorld_head.js"/>
  <uri type="debug" value="res:/HelloWorld/js/helloWorld_head.js.uncompressed.js" />
</sub-contribution>
```
Optional: Define a CSS file.
1. The CSS file is defined as a subcontribution.
2. If multiple different CSS files are included by a module, add a separate subcontribution for each CSS file.
```
<sub-contribution type="css">
  <uri value="dav:fs-type1/common-resources/ibm/css/common.css"/>
</sub-contribution>
```

Optional: Define an alternate CSS file for right-to-left styles.

For CSS files that apply only when the reading direction is right-to-left, you can specify an extra URI of type rtl.

<sub-contributiontype="css">
  <uri value="dav:fs-type1/common-resources/ibm/css/common.css"/>
  <uri type="rtl" value="dav:fs-type1/common-resources/ibm/css/commonRTL.css" />
</sub-contribution>

Optional: Define a menu contribution.
1. Create a contribution of type menu with a subcontribution of type json. The subcontribution references a JSON file that defines the individual menu entries. For more information about defining menu entries, see Server-side framework.
```
<contribution type="menu" >
   <sub-contribution type="json">
      <uri value="res:/HelloWorld/json/menu.json" /> 
   </sub-contribution>
</contribution>
```
Optional: Define a module capability.
1. Theme modules can declare the capabilities of their contributions. This information is added to the overall theme client capabilities map that is carried in the com.ibm.portal.theme.client.capabilities request attribute.
2. Portlets can query from the server-side, which client-side capabilities are present, such as JavaScript libraries and CSS style catalogs. For more information about queries in the context of client-side aggregation, see Determining which client side APIs the current portal page provides.
3. For a global contribution, the plugin.xml file might look like the following example:
```
<extension point="com.ibm.portal.resourceaggregator.module" id="TestModule18" >
    <module id="testModule18" version="1.0" > 
    <prereq id="testModuleA" />
    <capability id="my-js-lib" value="1.6.2"/>
    <capability id="some-other-js-lib" value="1.8"/>
    </module> 
</extension>
```
Set the modules active or inactive at run time
1. By default, all modules that are defined are active. An inactive module is treated the same as a module that is not defined. Therefore, inactive modules are not started during portal run time.
2. Specify module activation details with the <moduleActivation> tag inside a <module> tag as shown in the following example:
```
<module id="MODULE_ID" version="1.0">

  <moduleActivation 
  class="com.ibm.portal.resourceaggregator.util.ResourceEnvironmentProviderModuleActivationHandler">
	  <parameter name="rep" value="RESOURCE_ENV_PROVIDER_NAME" />
	  <parameter name="key" value="KEY_IN_RESOURCE_ENV_PROVIDER"/> 
  </moduleActivation>

</module>
```
3. Specify a key for activation or deactivation of the module with an entry in a resource environment provider in the application server. Substitute the RESOURCE_ENV_PROVIDER_NAME with the name of the resource environment provider, and KEY_IN_RESOURCE_ENV_PROVIDER with the key within the resource environment provider.
4. For example, if you want to specify the my.module.is.active key for module activation in the resource environment provider ConfigService, the entry is: .
```
<repentry rep="ConfigService" key="my.module.is.active"/>
```
5. Enter the value of the my.module.is.active key in the corresponding resource environment provider. Valid key values are true if the module is active, or false if the module is inactive.
Optional: Define a resource for a specific device class. Within the same subcontribution, add URIs with the appropriate device class attribute. For example:
```
<sub-contribution type="css">
<uri value="res:/HelloWorld/css/my.css" />
<uri deviceClass="smartphone" value="res:/HelloWorld/css/my_smartphone.css" />
</sub-contribution>
```
The my_smartphone.css file is only used for smartphone devices. All other devices use the my.css file.