Using Studio Templates

Templates

This section contains three tables defining the templates available in Studio for use with CSP or Zen:

Class Definition Templates

Many of the CSP templates are available for use in class definitions (they can be useful in &html<> blocks). In addition, the following templates are available:

Zen Templates

You can use the following wizards (also called templates) in Zen classes. For detailed information on using these wizards, see Zen Wizards in Using Zen and the chapters referenced in the table below for select templates.

Add-In Templates

The Tools > Add-Ins menu contains a list of wizards with which you can add items to your project. The menu contains the following add-ins.

Template Architecture

Studio Templates are created and implemented using Caché Server Pages (CSP); each template is one or more server pages that run on a Caché server. When you invoke a template, Studio creates a window containing a browser and makes an HTTP request (via the built-in Caché simple HTTP server) to the CSP page associated with the template. The CSP page can either:

1. Return HTML containing an interactive form that solicits additional input from the user, or

2. Return XML containing the text to be inserted at the cursor point in Studio. (All Text and New Document Templates do this as their final step; Simple Templates, with no user interface, implement only this step; Add-in Templates do not insert text into a document.)

To make it easier to develop templates, Caché includes a set of custom CSP tags that perform all the basic operations of templates. These tags are described in the following sections.

The power of templates comes from the fact that they are running on a Caché server and have the entire power of Caché at their disposal. Therefore, for example, templates can perform sophisticated database operations.

When invoking a template, Studio passes parameters to the server, where they are accessible, in the %request object. These parameters (which are case-sensitive) may include:

• Project—name of the current Studio project.

• Namespace—name of the namespace Studio is connected to.

• User—name of the current Studio user.

• Language —ObjectScript language mode.

