Customize tolvenWEB Plugin

From DOC

Jump to: navigation, search

Contents

Overview

tolvenWEB is a war file located in the tolvenEAR file. It has a great deal of customization capability, including adding servlets, filters, XHTML files, facelet library tags etc. In all of the examples below, when referring to another plugin from your plugin, you need to add an import tag to your plugin. There should be only on <requires> tag (which can contain many <import> tags) and it should appear before any <extension> tags.

<requires>
     <import plugin-id="org.tolven.component.tolvenweb" />
</requires>

XHTML Files

tolvenWEB has a number of directories to which you may wish to add or override files e.g. drilldown, five, images etc. You can add one or more of the extensions below to your manifest, and then you only need create a directory in your plugin, at the same level as the manifest and add the name of that directory as the value of the sourceDirectory parameter. The values below are all examples, which just happen to match the name of the directory in tolvenWEB.

<extension id="ajaxDirectory" plugin-id="org.tolven.component.tolvenweb" point-id="ajaxDirectory">
     <parameter id="sourceDirectory" value="web/ajax" />
</extension>
<extension id="drilldownDirectory" plugin-id="org.tolven.component.tolvenweb" point-id="drilldownDirectory">
     <parameter id="sourceDirectory" value="web/drilldown" />
</extension>
<extension id="fiveDirectory" plugin-id="org.tolven.component.tolvenweb" point-id="fiveDirectory">
     <parameter id="sourceDirectory" value="web/five" />
</extension>
<extension id="imagesDirectory" plugin-id="org.tolven.component.tolvenweb" point-id="imagesDirectory">
     <parameter id="sourceDirectory" value="web/images" />
</extension>
<extension id="invitationDirectory" plugin-id="org.tolven.component.tolvenweb" point-id="invitationDirectory">
     <parameter id="sourceDirectory" value="web/invitation" />
</extension>
<extension id="manageDirectory" plugin-id="org.tolven.component.tolvenweb" point-id="manageDirectory">
     <parameter id="sourceDirectory" value="web/manage" />
</extension>
<extension id="privateDirectory" plugin-id="org.tolven.component.tolvenweb" point-id="privateDirectory">
     <parameter id="sourceDirectory" value="web/private" />
</extension>
<extension id="publicDirectory" plugin-id="org.tolven.component.tolvenweb" point-id="publicDirectory">
     <parameter id="sourceDirectory" value="web/public" />
</extension>
<extension id="stylesDirectory" plugin-id="org.tolven.component.tolvenweb" point-id="stylesDirectory">
     <parameter id="sourceDirectory" value="web/styles" />
</extension>
<extension id="templatesDirectory" plugin-id="org.tolven.component.tolvenweb" point-id="templatesDirectory">
     <parameter id="sourceDirectory" value="web/templates" />
</extension>
<extension id="vestibuleDirectory" plugin-id="org.tolven.component.tolvenweb" point-id="vestibuleDirectory">
     <parameter id="sourceDirectory" value="web/vestibule" />
</extension>
<extension id="wizardDirectory" plugin-id="org.tolven.component.tolvenweb" point-id="wizardDirectory">
     <parameter id="sourceDirectory" value="web/wizard" />
</extension>

JavaScript Files

JavaScript files can be added to tolvenWEB by placing them in your plugin zip file in a directory called, for example, web/scripts, and then adding the following extension:

<extension id="scriptsDirectory" plugin-id="org.tolven.component.tolvenweb" point-id="scriptsDirectory">
     <parameter id="sourceDirectory" value="web/scripts" />
</extension>

For this example, we will assume a file called myJavaScript.js now exists in the web/scripts directory of the plugin zip file.

Merely adding java scripts to the war file is not enough, since they need to be included by web components. One hook point for doing this is provided as a portalScriptInclude, which specifies a text file with the snippet required by the tolven portal template.

As an example, you can place the following snippet in a text file called scriptInclude/myJavaScript.txt in your plugin (easy to identify as associated with myJavaScript.js):

<script language="JavaScript" type="text/javascript"
	src="#{facesContext.externalContext.request.contextPath}/scripts/myJavaScript.js">
</script>

