ismodule Element

Syntax

<ismodule
  template  = template_path \\required
  name      = tag_name      \\required
  attribute = attr_name     \\0 or more
/>

template = template_path

Allowed data type: string or expression.

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

Note: Template file names and folder names can't contain spaces.

name= tag_name

Allowed data type: string. Expression isn't allowed.

tag_name is the name of the custom tag. Custom tags are always declared without the is prefix, for example, mytag. However, when using the custom tag in a template, you must include the is prefix like this: <ismytag>. Custom tags can use either case.

attribute = attr_name

Allowed data type: string. Expression isn't allowed.

Specifies attributes you want your custom tag to have. You can have as many attributes as you want. Attributes are not required.

Note: Because all attribute names stored in the Pipeline Dictionary are lowercase, use lowercase names in the definitions.

Purpose

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 don't interrupt template processing, the last one is used. You can also define a custom tag in an included template and use it afterward in the including template.

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

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

• They can be strings or expressions that are converted to strings during run time.
• They are always optional. During run time, the template processor doesn't check if attributes are missing. If needed, code a check explicitly.
• They can be accessed in the definition template simply by name. This method is similar to how user-defined variables are accessed.

Examples

This first example demonstrates the declaration, the implementation, and the application of a custom tag bgcolor, which is used for inserting specifically colored backgrounds.

Before you can use a custom tag in a template, it must 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 content of the sample1.isml file:

<!--- tag declaration --->
<ismodule template = "TagExtension/background.isml"
name = "bgcolor"
attribute = "color">
<!--- tag usage --->
<isbgcolor color = "green">

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

<!--- tag implementation --->
<isif condition="${color != null}">
<img src="${URLUtils.webRoot() + 'images/background_' + color + '.gif'}">
<iselse>
<img src="${URLUtils.webRoot() + 'images/background_default.gif'}">
</isif>

This second example is from the Reference Application, and uses the Pipeline Dictionary.

Here is the section within checkout_address.isml that references the step attribute, which keeps track of a customer's progress during checkout..

<ismodule
	template="cart/checkout_progressindicator"
	name="checkoutprogressindicator"
	attribute="step">

The template it refers to, containing the actual code of the tag, is cart/checkout_progressindicator.isml. This template uses the Pipeline Dictionary to track the step value:

<div class="checkoutprogressindicator">
	<isif condition="${pdict.step == '1'}">
		<isset name="step1state" value="active" scope="PAGE">	
		<isset name="step2state" value="inactive" scope="PAGE">	
		<isset name="step3state" value="inactive" scope="PAGE">	
		<isset name="step4state" value="inactive" scope="PAGE">	
	<iselseif condition="${pdict.step == '2'}">
		<isset name="step1state" value="inactive" scope="PAGE">	
		<isset name="step2state" value="active" scope="PAGE">	
		<isset name="step3state" value="inactive" scope="PAGE">	
		<isset name="step4state" value="inactive" scope="PAGE">	
	<iselseif condition="${pdict.step == '3'}">
		<isset name="step1state" value="inactive" scope="PAGE">	
		<isset name="step2state" value="inactive" scope="PAGE">	
		<isset name="step3state" value="active" scope="PAGE">	
		<isset name="step4state" value="inactive" scope="PAGE">	
	<iselseif condition="${pdict.step == '4'}">
		<isset name="step1state" value="inactive" scope="PAGE">	
		<isset name="step2state" value="inactive" scope="PAGE">	
		<isset name="step3state" value="inactive" scope="PAGE">	
		<isset name="step4state" value="active" scope="PAGE">	
	<iselse>
		<isset name="step1state" value="inactive" scope="PAGE">	
		<isset name="step2state" value="inactive" scope="PAGE">	
		<isset name="step3state" value="inactive" scope="PAGE">	
		<isset name="step4state" value="inactive" scope="PAGE">	
	</isif>