Using Zen
Zen Tutorial
[Back] [Next]
   
Server:docs1
Instance:LATEST
User:UnknownUser
 
-
Go to:
Search:    

This chapter describes how to create some simple web pages using Zen. The chapter is organized as a step-by-step tutorial. Topics include:

This chapter offers a foundation for topics found later in this book and in subsequent books on Zen. For a more complete hands-on experience, also try the Zen QuickStart Tutorial, which is available from the Documentation home page.
Hello World
The following steps display “Hello world!” on a Zen page:
  1. Start Caché Studio.
  2. Choose the SAMPLES namespace.
  3. Choose File > New or Ctrl-N or the icon.
  4. Click the Zen tab.
  5. Click the Zen Page icon.
  6. Click OK.
  7. For Package Name choose ZENDemo.
  8. In the Class Name field, type:
  9. For Application Name choose ZENDemo.Application.
  10. Click Next.
  11. Click Finish.
  12. Place the cursor at the start of this line and click to move the insertion point there:
  13. Press Enter.
  14. Move the cursor up to the blank line and click to move the insertion point there.
  15. Type a left angle bracket (<) to display a context-sensitive list of XML elements.
  16. Click button.
  17. Press Enter.
  18. Type a space to display a context-sensitive list of XML attributes.
  19. Click caption.
  20. Press Enter.
  21. Type:
  22. Choose Build > Compile or Ctrl-F7 or the icon.
  23. Choose View > Web Page or the icon.
    Your simple new Zen page displays “Hello world!” on the face of a button.
  24. Also try steps 13–24 with:
    <calendar align="right"/>
    <colorPicker/>
    <text value="Hello world!"/>
    
If you encounter difficulties during this exercise, review The Zen Demo and Supported Browsers in the chapter “Introducing Zen.” These sections provide useful background information for getting started with Zen.
Creating a Zen Application
A Zen application class extends %ZEN.application to provide application-wide styling behavior. In this exercise you create a Zen new application class, as follows:
  1. Start Caché Studio.
  2. Choose the SAMPLES namespace.
  3. Choose File > New or Ctrl-N or the icon.
  4. Select the Zen tab.
  5. Click the Zen Application icon.
  6. Click OK.
    The Zen Application Wizard presents the fields shown in the following table. For this exercise, enter the values shown in the right-hand column of the table.
    Field Meaning Value to Enter
    Package Name The package that contains the new application class. MyApp
    Class Name The class name of the new application class. MyNewApp
    Application Name The logical name of the application. My New Zen Application
    Description Any text that you want to use to describe the application. This is my first new Zen application.
    Click Finish.
  7. The Zen Application Wizard creates and displays a skeletal application class. It includes some predefined class parameters and an XData Style block as follows:
    /// This is my first new Zen application.
    Class MyApp.MyNewApp Extends %ZEN.application
    {
    
      /// This is the name of this application.
      Parameter APPLICATIONNAME = "My New Zen Application";
    
      /// This is the URL of the main starting page of this application.
      Parameter HOMEPAGE = "";
    
      /// This Style block contains application-wide CSS style definitions.
      XData Style
      {
        <style type="text/css">
        </style>
      }
    } 
  8. Choose Build > Compile or Ctrl-F7 or the icon.
Creating a Zen Page
A Zen page class extends %ZEN.Component.page to define the contents and behavior of a web page. In this exercise you create a new Zen page class in several steps.
Step 1: New Page Wizard
Create the new class as follows:
  1. Start Caché Studio.
  2. Choose the SAMPLES namespace.
  3. Choose File > New or Ctrl-N or the icon.
  4. Select the Zen tab.
  5. Click the Zen Page icon.
  6. Click OK.
    The Zen Page Wizard presents the fields shown in the following table. For this exercise, enter the values shown in the right-hand column of the table.
    Field Meaning Value to Enter
    Package Name The package that contains the page class. MyApp
    Class Name The page class name. MyNewPage
    Application The package and class name of the application that this page belongs to. MyApp.MyNewApp
    Page Name The logical name of this page within its application. My Home Page
    Domain The domain this page uses for localization of caption text. For this exercise, leave the Domain field empty.
    Description Any text that you want to use to describe the page. My very first Zen page class.
    Page type Regular page, or subclass of a template page class. For this exercise, leave the Page type field with its default selection of Page.
    Click Next.
  7. The wizard prompts you to select an initial page layout, for example:
    For this exercise, click Title Page. Then click Finish.
  8. The New Page Wizard creates and displays a skeletal Zen page with predefined class parameters and the XML blocks XData Style and XData Contents, as follows:
    Class MyApp.MyNewPage Extends %ZEN.Component.page
    {
    
      /// Class name of application this page belongs to.
      Parameter APPLICATION = "MyApp.MyNewApp";
    
      /// Displayed name of this page.
      Parameter PAGENAME = "My Home Page";
    
      /// Domain used for localization.
      Parameter DOMAIN = "";
    
      /// This Style block contains page-specific CSS style definitions.
      XData Style
      {
        <style type="text/css">
        /* style for title bar */
        #title {
          background: #C5D6D6;
          color: black;
          font-family: Verdana;
          font-size: 1.5em;
          font-weight: bold;
          padding: 5px;
          border-bottom: 1px solid black;
          text-align: center;
          }
        </style>
      }
    
      /// This XML block defines the contents of this page.
      XData Contents [XMLNamespace="http://www.intersystems.com/zen"]
      {
        <page xmlns="http://www.intersystems.com/zen" title="">
          <html id="title">Title</html>
          <vgroup width="100%">
            <!-- put page contents here -->
          </vgroup>
        </page>
      }
    }
    
    The XML blocks in this page class work together as follows:
  9. Choose Build > Compile or Ctrl-F7 or the icon.
  10. Choose View > Web Page or the icon.
    Your new Zen page displays as follows:
If you encounter difficulties when displaying any Zen page from Studio, you can display the page by opening a browser session and entering a URI in this format:
http://localhost:57772/csp/samples/MyApp.MyNewPage.cls
Where:
Step 2: XData Contents Block
In this exercise you modify the <page> element to add a simple button to the page. You can do this by typing text into the XData Contents block, or by using templates to generate a <button> element with the correct syntax. This exercise uses both techniques:
  1. In Studio, open the page class.
  2. Select the text Title within the <html> element. Replace Title with a meaningful string, for example:
  3. Remove this line just after the <vgroup> element:
    Place the cursor between <vgroup> and </vgroup> and click to move the insertion point there.
  4. Choose Tools > Templates > Templates or press Ctrl-T to display the Studio Templates dialog.
  5. Click OK to display the Zen Element Wizard dialog.
  6. In the drop-down list of XML elements, choose button. Click Next. Add properties as follows:
  7. Click Finish. The XData Contents block now looks like this:
    XData Contents [XMLNamespace="http://www.intersystems.com/zen"]
    {
      <page xmlns="http://www.intersystems.com/zen" title="">
        <html id="title">Zen Exercise Results</html>
        <vgroup width="100%">
          <button id="myButton" caption="Press Me"/>
        </vgroup>
      </page>
    }
    New additions to this XData Contents block accomplish the following:
  8. Choose Build > Compile or Ctrl-F7 or the icon.
  9. Choose View > Web Page or the icon.
    Your new Zen page displays as follows:
Step 3: Client-Side Method
In this exercise, you add a JavaScript client-side method to your Zen page class and invoke it each time the user clicks the <button>, as follows:
  1. In Studio, open the page class.
  2. Type an onclick attribute into your <button> definition as follows:
    The XData Contents block now looks like this:
    XData Contents [XMLNamespace="http://www.intersystems.com/zen"]
    {
      <page xmlns="http://www.intersystems.com/zen" title="">
        <html id="title">Zen Exercise Results</html>
        <vgroup width="100%">
          <button id="myButton" caption="Press Me" onclick="zenPage.btnClick();"/>
        </vgroup>
      </page>
    }
    The value of the onclick attribute is a JavaScript expression that executes a method called btnClick on an object called zenPage. zenPage is the JavaScript variable that represents the page object on the client side. The btnClick method is available on the client side only if you define it in your Zen page class as a client-side method. The next step explains how to do this.
  3. Place the cursor just below the closing curly brace of the XData Contents block, but above the closing curly brace of the page class. Click to move the insertion point there.
  4. Choose Tools > Templates > Templates or press Ctrl-T to display the Studio Template dialog. Choose Zen Method Wizard. Click OK to display the following dialog:
    Edit the dialog as follows:
    ClientMethod btnClick() [Language = javascript]
    {
       // TODO: implement
       alert('Client Method');
    }
    
  5. Change the code within curly braces so the method now looks like this:
    ClientMethod btnClick() [Language = javascript]
    {
       alert('Hello, World!');
    }
    
  6. Choose Build > Compile or Ctrl-F7 or the icon.
  7. Choose View > Web Page or the icon.
  8. Click the “Press Me” button to display your JavaScript alert message:
  9. Click OK to close the popup.
Some important things to notice about the btnClick method:
Step 4: Viewing the HTML Output
While viewing your Zen page in the browser, use the View Source option to look at the HTML served by the Zen page. You can see that the Zen page consists of the following elements, from top to bottom:
Step 5: Server-Side Method
In this exercise, you make a simple modification in your new Zen page. This modification demonstrates the ability to invoke server logic from within a client page, as follows:
  1. In Studio, open the page class.
  2. Using techniques from the previous exercises in this chapter, add a new button inside the XData Contents block. Give the new button the attribute values listed in the following table.
    Your XData Contents block should now resemble this one:
    XData Contents [XMLNamespace="http://www.intersystems.com/zen"]
    {
      <page xmlns="http://www.intersystems.com/zen" title="">
        <html id="title">Zen Exercise Results</html>
        <vgroup width="100%">
          <button id="myButton" caption="Press Me"
                  onclick="zenPage.btnClick();"/>
          <button caption="No, Me!" id="myButtonToo"
                  onclick="zenPage.BtnClickMe();"/>
        </vgroup>
      </page>
    }
  3. Position the cursor just below the closing curly brace of the XData Contents block, but above the closing curly brace of the page class. Click to move the insertion point there.
  4. Choose Tools > Templates > Templates or press Ctrl-T to display the Studio Template dialog. Choose Zen Method Wizard. Click OK to display the following dialog:
    Edit the dialog as follows:
    Method BtnClickMe() [ZenMethod]
    {
       // TODO: implement
       &js<alert('Server Method');>
       Quit
    }
    
  5. Change the code within curly braces so the method now looks like this:
    Method BtnClickMe() [ZenMethod]
    {
        Set msg = $ZVERSION
        &js<alert('#(msg)#');>
        Quit
    }
    
    Now the ObjectScript method BtnClickMe executes the ObjectScript $ZVERSION or $ZV utility, which produces a text string that describes the Caché version that you are running.
  6. Choose Build > Compile or Ctrl-F7 or the icon.
  7. Choose View > Web Page or the icon to display your new Zen page as follows:
  8. Click the “No, Me!” button. The following popup message appears:
  9. Click OK to close the popup.
  10. Use the View Source option of your browser to look at the HTML.
Some important things to notice about the BtnClickMe method:
Important:
The “&js< ... >” should ONLY be used when working in Synchronous mode and interacting with ClassMethods where no DOM synchronization is happening.
In an instance method, if you are modifying elements in the DOM, this code is returned by the hyperevent, bundled into a function and executed in the browser immediately on return; then the DOM is updated, overwriting any and all changes made by the function. If you are calling Asynchronously, there is also a risk that these functions may not execute in the order you expect them to.
Zen Naming Conventions
Zen programs are case-sensitive. If you are not experienced with case-sensitive programming, case might be your biggest adjustment in using Zen. Remember that a is not the same as A.
The following naming conventions apply throughout the Zen code. These conventions use case to distinguish between different categories of method or property. myMethodName and MyMethodName are not the same name.
Naming Conventions
Convention Example
Client-side methods are defined using the Language=JavaScript key phrase, and are written in JavaScript. They can be called from the client and, when called, run on the client. These names start with a lowercase letter and use an initial capital letter for each successive word (in-word capitalization). The same is true of client-only properties. myMethodName
Zen methods are defined using the keyword ZenMethod. They can be called from the client, but are executed on the server. These methods are written in ObjectScript, Caché Basic, or Caché MVBasic, but they may include embedded JavaScript that calls back to the client. Their names start with an uppercase letter, use in-word capitalization, and cannot start with the % character. MyMethodName
Server-side methods use no special keyword. They are written in ObjectScript, Caché Basic, or Caché MVBasic. They are available to be called from code that is executing on the server and, when called, they run on the server. These method names start with the % character. Server-only properties use this naming convention too. %MyMethodName
Typically, Zen class names start with lowercase and use in-word capitalization, similar to the conventions for client-side methods and properties. The exceptions to this rule include some of the server-only utility classes, which begin with an uppercase letter. tablePane
Attribute and property names start with lowercase and use in-word capitalization, except for event handlers and callbacks. filterOp
Attributes that identify event handlers for components follow the JavaScript convention of all-lowercase. onmousedown
Attributes that identify server-side callbacks for components start with On (capital letter O) and use in-word capitalization. OnCreateDataSet
Zen offers many built-in variables, as described in the Zen Pages chapter of Developing Zen Applications. The most important of these are the two variables that represent the Zen page object on the client and server sides. These two variables conform to Zen naming conventions for client and server identifiers, as follows:
Important:
InterSystems strongly recommends that you do not create any classes in a package called ZEN.Component using any combination of uppercase and lowercase characters. Creating a package called ZEN.Component breaks the Zen framework for generating client-side code.
Zen Sample Applications
If you are an experienced Caché user, you are already familiar with the SAMPLES namespace. In particular, the sample application Cinema is a favorite with users learning about Caché Server Pages (CSP). Zen offers a large number of sample pages, organized into packages in the SAMPLES namespace. If you have a new Caché installation, you must first run the ZENDemo home page. Loading this page silently generates data records for the SAMPLES namespace. You only need to do this once per Caché installation.
Enter the following URI in the browser:
http://localhost:57772/csp/samples/ZENDemo.Home.cls
Where 57772 is the web server port number that you have assigned to Caché.
Now you can view the Zen sample code at any time by following these steps:
  1. Start Caché Studio.
  2. Choose the SAMPLES namespace.
  3. In the Workspace window, choose the Namespace tab and open the Classes category.
    Packages ZENApp, ZENDemo, ZENMVC, and ZENTest are available for you to explore. You can also examine any of the other Caché samples, including the Cinema application near the top of the list.
How to Access the Sample Zen Code in Studio
Zen Wizards
Zen supplies a rich set of application programming wizards that you can run from within Caché Studio. The exercises in this chapter use several of them. For a complete list and description of the available options, see the chapter Zen Wizards.”
There is also a Studio tutorial that uses Zen wizards to create the user interface for a simple application. See the chapter Building a Simple Application with Studio in the book Using Caché Studio.