The tip of the week for May 9, 2008 discusses how to create and call custom tags in Lasso 8.5. Custom tags are Lasso's version of functions or procedures.

One of the most important features of LassoScript is the ability to create your own custom tags. Custom tags allow you to extend Lasso's language with your own functions and procedures. Custom tags can be created on any page and called just like built-in tags. Custom tags can be used to make re-usable code, to encapsulate frequently called procedures, or to package Lasso code for distribution to others.

The tagSwap site is a repository of custom tags which you can use in your own site. The LassoTech site also contains many examples of custom tags.

Custom tags are very easy to write and can be used to good benefit on any Lasso-powered site. This tip includes a quick introduction to custom tags including how to define a basic tag, how to return a value from a tag, and how to pass parameters into a tag.

Our First Tag

The most basic tag is one which simply returns a value. This is often called a "Hello World!" example. In Lasso the tag [Ex_Hello] could be defined as follows. The [Define_Tag] ... [/Define_Tag] container defines a new tag. Within the container the [Return] tag returns the specified value.

<?LassoScript
  Define_Tag('ex_hello');
    Return('Hello World!');
  /Define_Tag;
?>

Now we can call the tag [Hello] to get back the defined result.

[Ex_Hello]  Hello World!

This is the most trivial type of tag, but can actually be useful. For example, you could define a tag [mySite_Title] which returns the title for your site. Then, anywhere you want to display the title of your site you call the tag. If you later modify the name of the site you only need to change the definition of the tag rather than doing a search/replace of the entire site.

Basic Tag

A custom tag is defined using the [Define_Tag] ... [/Define_Tag] tags. The opening [Define_Tag] requires only one parameter, which is the name of the custom tag to be defined. All of the code between the [Define_Tag] ... [/Define_Tag] tags is stored, but not executed immediately. Instead, the code will be executed when the name of the custom tag is called.

Day Name Example

The [Ex_DayName] tag defined below returns the current day of the week. We have taken some code that we might have a hard time remembering and defined a new tag which has an easier name. Now, we can use the [Ex_DayName] tag throughout our site to return the current day name any time we need it.

<?LassoScript
  Define_Tag('ex_dayname');
    Return(Date->DayofWeek(-Long));
  /Define_Tag;
?>

The [Date->DayofWeek] tag will be called each time [Ex_DayName] is called to generate the proper result. Running this tag on the day this tip was authored produced the following result.

[Ex_DayName]  Friday

Local Variables

We can use local variables to hold temporary results within our tag. This allows us to store values without polluting the variables within the page. For example, we might have a "temp" variable within our tag, but we don't want to overwrite the "temp" variable that a user has already created on a Web page.

The [Local] tag works exactly like the [Var] tag on a page, but the local variable only exists within the current run of the custom tag. The shortcut #varname can be used to reference a local variable similar to how $varname references a page variable.

Simple Next Monday Example

The [Ex_NextMonday] tag defined below returns the date of the next Monday after today. If today is Monday then today's date is returned. A local variable #curDate is set to today's date using [Date]. A [While] ... [/While] loop repeatedly adds one day to the date using [Date->Add] until the [Date->DayofWeek] tag returns 1 for Monday.