Note that the src path is the eventual location of the myJavaScript.js within the war file. Now add the following extension to include this information into the portal template:

<extension id="myJavaScript" plugin-id="org.tolven.component.tolvenweb" point-id="portalScriptInclude">
	<parameter id="includeFile" value="scriptInclude/myJavaScript.txt" />
</extension>

When you add new folder to the plugin project and if you intend to add this folder to plugin (.zip file) you need to update the respective build script.

<zip destfile="${zipFileName}" update="true">
	<zipfileset dir="${buildFolder}">
		<include name="devLib.jar" />
	</zipfileset>
	<zipfileset dir="." includes="scriptInclude/*.*"/>
</zip>

Facelets Library Tags

Add A Converter With No Namespace

To add a converter to tolvenWEB, which is not related to a tag library, but which is added to the faces-config.xml:

<extension id=myConverter" plugin-id="org.tolven.component.faces" point-id="globalConverter">
	<parameter id="description" value="My Converter" />
	<parameter id="converter-id" value="myConverter" />
	<parameter id="converter-class" value="com.myorg.MyConverter" />
	<parameter id="target-plugin-id" value="org.tolven.component.tolvenweb" />
</extension>
Add A Validator With No Namespace

To add a validator to tolvenWEB, which is not related to a tag library, but shows up in faces-config.xml:

<extension id=myValidator" plugin-id="org.tolven.component.faces" point-id="globalValidator">
	<parameter id="description" value="My Validator" />
	<parameter id="converter-id" value="myValidator" />
	<parameter id="converter-class" value="com.myorg.MyValidator" />
	<parameter id="target-plugin-id" value="org.tolven.component.tolvenweb" />
</extension>
Existing Namespaces

There are currently three namespaces in Tolven:

http://www.tolven.org/jsf/ccr
http://www.tolven.org/jsf/trim
http://www.tolven.org/jsf/wizard

See org.tolven.component.tolvenweb.taglibs.ccr, org.tolven.component.tolvenweb.taglibs.trim and org.tolven.component.tolvenweb.taglibs.wizard.

Add A Directory Of Source Tags To An Existing Namespace

As an example, to add taglibs to the ccr namespace, you would place your taglibs files in a directory called ccr (in the example below) in your plugin, and then add the following extension:

<extension id="tagSourceDirectory.ccr" plugin-id="org.tolven.component.tolvenweb.taglibs.ccr" point-id="tagSourceDirectory">
	<parameter id="source-directory" value="ccr" />
</extension>
Add Converter To An Existing Namespace

In the example below, myTrimConverter is being added to the trim namespace, which is defined by org.tolven.component.tolvenweb.taglibs.trim

<extension id="myTrimConverter" plugin-id="org.tolven.component.tolvenweb.taglibs.trim" point-id="tagConverter">
	<parameter id="tag-name" value="myTrimConverter" />
	<parameter id="converter-id" value="myTrimConverter" />
	<parameter id="converter-class" value="com.myorg.MyTrimConverter" />
</extension>
Add Validator To An Existing Namespace

In the example below, myTrimValidator is being added to the trim namespace, which is defined by org.tolven.component.tolvenweb.taglibs.trim

<extension id="myValidator" plugin-id="org.tolven.component.tolvenweb.taglibs.trim" point-id="tagValidator">
	<parameter id="tag-name" value="myValidator" />
	<parameter id="validator-id" value="myValidator" />
	<parameter id="validator-class" value="com.myorg.MyTrimValidator" />
</extension>
New Namespaces

When adding facelets tag libraries, this is a rare case where it is necessary for you to add extension-points. The section below shows that the first step is to add one extension which defines the namespace of for your tags. Then you can decide whether validators, converters or a tagSourceDirectory is going to be necessary. The tagSourceDirectory is a directory of tag files, which you will supply within your plugin. These will be combined into the tag-filename, which in the example below is mytags.taglib.xml:

<extension id="taglib" plugin-id="org.tolven.component.faces.taglib" point-id="taglib">
     <parameter id="namespace" value="http://www.myorg/jsf/mytags" />
     <parameter id="tag-filename" value="mytags.taglib.xml" />
     <parameter id="target-plugin-id" value="org.tolven.component.tolvenweb" />
