JackBe JBML compiler manual

July 20, 2006

Contents
1 Introduction 2 Files 3 Usage 3.1 Conguration . . . . . . . . . . . . . . . . . . . 3.2 Parameters . . . . . . . . . . . . . . . . . . . . 3.3 Output . . . . . . . . . . . . . . . . . . . . . . . 3.4 Command line options . . . . . . . . . . . . . . 3.5 Schema validation and xsd le location . . . . . 3.6 jbml-compile Ant task . . . . . . . . . . . . . 3.6.1 Declaring the Ant task in your build le 4 Overview of the JBML 4.1 How the JackBuilder generates the attributes 4.1.1 Parameters . . . . . . . . . . . . . . . 4.1.2 Resource bundles . . . . . . . . . . . . 4.1.3 Special cases . . . . . . . . . . . . . . . 1 2 2 2 2 3 4 4 5 5 6 7 8 8 8

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

Introduction

The JBML, or JackBe Markup Language, is an XML based language for the specication of projects and forms. A JBML le, or set of les, is used to hold the information relevant to a project and the forms it comprises. An XML dialect was

chosen to represent this information because of its ease of interpretation by both, humans and computer tools and programs. As part of JackBes development tool chain, a JBML le seats between the JackBuilder (Integrated Development Environment) and the JBML compiler. The JackBuilder, being the primary tool for project and form manipulation, is also the main producer of JBML les (though, it might not be the only). When forms are saved, these les are sent to the server to be consumed by the compiler in order to generate low-level code used for very fast form rendering, among other things. This document discusses the usage (command line and options) of the JBML compiler and gives some example of its use.

Files
jbml.jar toolkit.jar kawa.jar

The java jar les that are required for the compilation of JBML les are the following:

3
3.1

Usage
Conguration

As in the general use of the JackBe NQ Suite, the use of the JBML compiler requires a full JDK version Java 1.5, and it involves issuing a command at the operating system prompt that calls for the java interpreter, tells where the JBML compiler java archive is and appends the proper arguments. This can be put like this (the arguments will be explored later): c:\> java -jar "C:\Program Files\JackBeNQSuite\JBML\jbml.jar" [file1, file2, ...]

3.2

Parameters

The JBML compiler takes several parameters: a project le and one or more form les. The language allows for a le to contain project information only, leaving everything pertaining to the forms to separate les. 2
Copyright 2000-2006, JackBe Corp.

The directory structure created by the JackBuilder contains many directories, but as far as the JBML compiler is concerned, only some of them are important: the root of the project, where the project.jbml is located, and jf/jbml, where the form les are saved: project_root |-project.jbml |- jf |- jbml |- form1.jbml |- form2.jbml So, standing on the root of the project, we use the following: c:\project_root\> java -jar "C:\Program Files\JackBeNQSuite\JBML\jbml.jar" jbproject.jbml jf\jbml\form1.jbml jf\jbml\form2.jbml ...

3.3

Output

The location of the output directory is controlled by the <jackbe-location> tag inside <jbproject>. Tipically, this tag has a <dynamic> element with two attributes: physical, pointing to the root of webapp of our project, and virtual, that corresponds to the path of the application relative to the web server. The former, physical, is the root of the output for the compiler: <jbml> <jbproject name="example" ... > <jackbe-location> <dynamic physical="C:\tomcat5\webapps\myapp" virtual="/myapp/"/> </jackbe-location> ... </jbproject> </jbml> However, the <jackbe-location> tag can have an additional <static> element with the same attributes as <dynamic>. It is important to note that if the <static> element appears, it takes precedence over the <dynamic>. The output of the compiler is a set of les. For each project, a special le called the gc le is created, along with a series of js les, one for each form. The gc le goes to the jackbe directory inside the root, but the location of these .js les is controlled by <jf-location>, inside <workspace>. It has physical and virtual attributes too: 3
Copyright 2000-2006, JackBe Corp.

<workspace middleware="0"> ... <jf-location physical="C:\tomcat5\webapps\myapp\jf" virtual="jf/"/> ... </workspace> Say, for instance, that one compiles a project with three forms. A hierarchy that looks like this would be created: myapp |- jackbe | |- gc_1.js |-jf |- form1_1.js |- form2_1.js |- form3_1.js

3.4

Command line options

The default behavior of the compiler is to validate all the input les against the JBML schema and stop whenever a fatal error is found (there are three levels for abnormal conditions: fatal, error and warning). This behavior can be altered by specifying some options on the command line, just before the input les. The options are the following: +f error conditons will also stop compilation, not only fatal ones. +n stops validation against the schema. +i id duplication check is enabled. The compiler checks for duplicated ids and if found it stops the compilation.

3.5

Schema validation and xsd le location

The schema used for validation of JBML les can be located inside the project directories, in a subdirectory called xsd inside the directory specied by <static>/<physical> in <jackbe-location>, if a static specication exists. Otherwise, it is located in a subdirectory called xsd inside the directory specied by <dynamic>/<physical>. A copy of the schema can be also found in the JBML subdirectory of the JackBe NQ Suite installation directory. 4
Copyright 2000-2006, JackBe Corp.