• Document Namespace—namespace the document belongs to (might be different from current namespace.

• Name—name of the current document, if any.

• Tabsize—Number of spaces a tab contains in the document.

• SelectedText—selected text in the current document, if any.

Give each template a unique name (unless you are replacing an existing template with a new one).

Default Template Timeout

A session timeout is the amount of time in which a session stays open without any input from a user. At the end of this time of no user input, CSP closes the session.

Templates created in Studio are stored in either of the CSP applications, /isc/studio/usertemplates (which appear on the Tools > Templates menu) or /isc/studio/templates (which appear on the Tools > Templates > Templates menu). By default, both of these applications have default session timeouts of 90 seconds. In the Management Portal, on the CSP Application options page for each of these applications, you can enter a number in the Default Timeout setting, but the number has no effect on the hard-coded session timeout of 90 seconds. This is intentional to prevent inactive Studio templates from retaining system licenses.

Simple Text Templates

A simple template is a single CSP page that returns a block of text that is inserted into the current document at the cursor point. The CSP page contains the special Studio CSP tag: <csp:StudioSimpleTemplate>.

Testing a Simple Studio Template

To test a simple text template:

1. Open an existing (or create a new) CSP page in Studio (you can use any CSP application directory). While you can continue to use the namespace in which you created the template, you probably want to connect to the namespace where you normally work.

2. Position the cursor in the CSP document editor window and select Tools > Template > Templates.

3. You see your new template in the list. Select it and select OK.

The body of the simple template is inserted at the cursor location. For example:

<html>
<body>
SOME TEXT!
</body>
</html>

Adding Logic to a Simple Studio Template

The real power of templates is that they can execute code. CSP page templates can include CSP features including:

• Embedded expressions using #( )# syntax.

• Line of code contained in a <script runat=”server”> tag.

For example, we could create a simple template that returns the current date and time (using the $ZDT function) in an HTML <B> (boldface) tag:

<csp:StudioSimpleTemplate name="Now" type="CSP">
<B>#($ZDT($H,3))#</B>

Troubleshooting a Simple Studio Template

If you have problems developing a custom template, one way to debug it is to view your template CSP page in a browser with View > Web Page while editing your CSP. Use a browser capable of displaying XML text; the value returned by a template is wrapped in XML.

For example, you can display the output of the template defined earlier in this section by entering a URL in a browser (or using File > Open URL), such as:

http://localhost:8972/csp/user/MyTemplate.csp

This results in the following XML response:

<?xml version="1.0"?>
<template>
<![CDATA[BODY##www.intersystems.com:template_delimiter##
 SOME TEXT!##www.intersystems.com:template_delimiter##]]>
</template>

The response is contained in a <template> element. The body of the response is delimited using the ##www.intersystems.com:template_delimiter## delimiter.

Interactive Studio Templates

An interactive template is a set of one or more CSP files that display a dialog window (using HTML) requesting user input. The interactive template's final page inserts a block of text into the current document at the cursor point, as a simple template does.

When you select an interactive template, Studio displays a dialog window containing a Web browser. The first page (or pages) of an interactive template returns an HTML form that solicits user input.

The first page of an interactive template starts with the <csp:StudioInteractiveTemplate> tag. The attributes of this tag are identical to those of the simple template tag. The final page (the one returning output to Studio) starts with the <csp:StudioGenerateTemplate> tag. Any intermediate pages (perhaps you are creating a multiple page wizard) do not need any special tags. The penultimate page contains a SUBMIT button that invokes the final page.

For example, suppose you want to create an interactive template, MyScript, that solicits script content and script type from a user and inserts a <script> tag into a CSP document. The first page, MyScript.csp, contains a simple HTML form:

<csp:StudioInteractiveTemplate name="MyScript" type="CSP">
<HTML>
<BODY>
<FORM NAME="form" ACTION="MyScript2.csp">
Language:
<SELECT NAME="language">
<OPTION VALUE="CACHE" SELECTED>CACHE
<OPTION VALUE="JavaScript">JavaScript
</SELECT>
<BR>
Script: <TEXTAREA NAME="script" ROWS="10" COLS="40"></TEXTAREA>
<BR>
<INPUT TYPE="submit" VALUE="OK" NAME="submit">
</FORM>
</BODY>
</HTML>

This CSP page contains:

1. A <csp:StudioInteractiveTemplate> tag specifying that this is an interactive template as well as the template's name and type.

2. An HTML form whose ACTION attribute links it to the final page of the template, MyScript2.csp (see below).

3. A SELECT control for specifying a script language.

4. A TEXTAREA control for entering the contents of the script.

5. A SUBMIT button that submits the contents of the form to the MyScript2.csp page.

The final template page, MyScript2.csp, uses the values submitted from the form to create a response that is sent back to Studio:

<csp:StudioGenerateTemplate>
<SCRIPT LANGUAGE="CACHE" RUNAT="SERVER">
    Write "<SCRIPT"
    Write " LANGUAGE=""",$G(%request.Data("language",1)),""""
    If ($G(%request.Data("language",1))="CACHE") {
        Write " RUNAT=""SERVER"""
    }
    Write ">",!
    Write $G(%request.Data("script",1)),!
    Write "<","/SCRIPT>",!
</SCRIPT>

This page starts with a <csp:StudioGenerateTemplate> tag and then includes ObjectScript code that sends back a SCRIPT tag (with appropriate attributes) to Studio. To test this, create a new CSP page and select Tools > Templates > MyScript. Enter some ObjectScript in the script box and select Ok. Script tags with your script are entered automatically into your new CSP page.

New Document Studio Templates

You can create a new document template by adding a mode attribute, with value of new, to either the <csp:StudioSimpleTemplate> or <csp:StudioInteractiveTemplate> tags.

Any template whose mode is new, appears, by name, in the New Document dialog (invoked by File > New). The results of the template are written into a newly created document.

For example, to create a new document template that creates new CSP pages, make a CSP file similar to this:

<csp:StudioSimpleTemplate name="MyCSPPage" type="CSP" mode="new">
<HTML>
<HEAD>
</HEAD>
<BODY BGCOLOR="FFDDFF">
<H1>New CSP Page</H1>
</BODY>
</HTML>

After saving this CSP file (you can save it under any CSP application) and compiling it, it appears in the Studio New dialog as MyCSPPage When selected, a new, untitled CSP document is created with the following contents:

<HTML>
<HEAD>
</HEAD>
<BODY BGCOLOR="FFDDFF">
<H1>New CSP Page</H1>
</BODY>
</HTML>

You can create more sophisticated New Document Templates by adding logic or by using an interactive template, as described above for Text Templates.

Parameters passed to the server in the %request object for a new document template are:

• Project—name of the current Studio project.

• Namespace—name of the namespace Studio is connected to.

• User—name of the current Studio user.

• Tabsize—Number of spaces a tab contains in the document.

New Class Definition Templates

If you are creating a New Document Template that creates a new class definition, you must perform an extra step in your template code: you tell Studio of the name of the new class so that it can create the correct internal data structures for the new class definition. This information is returned from the Template to Studio via data in the %session object's Data property stored under the subscripts Template and CLASS. At some point, your template should contain code similar to this:

<SCRIPT LANGUAGE="CACHE" RUNAT="SERVER">
    Set %session.Data("Template","CLASS") = classname
</SCRIPT>

Add Text to End of a Document

You can add text to end of a document template by setting an InsertAtEnd flag on the last page of either a Simple Template or an Interactive Template. If this flag evaluates to true (1), then studio inserts the template-generated text at the end of document for a non-class document or before the first <Storage> tag for a class document.

<SCRIPT LANGUAGE="CACHE" RUNAT="SERVER">
    Set %session.Data("Template","InsertAtEnd") = 1
</SCRIPT>

Add-in Studio Templates

You can create an add-in template by adding a mode attribute, with value of addin, to either the <csp:StudioSimpleTemplate> or <csp:StudioInteractiveTemplate> tags.

Any template whose mode is addin, appears, by name, in the Add-in dialog (invoked by the Tools > Add-in).

You can create Add-in Templates in the same manner as described above for Text Templates.

When invoking an add-in, Studio passes parameters to the server, where they are accessible, in the %request object. These parameters (which are case-sensitive) include the following:

• Project—name of the current Studio project.

• Namespace—name of the namespace Studio is connected to.

• User—name of the current Studio user.

• Document—name of the current document, if any.

• SelectedText—selected text in the current document, if any.

Adding Items to a Project

From an Add-in Template, you can instruct Studio to add one or more items to the current project by using the inherited method, AddToProject, on the final page of the Add-in Template.

For example, the following adds a class, MyApp.MyClass, to the current project:

<SCRIPT LANGUAGE="CACHE" RUNAT="SERVER">
    Do ..AddToProject("MyApp.MyClass.CLS") // note .CLS extension
</SCRIPT>

Note that when adding an item to a project in this way, you must append the type of item (.CLS, .CSP, .MAC, and so on) to the item name. Also note that the item must exist before you add it to a project; adding a class to a project does not automatically create such a class (but, perhaps, your Add-in Template does this using the %Dictionary class provided in the class library).