</extension>
<extension-point id="tagValidator">
     <parameter-def id="tag-name" />
     <parameter-def id="validator-id" />
     <parameter-def id="handler-class" multiplicity="none-or-one" />
</extension-point>
<extension-point id="tagConverter">
     <parameter-def id="tag-name" />
     <parameter-def id="converter-id" />
     <parameter-def id="handler-class" multiplicity="none-or-one" />
</extension-point>
<extension-point id="tagSourceDirectory">
     <parameter-def id="source-directory" multiplicity="none-or-one" />
</extension-point>

In the section below, also to be added to your plugin manifest, basically supplies extensions to the extension-points given above. Please note that the plugin-id entries refer to your own plugin i.e. com.myorg.myplugin. That's because the extension-points above are also in the same plugin manifest. Working with and maintaining one plugin are far simpler than multiple plugins.

<extension id="validator1" plugin-id="com.myorg.myplugin" point-id="tagValidator">
     <parameter id="tag-name" value="ValidatorTag1" />
     <parameter id="validator-id" value="Validator1" />
     <parameter id="handler-class" value="com.myorg.ValidatorClass1" />
</extension>
<extension id="validator2" plugin-id="com.myorg.myplugin" point-id="tagValidator">
     <parameter id="tag-name" value="ValidatorTag2" />
     <parameter id="validator-id" value="Validator2" />
     <parameter id="handler-class" value="com.myorg.ValidatorClass2" />
</extension>
<extension id="converter1" plugin-id="com.myorg.myplugin" point-id="tagConverter">
     <parameter id="tag-name" value="ConverterTag1" />
     <parameter id="converter-id" value="Converter1" />
     <parameter id="handler-class" value="com.myorg.ConverterClass1" />
</extension>
<extension id="converter2" plugin-id="com.myorg.myplugin" point-id="tagConverter">
     <parameter id="tag-name" value="ConverterTag2" />
     <parameter id="converter-id" value="Converter2" />
     <parameter id="handler-class" value="com.myorg.ConverterClass2" />
</extension>
<extension id="tagSourceDirectory" plugin-id="com.myorg.myplugin" point-id="tagSourceDirectory">
     <parameter id="source-directory" value="tagDir" />
</extension>

WAR Class Files

In the example below, placing classes in the folder web/classes, where web is at the top level of the plugin, will result in the folders in the classes directory appearing in the WEB-INF/classes directory of the war file.

<extension id="webclasses" plugin-id="org.tolven.component.tolvenweb" point-id="classes">
     <parameter id="dir" value="web/classes"/>
</extension>

Managed Beans

Below is an example of an extension which allows a managed bean to be added to the faces-config.xml.

<extension id="my-managed-bean" plugin-id="org.tolven.component.faces" point-id="managed-bean">
	<parameter id="description" value="This is my bean" />
	<parameter id="managed-bean-name" value="myBean" />
	<parameter id="managed-bean-class" value="com.myorg.MyBean" />
	<parameter id="managed-bean-scope" value="request" />
	<parameter id="target-plugin-id" value="org.tolven.component.tolvenweb" />
</extension>

Note that the target-plugin-id refers to the tolvenweb plugin, and you should ensure that you import it into your plugin along with the other plugin referred to i.e. org.tolven.component.faces.

If you wish to actually replace a default Tolven bean, then you must use the override flag parameter:

<extension id="reg-managed-bean" plugin-id="org.tolven.component.faces" point-id="managed-bean">
	<parameter id="description" value="Used for registration and activation activities" />
	<parameter id="managed-bean-name" value="reg" />
	<parameter id="managed-bean-class" value="org.tolven.web.RegisterAction" />
	<parameter id="managed-bean-scope" value="request" />
	<parameter id="target-plugin-id" value="org.tolven.component.tolvenweb" />
	<parameter id="override" />
</extension>

In this case, the presence of the parameter is enough, and it does not require the normal value. If a value is supplied, it will be ignored.

Managed Property

Managed properties can be added as follows:

