Using Scripts and Templates

When building iKnowBase applications, you can use scripts and templates to implement logic and layout in a very efficient manner.

Inside iKnowBase, the term template is used to cover both scripts and templates. In fact, they are very much the same thing: A chunk of text which is evaluated at runtime, performing some kind of logic and producing some kind of output. You are free to implement templates in either FreeMarker, JavaScript or Groovy (where templates implemented using the latter two are typically called scripts).

Template concepts

The basic idea behind templates in iKnowBase can be summarized as follows:

Execution starts inside an iKnowBase component declared in the DevelopmentStudio. This component first executes whatever duties it has, and then assembles a set of model objects for the template to use
Control is then passed to the first template declared in the component. The template is then executed, and the output from the template is rendered in the context where the component is used

Available components

Templates are available for use with a large number of components:

With a Page, the template is used to render the content of the page. The most important model objects are the portlets that are defined on the page.
With a ContentViewer (through its Presentation style), the template is used to render the documents returned from the iKnowBase content store.
With a DimensionViewer, the template is used to render the dimensions returned from the content store
With a MenuViewer, the template is used to render the menu items returned from the content store
With a TemplateViewer, the template is used to render arbitrary text, or run arbitrary logic.
With a TemplateTarget, the template is used to render arbitrary text or run arbitrary logic.

Model objects

When an iKnowBase component passes control to a template, it also forwards information relevant to the execution. The actual objects available depends on the originating component, and the full list can be found in the API-reference documentation.

Available template languages

iKnowBase support template implementations in several languages:

FreeMarker, an open source tool to generate text output based on templates.
Groovy, a java-like scripting language.
JavaScript (ECMAScript), implemented through the Nashorn script engine.
HTML Script, the traditional HTML template format. Supports substitution tags (see below), as well as conditional execution using the configured parameter name and value.

The choice of language for a template is entirely up to you, but there are some typical guidelines:

If your focus is on the presentation of output, FreeMarker is often the best choice.
If your focus is on programming application logic, use one of the two other options. They are mostly equivalent, and the choice mostly comes down to what you know best: JavaScript programmers will chose the JavaScript engine, and java programmers will chose Groovy.
If you need both application logic and complex logic, the best solution may be to use template chaining to combine either JavaScript or Groovy with FreeMarker, for the best of both worlds.

FreeMarker

iKnowBase supports the use of FreeMarker templates. When using FreeMarker templates, you will combine static markup, standard FreeMarker functionality and iKnowBase model objects to create the desired output:

Static markup is the static text that you want output from the template. This is typically HTML, but can really be any kind of text that you want, for example to generate XML, RSS or JSON.
iKnowBase model objects are the data that iKnowBase makes available to you.
Standard FreeMarker functionality are directives and expressions that allow you to iterate over, print and otherwise manipulate the model objects.

In order to best utilize the FreeMarker technology, you should read the FreeMarker documentation available at http://freemarker.org/docs. Some key features are described below, but this covers only a small subset of the capabilities.

Groovy

iKnowBase supports the use of Groovy templates. When using Groovy templates, you will use the power of groovy to create the desired output, or perform the required actions.

Implicit objects

When using Groovy, iKnowBase will always provide you with a number of “implicit objects” available to the script. These are documented in the API Reference, under each component type, and are the same objects that are being made available to FreeMarker templates. However, Groovy templates have access to a number of additional objects.

For templates that run in any sort of viewer or page, the following objects are available:

Object	Description
out	A PrintWriter representing the output destination
html	A MarkupBuilder useful for creating HTML or XML markup to the output destination
json	A StreamingJsonBuilder useful for creating JSON markup to the output destination

When running in a web settings, where there is in fact an underlying HTTP servlet, the following objects are also available:

httpServletRequest	A HttpServletRequest providing access to the underlying HttpServletRequest
httpServletResponse	A HttpServletResponse providing access to the underlying HttpServletResponse

