docs.intersystems.com
Using InterSystems Development Environments — Atelier and Studio
Making Your Own Studio Templates
[Home] [Back] 
InterSystems: The power behind what matters   
Search:    

Making Your Own Studio Templates
You can create any of the following types of templates:
Note:
You should have some familiarity with CSP development before attempting to create Studio templates.
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:
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>.
Creating a Simple Studio Template
To create a simple Studio template, start Studio and do the following:
  1. Create a new CSP page with File > New > Caché Server Page.
  2. Replace the contents of the document with the following. (The name of the new template is MyTemplate.)
    <csp:StudioSimpleTemplate name="MyTemplate" type="CSP">
    SOME TEXT!
    
  3. Save and compile this CSP document with Build > Compile. It does not matter what file name you use for the CSP document or which namespace or CSP application you store it in.
    To make a Studio template accessible to all namespaces, save it in the %SYS namespace in /isc/studio/usertemplates.
You have now defined a template called MyTemplate (its name is specified by the name attribute of the <csp:StudioSimpleTemplate> tag). When you are in an open CSP page in the Studio Editor, select Tools > Templates > MyTemplate, and the text SOME TEXT! is inserted into the page.
The Template dialog lists templates whose type matches the document type from which you invoked the Template dialog. In our example, the MyTemplate template has a type of CSP. When you are in a CSP page in the Studio Editor, it appears on the Tools > Templates list.
You can also edit the type attribute, a comma-separated list of document types, to specify the document types the template can be called from. The list of types includes:
Studio Template Types
Template Type Template is available when your current document is a
CSP CSP document
CSR CSR document
MAC MAC routine
INT INT routine
INC INC file
BAS BASIC script
CLS Class Definition document
MVB MVBasic Routine
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:
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:
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:
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).


Send us comments on this page
Copyright © 1997-2019 InterSystems Corporation, Cambridge, MA