<?LassoScript
  Define_Tag('ex_nextmonday');
    Local('curDate') = Date;
    #curDate->Set(-Hour=12, -Minute=0, -Second=0);
    #curDate->SetFormat('%Q');
    While(#curDate->DayofWeek != 1);
      #curDate->Add(-Day=1);
    /While;
    Return(#curDate);
  /Define_Tag;
?>

Note that we set the time of the #curDate to noon using the [Date->Set] tag. This prevents Daylight Saving Time from throwing off our calculation. We also set the format for the date so simply calling the tag will return the date of the next Monday without the time. Running this tag on the day this tip was authored produced the following result.

[Ex_NextMonday]  2008-05-11

Optional Parameters

Custom tags can accept parameters in the same way as any built-in tags. Optional parameters are named using one or more -Optional keywords in the opening [Define_Tag].

Parameters which are passed to the tag will be matched up by keyword to the corresponding parameter name. Any parameters which do not have a keyword will be assigned to the remaining optional parameters in order.

Within the tag each optional parameter will automatically define a local variable with the same name.

Better Next Monday Example

We can improve the [Ex_NextMonday] tag by adding an optional parameter which allows the user to specify what date they want to find the next Monday after. If the user does not specify a -Date parameter then the tag will default to returning the next Monday after today's date.

We add an -Optional='date' keyword to the opening [Define_Tag]. This defines the name for the optional parameter. The [Local_Defined] tag can then be used to check for the existence of the 'date' local variable. If this local exists then the user specified a -Date parameter which should be cast to [Date]. Otherwise, the default current date is used.

<?LassoScript
  Define_Tag('ex_nextmonday', -Optional='date');
    If(Local_Defined('date'));
      Local('curDate') = Date(#date);
    Else;
      Local('curDate') = Date;
    /If;
    #curDate->Set(-Hour=12, -Minute=0, -Second=0);
    #curDate->SetFormat('%Q');
    While(#curDate->DayofWeek != 1);
      #curDate->Add(-Day=1);
    /While;
    Return(#curDate);
  /Define_Tag;
?>

Now, when we call the tag normally we get the next Monday after today. If we call the tag with a -Date parameter then we get the next Monday after the specified date. The second example shows how we can find the first Monday in the year 2008. Since the tag has only one optional parameter we can omit the -Date keyword as shown in the third example.

[Ex_NextMonday]  2008-05-11

[Ex_NextMonday(-Date='1/1/2008')]  2008-01-06

[Ex_NextMonday('1/1/2008')]  2008-01-06

Required Parameters

Custom tags may also have required parameters. Required parameters are named using one or more -Required keywords in the opening [Define_Tag].

Within the tag each required parameter will automatically define a local variable with the same name. Since the parameters are required you are guaranteed that the locals will be defined.

Simple Link Example

The following code defines a tag [Ex_Link] which formats an HTML link using a specified URL. The -URL parameter is defined as required. It is an error to call the tag without it. The -EncodeNone keyword in [Define_Tag] specifies that the output of the custom tag should not be encoded by default.

<?LassoScript
  Define_Tag('ex_link', -Required='url', -EncodeNone);
    Local('output') = '<a href=' + #url + '">' + #url + '</a>';
    Return(#output);
  /Define_Tag;
?>

When we call the tag the -URL parameter must be specified. It can either be specified explicitly as in the first example or implicitly as in the second example. However, if no URL is specified at all then an error is generated.

[Ex_Link(-URL='http://www.lassotech.com/')] 
 <a href=http://www.lassotech.com/">http://www.lassotech.com/</a>

[Ex_Link('http://www.lassotech.com/')] 
 <a href=http://www.lassotech.com/">http://www.lassotech.com/</a>

[Ex_Link()]  [em]Error[/em]

Required Parameters

We can define a tag which has both required and optional parameters. This can be useful when certain parameters are only necessary to change the default behavior of the tag.

Parameters which are passed to the tag will be matched up by keyword to the corresponding parameter name. Parameters with a keyword can match either required or optional parameters. Any parameters which do not have a keyword will be assigned first to the remaining required parameters in order, then to the remaining optional parameters.

Better Link Example

We can improve the [Ex_Link] tag by adding an optional parameter -Label which allows the user to specify the text to use as the label for the link. If no label is specified then the URL will be used as the label. We add an -Optional parameter to the tag and then check for the existence of the parameter within the tag using [Local_Defined]. Note that since the URL parameter is required we know that it will always be defined.

<?LassoScript
  Define_Tag('ex_link', -Required='url', -Optional='label', -EncodeNone);
    Local('output') = '';
    #output += '<a href=' + #url + '>';
    If(Local_Defined('label'));
      #output += #label;
    Else;
      #output += #url;
    /If;
    #output += '</a>';
    Return(#output);
  /Define_Tag;
?>

[Ex_Link(-URL='http://www.lassotech.com/', -Label='LassoTech')] 
 <a href=http://www.lassotech.com/">LassoTech</a>

More Information

See the following tips of the week for many good examples of defining custom tags in Lasso.

Custom Tag Examples
http://www.lassosoft.com/Documentation/TotW/index.lasso?9276

Recursive Tags, Algorithms, or Functions
http://www.lassosoft.com/Documentation/TotW/index.lasso?9200

Privileged Tags
http://www.lassosoft.com/Documentation/TotW/index.lasso?9020

Constants and Prototypes
http://www.lassosoft.com/Documentation/TotW/index.lasso?8694

Custom Caching
http://www.lassosoft.com/Documentation/TotW/index.lasso?8213

Custom Tags - The original version of this tip from 2004.
http://www.lassosoft.com/Documentation/TotW/index.lasso?7650

More information about creating custom tags can be found in the Lasso Language Guide or in the Lasso Reference.