For templates that run as a Script Target, the following additional objects are also available:

Object	Description
sout	A ServletOutputStream representing the output destination

Examples

This example shows a couple of items. First, how you can use the iknowbase-object to get a Groovy SQL object, and then use that to query the database. Second, it shows how the implicit MarkupBuilder named html can be used to produce well-formatted html output.

 // Prepare some data
def pageTitle = "/SYSTEST/Action/GroovyScript-HtmlBuilder"
def users = iknowbase.sql.rows("select * from all_users where rownum <= 5")

// Output a complete html-document
html.html {
   head {
      title(pageTitle)
      style(type:"text/css","""
      table { border:thin solid black; width:100%; }
      th { background-color: #999 }
      """)
   }
   body {
      h1(pageTitle)
      table {
         tr {
            th("User ID")
            th("Username")
         }
         users.each { user->
            tr {
               td(user.user_id)
               td(user.username.toLowerCase())
            }
         }
      }
   }
}

This example shows how the implict StreamingJsonBuilder named json can automate the production of json:

def dbUsers = iknowbase.sql.rows("select * from all_users where rownum <= 5")

// Output a complete json-document
def userlist = [users:dbUsers.collect { [id:it.user_id, username:it.username.toLowerCase() ] }]
def userinfo = [userinfo:userlist]

json(userinfo)

This example shows how to use the documentService to create a document from an activitiy Script task.

import com.iknowbase.api.contentservices.v2.model.*;
def userref = new UserReference().withUsername(initiator)

def document = new Document()
document.documentIdentity = new DocumentReference(null, null, "activiti_" + execution.getProcessInstanceId(), null, null)
document.title = "Activiti Process - ProcessInstanceId: " + execution.getProcessInstanceId()
document.documentTypeReference = new ObjectReference(null, null, "TEMPDATA", null);

// Create ikb document
def documentReference = iknowbase.documentService.saveDocument (
   userref,
   document,
   SaveOperationEnumeration.INSERT,
   SaveOperationEnumeration.NONE,
   SaveOperationEnumeration.NONE,
   null, null, null, false
);

JavaScript

iKnowBase supports the use of JavaScript templates. When using JavaScript templates, you will use the power of JavaScript to create the desired output, or perform the required actions.

HTML script

You can use valid html. In addition, there is support for <ORACLE> tags to insert PL/SQL code.

Template chaining

iKnowBase allows template chaining, a mechanism where you combine multiple templates in one operation. For example, if you want to implement a search page, you may need to use a script (Groovy or JavaScript) to execute the actual search, but you still want the layout to be done using FreeMarker, which is better suited for that purpose.

Any component in iKnowBase that supports templating allows you to specify multiple templates, which you then name at will. iKnowBase will then proceed as follows:

iKnowBase will find the first template defined in the list, regardless of name, and exeucte this template.
If the template returns with a value, and this value is the name of another defined template, this template is executed next.

FreeMarker templates do not support returning a value, so any FreeMarker template will end the process. Groovy and JavaScript-templates, on the other hand, return the value of the last executed expression, so that it is simple to return the name of the next template:

// JavaScript template. Use a random value to choose template, then
// evaluate expression returning either "view-full" or "view-minimal"
var variant = Math.random() < 0.5 ? "full" : "minimal"
"view-" + variant

// Groovy-script
def variant = System.currentTimeMillis() % 2 == 0 ? "even" : "odd"
"view-$variant"

Error handling

All the template languages have their own, internal support for error handling (try-catch in JavaScript, try-catch in Groovy and #attempt/#recover in FreeMarker). However, it is often simpler to use the iKnowBase template error handling mechanism, which avoids the clutter inside each individual template.

If a template fails during execution, iKnowBase will look for a template named “ERROR”. If this template is found, it will be executed. Simple!

Using Scripts and Templates
Previous		Next
Building iKnowBase Applications		Advanced Configuration

Previous	Top	Next
Building iKnowBase Applications		Advanced Configuration