<extension id="your-managed-bean" plugin-id="org.tolven.component.faces" point-id="managed-bean">
	<parameter id="managed-property">
		<parameter id="property-name" value="yourPropertyName" />
		<parameter id="property-class" value="yourPropertyClass" />
		<parameter id="value" value="yourValue" />
	</parameter>
	<parameter id="target-plugin-id" value="org.tolven.component.tolvenweb" />
</extension>

The property-class is optional.

Navigation Rule

Most the parameters shown below should be familiar from the faces documentation, except the target-plugin-id, which is obviously the war file whose faces-config.xml is to contain this entry. The id of the extension tag need only be a unique identifier within your plugin.

New Navigation Rule

Add the following entry to your plugin manifest.

<extension id="/public/my-from.xhtml" plugin-id="org.tolven.component.faces" point-id="navigation-rule">
	<parameter id="description" value="A description of my navigation-rule" />
	<parameter id="from-view-id" value="/public/my-from.xhtml" />
	<parameter id="navigation-case">
		<parameter id="from-action" value="#{myBean.myAction}" />
		<parameter id="from-outcome" value="myOutcome" />
		<parameter id="to-view-id" value="/public/my-to.xhtml" />
		<parameter id="redirect" />
	</parameter>
	<parameter id="target-plugin-id" value="org.tolven.component.tolvenweb" />
</extension>
Override Existing Navigation Rule

To completely replace an already existing navigation-rule, add the following to your plugin manifest. The from-view-id is used to locate the rule, and the override parameter signals that the rule must already exist in the target-plugin-id.

<extension id="/public/my-from.xhtml-override" plugin-id="org.tolven.component.faces" point-id="navigation-rule">
	<parameter id="from-view-id" value="/public/my-from.xhtml" />
	<parameter id="navigation-case">
		<parameter id="from-action" value="#{myBean.myOverrideAction}" />
		<parameter id="from-outcome" value="myOverrideOutcome" />
		<parameter id="to-view-id" value="/public/my-override-to.xhtml" />
		<parameter id="redirect" />
	</parameter>
	<parameter id="override" />
	<parameter id="target-plugin-id" value="org.tolven.component.tolvenweb" />
</extension>
New Navigation Case

Add the following entry to your plugin manifest. The from-view-id is used to locate the corresponding navigation-rule in the target-plugin-id, to which this navigation-case will be added as a new navigation-case.

<extension id="/private/my-from.xhtml" plugin-id="org.tolven.component.faces" point-id="navigation-rule-contribution">
	<parameter id="from-view-id" value="/public/my-from.xhtml" />
	<parameter id="navigation-case">
		<parameter id="from-action" value="#{myBean.myOtherAction}" />
		<parameter id="from-outcome" value="myOtherOutcome" />
		<parameter id="to-view-id" value="/private/my-other-to.xhtml" />
	</parameter>
	<parameter id="target-plugin-id" value="org.tolven.component.tolvenweb" />
</extension>
Override Existing Navigation Case

Add the following entry to your plugin manifest. The from-view-id is used to locate the corresponding navigation-rule in the target-plugin-id, to which this navigation-case will be override an existing navigation-case. The existing navigation-case is identified based on the from-action, from-outcome (if it exists) and the to-view-id. In this case, the override parameter must be present.

<extension id="/private/my-from.xhtml-override" plugin-id="org.tolven.component.faces" point-id="navigation-rule-contribution">
	<parameter id="from-view-id" value="/public/my-from.xhtml" />
	<parameter id="navigation-case">
		<parameter id="from-action" value="#{myBean.myOverrideAction}" />
		<parameter id="from-outcome" value="myOverrideOutcome" />
		<parameter id="to-view-id" value="/private/my-override-to.xhtml" />
		<parameter id="override" />
	</parameter>
	<parameter id="target-plugin-id" value="org.tolven.component.tolvenweb" />
</extension>

Filters

Add New Filter

The example below shows how a new filter called YourFilter, supported by a class called com.myorg.YourFilter, can be added to the manifest of your plugin. The parameters filter-name, filter-class and url-pattern match those normally found in the filter and filter mapping definitions in a web.xml.

