ismodule Element

Declare custom tags in your templates.

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.

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 aren’t required.

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

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’re 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.

This first example demonstrates the declaration, the implementation, and the application of a custom tag bgcolor, which is used for inserting 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’s the content of the sample1.isml file:

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

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

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

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: