Introduction

Use <ISMODULE> to declare ISML module in your ISML templates. The declaration can be located anywhere in the template, as long as it appears before the first usage of the declared tag. Multiple declarations of the same tag do not interrupt template processing, the last one is used. You can also define a ISML module in an included template and use it afterwards in the including template.

ISML modules can be used like any other tags. In fact, a ISML module is an included template that can have user-defined attributes. Therefore, every ISML module definition is stored in a separate file. This method is similar to including a template.

Custom tag attributes are slightly restricted and generalized in their behavior and syntax, as follows:

• They may be strings or ISML expressions that are converted to strings during runtime.
• They are always optional. During runtime, the template processor does not check if attributes are missing. If such a check is needed, you have to code it explicitly.
• They can be accessed in the definition template simply by name. This method is similar to how user-defined variables are accessed.

Syntax

<ismodule
template = "( {ISML template identifier} | {ISML expression} )"
name = "{simple name}"
strict = "( {true} | {false} )"
[ attribute = "{simple name}" ]
[ returnattribute = "{simple name}" ]
>

Example

This first example demonstrates the declaration, the implementation, and the application of a ISML module bgcolor, which is used for inserting specifically colored backgrounds.
Before you can use a ISML module in a template, it needs to be declared in the same template (sample1.isml). The tag declaration must include a reference to a separate template file ( background.isml) containing the actual code of the tag. In this case, the background.isml file has been stored in a separate folder named TagExtension.

Here is the contents of the sample1.isml file:

<---! tag declaration --->
<ISMODULE template="TagExtension/background.isml" name="bgcolor" attribute="color" strict="true">
<---! tag usage --->
<ISBGCOLOR color = "green">

And here, the contents of the background.isml file:

<---! tag implementation --->
<ISIF condition="#isDefined(color)#">
  <img src="#WebRoot()#images/background_#color#.gif">
  <ISELSE>
  <img src="#WebRoot()#images/background_default.gif">
</ISIF>

This next example shows <ISMODULE> combined with server-side scripting:
The custom tag can be used to store key-value pairs in the pipeline dictionary of the current pipeline. Declaration and usage of the custom tag takes place in the sample2.isml template, where the actual code of the ISML module has been stored in a separate template file, put.isml.

Following is the code in the sample2.isml file:

<!--- tag declaration --->
<ISMODULE template="put.isml" name="put" strict="true" attribute="keyname" attribute="keyvalue">
<!--- tag use --->
<ISPUT keyname="foo" keyvalue="foobar">
<!--- tag test --->
<ISPRINT value="#foo#">

And finally, the code in the put.isml file:

<%
  if (getObject("keyname")==null)
    throw new ServletException("missing key name");
  if (getObject("keyvalue")==null)
    throw new ServletException("missing key value"); getPipelineDictionary().put((String)getObject("keyname"), getObject("keyvalue"));
%>

Attributes

template

This attribute is required.
template = ISML template identifier | ISML expression

Defines a path and a name for the ISML file implementing the tag. Relative paths are expanded from the server's template root directory. Physical paths are not allowed.

name

This attribute is required.
name = string

Name of the ISML module. ISML modules are always declared without the IS prefix, e.g., MYTAG. However, when using the custom tag in a template, you must first write the prefix like this: <ISMYTAG>. ISML modules can use either case.

strict

This attribute is required.
strict = true | false

This parameter can be used to control parameter handling.
If set to false(default), the behavior does not change compared to earlier releases:

• The whole pipeline dictionary is passed to the module.
• If a parameter is passed to a module, an already existing variable with the same name as the attribute will be overwritten in the dictionary.
• After the execution of the module, the variable is completely removed from the dictionary, even if the variable existed before (e.g., an output parameter of a pipelet).
  If set to true, strict has the following effect:
• A new empty dictionary is passed to the module only initialized with the specified attributes.
• The original pipeline dictionary will be restored after the execution of the module.

attribute

This attribute is optional.
attribute = simple name

(Unlimited) Specifies attributes you want your custom tag to have.

returnattribute

This attribute is optional.
returnattribute = simple name

With strict="true", <ISMODULE> tags can return values. Using returnattribute, the names of dictionary keys to be returned can be specified. Specified return attributes can be mapped into the pipeline dictionary of the caller.