<extension id="YourFilter" plugin-id="org.tolven.component.war" point-id="filter">
	<parameter id="filter-name" value="Your Filter" />
	<parameter id="filter-class" value="com.myorg.YourFilter" />
	<parameter id="filter-sequence" value="10000" />
	<parameter id="web-resource-name" value="Protected Area" />
	<parameter id="transaction" value="false" />
	<parameter id="target-plugin-id" value="org.tolven.component.tolvenweb" />
</extension>
<extension id="YourFilter-contribution" plugin-id="org.tolven.component.war" point-id="filter-mapping-contribution">
	<parameter id="filter-name" value="YourFilter" />
	<parameter id="url-pattern" value="your-pattern1" />
	<parameter id="url-pattern" value="your-pattern2" />
	<parameter id="target-plugin-id" value="org.tolven.component.tolvenweb" />
</extension>

Since filters are order-sensitive, they each require a filter-sequence, which is a number. The current filter-sequence for filters in the target-plugin-id (which in the above case is org.tolven.component.tolvenweb), can be found by looking at the tolvenweb manifest.

The url-patterns intercepted by the filter may be subject to a transaction filter, which is also part of tolvenweb. If so, then the transaction should be set to true, otherwise set it to false.

Finally, url-patterns intercepted by the filter are defined in a separate extension called filter-mapping-contribution. There can be any number of url-patterns.

The web-resource-name is optional, and thus can be completely omitted. If present, it determines which security constraint the url-patterns will be subject to. There are three security constraints available, which are pre-defined in the tolvenweb plugin:

Unprotected Data: transport-guarantee=NONE
Secure pages: transport-guarantee=CONFIDENTIAL
Protected Area: transport-guarantee=CONFIDENTIAL and role-name="*" (which means a login is required)

You can find many examples of the above filters which are pre-defined in org.tolven.component.tolvenweb manifest.

Initial Parameters And Dispatchers

In the cases where you need to add init-params and dispatchers, you can use the following optional parameters:

<extension id="YourFilter" plugin-id="org.tolven.component.war" point-id="filter">
	<parameter id="filter-name" value="Your Filter" />
	<parameter id="filter-class" value="com.myorg.YourFilter" />
	<parameter id="init-param">
		<parameter id="param-name" value="someName" />
		<parameter id="param-value" value="someValue" />
	</parameter>
	<parameter id="filter-sequence" value="10000" />
	<parameter id="web-resource-name" value="Protected Area" />
	<parameter id="transaction" value="false" />
	<parameter id="target-plugin-id" value="org.tolven.component.tolvenweb" />
</extension>
<extension id="YourFilter-contribution" plugin-id="org.tolven.component.war" point-id="filter-mapping-contribution">
	<parameter id="filter-name" value="YourFilter" />
	<parameter id="url-pattern" value="your-pattern1" />
	<parameter id="url-pattern" value="your-pattern2" />
	<parameter id="dispatchers" value="FORWARD,REQUEST,INCLUDE" />
	<parameter id="target-plugin-id" value="org.tolven.component.tolvenweb" />
</extension>
Add URL Pattern To Existing Filter

By adding the following to your manifest, you can add your two url-patterns to a filter called TargetFilterName. Note that by setting optional to true, it means that there will be no exception during assembly, if the filter does not exist. For example, if the filter itself can be optional, then you would add this flag, indicating that you don't mind if the filter is not there. This would be reasonable for the PerformanceFilter, which is destined to be optional.

<extension id="your-filter-mapping-contribution" plugin-id="org.tolven.component.war" point-id="filter-mapping-contribution">
	<parameter id="filter-name" value="TargetFilterName" />
	<parameter id="url-pattern" value="your-pattern1" />
	<parameter id="url-pattern" value="your-pattern2" />
	<parameter id="optional" value="true" />
	<parameter id="target-plugin-id" value="org.tolven.component.tolvenweb" />
</extension>

Servlets

Add New Servlet

The example below shows how a new servlet called YourServlet, supported by a class called com.myorg.YourServlet, can be added to the manifest of your plugin. The parameters servlet-name, servlet-class, url-pattern and load-on-startup match those normally found in the servlet and servlet mapping definitions in a web.xml.