The attribute xsi:schemaLocation of the <jbml> element at the beginning of every input le indicates to the compiler the position of the schema to use for validation. When generated by the JackBuilder, the schemaLocation reects the correct position within the directory layout. If, however, the default layout is not used, manual adjustment of this attribute might be required.

3.6

jbml-compile Ant task

A typical usage of the JBML compiler not only involves issuing the compiling command, but a number of other tasks that might be automated, for instance, using an Apache Ant script. To facilitate the use of the compiler in such a scenario, we provide the jbml-compile task with the following parameters: projectle Path to the jbml le including the project JBML tag. This attribute is required. validate Optional, boolean parameter that tells whether to validate the les agains the schema or not. Defaults to true failonerror Optional, boolean parameter that tells whether to stop compiling on the rst error or go ahead. Defaults to false. An additional parameter specied as a nested element is an Ant leset that species the JBML les to compile. An example use of the task looks like this: <jbml-compile projectfile="project.jbml" validate="false" failonerror="true"> <fileset dir="${sources.dir}"> <include name="**/*.jbml"/> </fileset> </jbml-compile> This fragment compiles the sources (les ended in .jbml) inside the directory specied by the sources.dir variable, validating them against the schema and stopping in case of any error. 3.6.1 Declaring the Ant task in your build le

Before using the Ant task in your build.xml le, you may need to declare it somewhere near the beginning of the script as following:

Copyright 2000-2006, JackBe Corp.

<path id="task.classpath"> <fileset dir="lib"> <include name="**/*.jar"/> </fileset> <fileset dir="."> <include name="jbml.jar"/> <include name="jbml-ant-task.jar"/> </fileset> </path> <taskdef name="jbml-compile" classname="com.jackbe.jbml.ant.JBMLCompile"> <classpath refid="task.classpath"/> </taskdef> The rst section of the code sets the classpath needed to execute the task (see the preceeding sections) and the second declares the task itself. Another option for setting the classpath is using the -lib parameter in the Ant executable, supplying the directory where the JBML jar les are installed inside the Jackbe NQ Suite: ant -lib ${nqsuiteintallpath}/JBML This avoids the need for a special classpath in the taskdef tag. The taskdef tag itself is still needed.

Overview of the JBML

When generating a JBML le, the JackBuilder conveys the information gathered through user interaction into XML elements and attributes. Most of the time, this operation is carried in a straightforward manner, translating properties from the JackBuilder palette into attributes for a given element, like a button, an image or an inputbox. For instance, suppose we have an inputbox with the following attributes set in the JackBuilder: ID areacode Name i1 6

Copyright 2000-2006, JackBe Corp.

Label area code: Left 27 Top 23 Size 20 Required no DataType Any The JBML code generated would look like the following (this is an abridged and formatted version): <jbml ...> <jbform ...> <inputtext id="areacode" name="i1" label="area code:" left="27" top="23" size="20" required="false" disabled="false" readonly="false" dataType="any"/> </jbform> </jbml>

4.1

How the JackBuilder generates the attributes

As can be appreciated, palette properties end up in general as attributes with the same name but with a lowecase initial. Certain Jackbe features, like form parameters and resource bundles, need more explanation.

Copyright 2000-2006, JackBe Corp.

4.1.1

Parameters

Jackbe supports parameterization of properties. When a property is parameterized, the following notation is used inside the JBML: <inputtext label="${parameter n}area code:" ... /> where n is the number of the parameter passed to the form. 4.1.2 Resource bundles

When using resource bundles, the syntax is very similar: <inputtext label="@{bundlename|key}" ... /> where bundlename is the name of the bundle and key selects the correct entry inside it.ts 4.1.3 Special cases

A closer examination of the JBML code for the input box shown previously will reveal that not every attribute value is simply copied from the JackBuilder palette. Some attributes receive special treatment, so they deserve a better explanation. Some attributes that take a single value in the palette might be translated into several JBML attributes. This is the case for the required attribute of the inputbox. In the JackBuilder palette, the required property can take any of the following values: No, Disabled, ReadOnly and Yes, but on the JBML le this value generates a combination of three dierent attributes, namely, required, disabled and readonly. The following table presents the controls that have properties with these characteristics, along with the attributes they generate in JBML: InputText, Calendar, InputFile, InputPassword, TextArea required = Yes translates to required = true, disabled = false, readonly = false required = No translates to required = false, disabled = false, readonly = false required = Disabled translates to required = false, disabled = true, readonly = false required = ReadOnly translates to required = false, disabled = false, readonly = true 8
Copyright 2000-2006, JackBe Corp.

Checkbox, Select, Combo, RadioGroup required = Yes translates to required = true, disabled = false required = No translates to required = false, disabled = false required = Disabled translates to required = false, disabled = true Label FormatTags This property can take any combination of the values bold, underline and italic. For each value present, a corresponding boolean attribute will be set with the name of the selection (bold, underline, italic). Body The property Name.ext for the background image gets splitted into two attributes: imageName and imageType. Menu While JackBuilder allows the use of the disabled and icon properties, these dont have a corresponding attribute in JBML.

Copyright 2000-2006, JackBe Corp.