<extension id="YourServlet" plugin-id="org.tolven.component.war" point-id="servlet">
	<parameter id="servlet-name" value="Your Servlet" />
	<parameter id="servlet-class" value="com.myorg.YourServlet" />
	<parameter id="web-resource-name" value="Protected Area" />
	<parameter id="transaction" value="true" />
	<parameter id="load-on-startup" value="5" />
	<parameter id="target-plugin-id" value="org.tolven.component.tolvenweb" />
</extension>
<extension id="YourServlet-contribution" plugin-id="org.tolven.component.war" point-id="servlet-mapping-contribution">
	<parameter id="servlet-name" value="YourServlet" />
	<parameter id="url-pattern" value="your-url-pattern1" />
	<parameter id="url-pattern" value="your-url-pattern2" />
	<parameter id="target-plugin-id" value="org.tolven.component.tolvenweb" />

The url-patterns intercepted by the servlet may be subject to a transaction filter, which is also part of tolvenweb. If so, then the transaction should be set to true, otherwise set it to false.

Finally, url-patterns intercepted by the servlet are defined in a separate extension called servlet-mapping-contribution. There can be any number of url-patterns.

The web-resource-name is optional, and thus can be completely omitted. If present, it determines which security constraint the url-patterns will be subject to. There are three security constraints available, which are pre-defined in the tolvenweb plugin:

Unprotected Data: transport-guarantee=NONE
Secure pages: transport-guarantee=CONFIDENTIAL
Protected Area: transport-guarantee=CONFIDENTIAL and role-name="*" (which means a login is required)

You can find many examples of the above servlets which are pre-defined in org.tolven.component.tolvenweb manifest.

Add URL Pattern To Existing Servlet

By adding the following to your manifest, you can add your two url-patterns to a servlet called TargetServletName. Note that by setting optional to true, it means that there will be no exception during assembly, if the servlet does not exist. For example, if the servlet itself can be optional, then you would add this flag, indicating that you don't mind if the servlet is not there.

<extension-point id="servlet-mapping-contribution">
	<parameter-def id="TargetServletName" />
	<parameter id="url-pattern" value="your-pattern1" />
	<parameter id="url-pattern" value="your-pattern2" />
	<parameter-def id="optional" value="true" />
	<parameter id="target-plugin-id" value="org.tolven.component.tolvenweb" />
</extension-point>

Error Pages

TolvenWeb only has one default error page, which appears in the tolvenweb plugin manifest as:

<extension id="error-page" plugin-id="org.tolven.component.war" point-id="error-page">
	<parameter id="error-code" value="500" />
	<parameter id="location" value="/error.jsp" />
	<parameter id="target-plugin-id" value="org.tolven.component.tolvenweb" />
</extension>

After executing configPhase1, this manifest entry results in an equivalent entry appearing in the tolvenweb web.xml file i.e:

     <error-code>500</error-code>
          <location>/error.jsp</location>
     </error-page>
Add New Error Page Entry

To add a new error code, for example, 404, the following two entries can be added to your plugin. The first value web/public is the location of the source error page within your plugin. The second value </i>/public/error-404.jsp</i>, is the entry as it would appear in the web.xml and is also the location of the error.jsp page relative to the finally deployed web context.

<extension id="publicDirectory" plugin-id="org.tolven.component.tolvenweb" point-id="publicDirectory">
	<parameter id="sourceDirectory" value="web/public" />
</extension>

<extension id="error-page" plugin-id="org.tolven.component.war" point-id="error-page">
	<parameter id="error-code" value="404" />
	<parameter id="location" value="/public/error-404.jsp" />
	<parameter id="target-plugin-id" value="org.tolven.component.tolvenweb" />
</extension>
Override Existing Error Page Entry

Since there is currently only one (500), then placing the following entries in your plugin to switch the current code 500 handling to one carried out by your page in /public/error-500.jsp.

<extension id="publicDirectory" plugin-id="org.tolven.component.tolvenweb" point-id="publicDirectory">
	<parameter id="sourceDirectory" value="web/public" />
</extension>

<extension id="error-page" plugin-id="org.tolven.component.war" point-id="error-page">
	<parameter id="error-code" value="500" />
	<parameter id="location" value="/public/error-500.jsp" />
	<parameter id="override" />
	<parameter id="target-plugin-id" value="org.tolven.component.tolvenweb" />
</extension>
Personal tools