1 Structure and Concept

The creation of a complete project consists of 3 parts represented by different files. These are:

HTML file
The amount of specifications in the HTML file is as small as possible and consists of the required indication of the project file name and the optional indication of the colors and the text displayed while loading a project.

Project file
The project file describes the basic project structure and contains some settings needed at startup, like scrollbar settings.
The basic project structure is described by listing all the used layers, where the layer names, the files containing the corresponding layer data and the layer controlled by the user at startup are specified. The order the layers are listed will also specify their display order.

Layer file
The content of each layer will be specified in a separate file. This file contains the structure, the content and the behaviour of the corresponding layer. Each layer can access other layers by their names, which are specified in the project file, and are therefore able to influence their behaviour.

The display information within the layer file is structured by different block types. This means, that the information consists of data and organization blocks, to which specific operations can be applied.

The most elemental block type is the Container Block, whose purpose is to host other blocks and to determine whether the contained blocks are organized in columns or in rows. Container Blocks can also contain presettings for contained blocks, like text colors or the target of hyperlink calls. These presettings are passed to the contained blocks regardless of their definition depth but can be overwritten within any block. Container Blocks can contain any number of additional Container Blocks, Text Blocks and Image Blocks.

Text Blocks (TB) and Image Blocks (IB) contain the corresponding display data (i.e. text and images).

Because the different contents/themes in a layer are mostly structured by individual Container Blocks specified at top level (not within another Container Block) and are therefore separated from each other, it is possible to apply additional operations on those content blocks by using Space Blocks (SB).
Each top level Container Block can be aligned vertically respectively to the previous and the following Container Block by using Space Blocks. In the simplest form this will be done by inserting a given amount of space specified in pixels, but it can also be done by applying a specific rule, like the automatic insertion of empty spaces to center a Container or to display its content at the top or the bottom while ensuring that other top level containers are not visible.

Commands can be executed by selecting an Active Component , by occurance of an event (e.g. mouse pressed) and in dependency of the display position of the corresponding layer. Such position dependent command sequences are also defined at top level (not within any Container Block) and can be combined with Space Blocks, e.g. to pause the automatic scrolling for a given duration after centering the Container Block.

Command sequences of any type (incl. Free Macros and Event Macros ) are specified by listing all the single commands to be executed when the command sequence is invoked. Each command of the sequence refers to the last stated layer within the sequence or even to all layers.

Commands of any layer can refer to any layer of the current project and can also be reassigned or redefined at runtime.

Insertion of Comments

Comments can be inserted at any position within project and layer files. A comment line is initiated by 2 slash chars // and lasts till end of line.

Example:

// comment: Definition of event macros
Init={start}   // comment: will start the automatic scrolling after initializing this layer

// comment: Definition of used images
Images={
    img1='images/logo.gif'
}

// comment: Definition and Layout of the display information
{ Columns
    TB = { Width='30'
        Text='This text will be displayed in the first column'
    }

    // comment: this container organizes its components in rows and will be centered within its parent container
    { Rows; Center
        TB={ Width='70'
            Text='This text will be displayed in the first row of the second column'
        }
        IB={ Width='70'; Center // comment: image will be centered in the second row of the second column
            Image='img1'
        }
    }
    TB = { Width='100'
        Text='This text will be displayed in the third column'
    }
}
SB='Center' // comment: This will center the whole container
Commands={Pause='3000'} // comment: the automatic scrolling will be paused for 3 seconds after centering the container

SB='1'  // comment: layer will only scroll, if it is larger than the display area

2 Integration of the Applet in the HTML File

The applet and all accompanying class files are compressed in only one jar-file. This reduces both, the data to be transmitted and the connections to be made to the server.

The following applet contained therein can be used:

• Ticker.class

The amount of parameters in the HTML file is as small as possible and consists therefore of values needed at startup.

Important:
The applet needs the author parameter, which must be identical to:

<PARAM NAME="Author" VALUE="JET - Java Extended Ticker - (c) exsys GbR Emden - www.java.exsys.net">

Please, copy and paste this value to prevent typing errors.

Parameter:

Example:

<APPLET CODE="Ticker.class" WIDTH="360" HEIGHT="240" ARCHIVE="jet.jar" NAME="jet_name" MAYSCRIPT>

    <PARAM NAME=ProjectFile VALUE="demo.prj">
    <PARAM NAME=LoadingBGColor VALUE="0x000000">
    <PARAM NAME=LoadingTextColor VALUE="0x999999">
    <PARAM NAME=LoadingMessage VALUE="Loading...">

</APPLET>

Consider that the JAR-file must be indicated in the applet parameter.

The MAYSCRIPT indication is only required, if there are any calls from the applet to JavaScript.

The assignment of an applet name (in the example: Name="jet_name") is only required, if the applet is controlled/accessed via JavaScript.

Not every browser supports the communication between Java and JavaScript.

3 Project File

Basic project settings are specified in the project file. Nevertheless some of this settings can be modified at runtime.
Beside of the scrollbar configuration, the activation or deactivation of the drag mode and the definition of the background color, this file is also the location where all the layers and their hierarchy are defined. The recommended extension for project files is .prj

Parameter:

Name:	ScrollbarLeftMargin
Description:	Left margin of the scrollbar
Values:	integer value >= 0
Default:	0

Name:	ScrollbarRightMargin
Description:	Right margin of the scrollbar
Values:	integer value >= 0
Default:	0

Name:	ScrollbarMarginColor
Description:	Color of the margin area generated by ScrollbarLeftMargin and/or ScrollbarRightMargin
Values:	hexadecimal, in the form: 0xrrggbb or #rrggbb
Default:	black

Keywords related to Layer:

The specification of a layer is made by the following keywords:

Example of a project file:

BGColor = '0x000000'
DragMode='no'
ScrollbarActive='no'
ScrollbarPosition='Right'
ScrollbarWidth='11'
ScrollbarLeftMargin='3'
ScrollbarRightMargin='0'
ScrollbarBGColor='0x000000'
ScrollbarMarginColor='0x000000'
ScrollbarButtonColor='0xAAAAAA'
ScrollbarSliderColor='0xAAAAAA'
ScrollbarLineColor='0xAAAAAA'
ScrollbarArrowColor='0x000000'
ScrollbarActiveArrowColor='0xFF0000'

Layer={
    Name='loading'; File='loadinglayer.jet'
}

Layer={
    Name='menu'; File='menulayer.jet'
}

Layer={
    Name='help'; File='helplayer.jet'
}

Layer={
    Name='info'; File='info_eng.jet'
    UserControl
}

Layer={
    Name='bg'; File='bglayer1.jet'
}

4 Layer File

A layer file contains all information needed to its display and process. The position of each layer within the display hierarchy and also their names will be determined in the project file and are valid for the whole runtime. The recommended extension for layer files is .jet

A layer file consists of the following category groups:

• Basic Settings
• Definition of Event Macros
• Definition of Free Macros
• Definition of used Fonts
• Definition of used Images
• Design: Declaration of the Display Information

Example of a layer file:

// comment: Definition of event macros
Init={start} // comment: starts the automatic scrolling after initializing this layer
MouseEnter={stop} // comment: stops automatic scrolling when mouse enters area
MouseExit={Start} // comment: starts automatic scrolling when mouse leaves area

// comment: Definition of used fonts
Fonts={
    Name='normalFont'; Size='12'; Style='bold'; font='TimesRoman' |
    Name='bigFont'; Size='18'; Style='bold'+'italic'; font='TimesRoman'
}

// comment: Definition of used images
Images={
    img1='images/logo.gif' |
    offImg='images/passive.gif' |
    onImg='images/active.gif'
}

// comment: Definition and Layout of the display information

Label='Main'    // comment: sets a label to jump to this position using the jump command
{ Columns
    TB = { Width='30'
        Text='This text will be displayed in the first column'
    }

    // comment: this container organizes its components in rows and will be centered within its parent container
    { Rows; Center
        TB={ Width='70'
            Text='This text will be displayed in the first row of the second column'
        }
        IB={ Width='70'; Center // comment: image will be centered in the second row of the second column
            Image='img1' 
        }
    }

    TB = { Width='100'
        Text='This text will be displayed in the third column'
    }
}
SB='Center' // comment: This will center the whole container
Commands={Pause='3000'} // comment: the automatic scrolling will be paused for 3 seconds after centering the container

{ Target='_blank'; Font='normalFont' // comment: default is rows
    TB={ Center; TextAlignment='Right' // comment: the block will be centered and ist content aligned to the right side
        Text='This text contains a '
        URL='www.exsys.net'
        Commands={Jump='Main'}
        UnderLine='yes'
        Font='bigFont'
        ActiveText='link' // comment: Active Component executes hyperlink call and command
        UnderLine='no'
        Font='normalFont'
        Text=' that will be underlined and displayed with a bigger font and executes a hyperlink call and a command'
    }
    IB = {
        Image='offImg'; ActiveImage='onImg' //comment: switches between both images in dependency of the mouse position
    }
}
SB='Bottom' // comment: this container will be alligned to the bottom when the first container leaves the visible area

4.1 Basic Settings

The basic settings in a layer file determine some fix values needed as base to evaluate the following data or determine additional features, that can be defined one time for each layer file.

Parameter:

4.2 Definition of Event Macros

Event Macros are command sequences, that will be performed automatically when the corresponding event occurs. The definition of Event Macros is optional, but it is recommended to add the Start command to the Init Event Macro in order to initiate the automatic scrolling.

The following rules are valid when defining Event Macros:

• Event Macros can only be defined at top level (not within a container or data block)
• An Event Macro is defined by indication of its event name followed by the assignment of a command sequence or the name of a Free Macro
• The assignment of a command sequence takes place between the curly brackets { and }. The assignment of a Free Macro occurs by indication of its name enclosed by single quotes '
• Commands of a command sequence may be separated by the semicolon character ; from each other
  

Example: Event Macros:

Init={start}    // comment: will start the automatic scrolling after initializing this layer
MouseEnter='MouseOnApplet'    // comment: executed when mouse enters area; Assignment of Free Macro name
MouseExit='MouseOffApplet'    // comment: executed when mouse leaves area; Assignment of Free Macro name
ReloadRequest={Layer='LoadMsg'; ShowIncrement}    // comment: executed when layer requests reload
ReloadIndication={Layer='LoadMsg'; HideIncrement}    // comment: executed when layer is reloaded

Listing of available Event Macros:

Init:
Will be executed when the layer gets new data. This happens when a layer gets its first layer file (mostly after loading the project file) and also when the content of a layer is replaced by another layer file (different file name) using the Load command. This macro will not be executed if the current layer file is reloaded (e.g. using the Reload command).
If the automatic scrolling should be initiated at startup, it's necessary to add at least the Start command (with or without priority) to this macro. Further it's recommended to specify the scrolling speed and direction within this macro.

ReloadRequest:
Will be executed when a layer requests the replacement of its current layer file using the Load or Reload command. It will not be executed if the layer has no layer file assigned at that time (at startup or when the layer gets its first layer file), because in that case there is no layer content and therefore no Event Macros defined. Such a situation can be handled by the Init macro of the loaded layer file.

ReloadIndication:
This macro will always be executed after replacing the content of a layer (layer file) by the Load or Reload command. It doesn't matter if the layer file is replaced by a new content file or the same content file (same file name). This macro will not be executed if a layer file is loaded (initiated by another layer) to a previously empty layer (layer that has no layer file assigned at that time).
Consider that this Event Macro will be executed after the loading process is finished, so that the ReloadIndication macro of the loaded layer file will be taken.

MouseEnter:
Will be executed each time the mouse enters the applet area

MouseExit:
Will be executed each time the mouse leaves the applet area

MouseOnLink:
Will be executed as soon as the mouse is on an Active Component

MouseOffLink:
Will be executed as soon as the mouse leaves the area of an Active Component

MousePressed:
This Event Macro will be executed as soon as the mouse button is pressed on the applet area. It will not be executed by the user controlled layer (layer the user can control via scrollbar and/or dragging of the visible area with the mouse) if the drag mode is enabled. In that case the Event Macro will be ignored and the automatic scrolling will be paused.

MouseReleased:
This Event Macro will be executed as soon as the pressed mouse button is released. It will not be executed by the user controlled layer (layer the user can control via scrollbar and/or dragging of the visible area with the mouse) if the drag mode is enabled. In that case the Event Macro will be ignored and the automatic scrolling will be restarted if it was previously paused by the MousePressed macro.

ShowLayer:
The ShowLayer macro will be executed after unhiding a previously hidden layer.

HideLayer:
The HideLayer macro will be executed when a layer is set to be hidden.

LayerResized:
Will be executed when the display area is resized. This is the case when modifying the applet size or after enabling or disabling the display of the scrollbar.
This Event Macro is mostly not needed, but can be used when implementing some special effects.

4.3 Definition of Free Macros

Free Macros are command sequences only specified to be assigned to a Commands keyword or an Event Macro. They are used to facilitate the usage of repetitive command sequences by defining them only once as Free Macro and also to enable the definition of rotating states of a command (commands switching between different states). The definition of Free Macros is optional.

• Free Macros can only be defined at top level (not within a container or data block)
• The defininition of the Free Macros list is initiated by the keyword Macros and takes place between the curly brackets { and }
• The different Free Macros within the list may be separated by vertical strokes | or by semicolons ; from each other
• The definition of a Free Macro is done by indication of its freely selectable name followed by the assignment of a command sequence
• The assignment of a command sequence takes place between the curly brackets { and }. It should be avoided to assign a Free Macro directly to another Free Macro
• Commands of a command sequence may be separated by the semicolon character ; from each other

Example: Free Macros

// Definition of Free Macros
Macros={
    helpOn={Layer='help'; Show; Set='helpOff'} |
    helpOff={Layer='help'; Hide; Set='helpOn'}
}

// Assignment of a Free Macro
{
    TB={
        Commands='helpOn'    // comment: Assignment of a Free Macro, that rotates between 2 states
        ActiveText='Help on/off'
    }
}

4.4 Definition of used Fonts

All fonts used in a layer must be defined within the font list and can be referenced by their names.

• If no fonts are defined, a default font with the following data is used: Name='Default'; Font='SansSerif'; Size='9'; Style='Plain'
• Fonts can only be defined at top level (not within a container or data block)
• The definition of the font list is initiated by the keyword Fonts and takes place between the curly brackets { and }
• The single keywords of a font definition can be separated by semicolons ; from each other
• The different fonts must be separated by vertical strokes | from each other
• All values assigned to the keywords of a font specification are enclosed by single quotes '
• Additional fonts can be specified at a later time like illustrated in the example, but must always be specified before they are referenced

Comment:
The different text colors are defined within the corresponding container and/or text blocks.

Example:

Fonts={
    Name='F1'; Size='20'; Style='bold' + 'italic'; font='Serif' |
    Name='F2'; Size='9'; Style='plain'; font='SansSerif'
}

// Some Data followed by more font-styles

Fonts={
    Name='F3' Size='12' Style='italic' font='Serif' |
    Name='F4' Size='12' Style='plain' font='MonoSpaced'
}

Parameter:

Keywords related to Fonts:

Comment:
MS IE distinguishes between capital and small letters when specifying fonts

4.5 Definition of used Images

All images and animations, that should be displayed in a layer, must be defined within the image list and can be referenced by their name.

• The definition of images (and image list) is only required if any image should be displayed in the layer
• Images can only be defined at top level (not within a container or data block) 
• The definition of the image list is initiated by the keyword Images and takes place between the curly brackets { and }
• The single keywords of an image definition can be separated by semicolons ; or by vertical strokes | from each other
• The definition of an image is done by indication of its freely selectable name followed by the assignment of its file, which must be enclosed by single quotes '
• The assigned file can also include a path. In case of a relative path, the origin will be the CodeBase (directory in which the applet is). Pay here attention to capital and small spelling
• Image format must be JPG or GIF (image and animation)
• Additional images can be specified at a later time like illustrated in the example, but must always be specified before they are referenced

Example:

Images={ 
    img1='img/square1.jpg' | 
    img2='img/square2.jpg'
}

// Some Data followed by more images

Images={
    img3='img/product_animation.gif' |
    img4='img/cube.gif'
}

4.6 Design: Declaration of the Display Information

The structuring of the display information (layout) is mainly done by container and space blocks, whereas the real display data is represented by text and image blocks, which are located within the container blocks.
Container blocks can be considered as flexible one-dimensional tables (as rows or columns), that also have properties and presettings for the contained blocks. Nevertheless, container blocks can be nested to get multi-dimensional tables.
Space blocks are used to vertically separate adjacent top level container blocks (mostly representing different topics/themes) from each other by generating blank areas, which can be stated as fix value or as rule.
Each block, except space blocks, can get an alignment within the container it's included, whereas the parent container of top level blocks is represented by the applet window. Blocks can be centered, aligned to the right or left side or to the top or bottom, depending if they are structured in rows or columns. In addition it's also possible to align the content of a data block by using the same rules.

4.6.1 Container Block

The most elementary block type to structure the information is the container block, which is used to host additional blocks and to indicate what kind of structure should be applied on them (columns or rows). Further it's possible to define some presettings within a container block, like text colors and target of hyperlinks, which will be used by incorporated blocks. Nevertheless those presettings can be overwritten within any of the included blocks.
In order to be able to get the desired appearance/structure, it's also possible to nest various container blocks, so that a row-oriented container can be inserted within a column-oriented container.
Container blocks can contain any amount of container, text and image blocks.

Syntax:
A container block will be defined by the curly brackets { and }

Example:

{ ROWS; CENTER; Color='0xFF0000'; Target='_blank'    // comment: opening first container block
    { COLUMNS    // comment: opening second container block
        IB = {
            // specify image block content
        }
        TB = {
            // specify text block content
        }
    }    // comment: closing second container block

    TB= {
        // specify text block content
    }
}    // comment: closing first container block

Parameter:

Comment:
The main container (applet window) structures its childs (container blocks) in rows

Comment:
If both, target and url, are defined in a container, this will connect all Active Components in that container.

Comment:
Because the definition of a target and an URL within a container will produce a connection of all Active Components in that container, this will be the primary purpose to define the URL within a container.

More Container Blocks
In order to be able to increase the structuring possibilities to display the information, it is possible to add more container blocks to a container, to which the same parameters and rules described above can be applied. 

Information transfered to blocks within the container:

• Font
• Color
• OffMouseColor
• OnMouseColor
• Target
• URL
• JSCall
• Commands

4.6.2 Text Block

Text blocks (TB) are always defined within a container block and are used to specify any kind of text to be displayed.
The whole displayed text is a composition of any amount of individual Text and ActiveText components, that will be displayed like one text component. Each Text and ActiveText component will get the properties (e.g. color, font, underlining and in case of ActiveText also command sequence, URL, target, JavaScript function) valid at the time of its declaration.

It's also possible to define optional wordwraps at any position, on any text component and as much as desired. This wordwraps will only be used, if the available space is too small to display the whole word. In such a case the word will be separated at the most appropriate position. This kind of wordwrapping will considerably reduce the maintenance efforts compared to hard wordwrapping, when modifying the applet size, the display structure or the content. The optional wordwraps are also useful at runtime when the display size is altered by adding or removing the scrollbar display, because the text will adapt and therefore reformat its display to fit the new circumstances.

Consider that any line break (carriage return) within a Text or ActiveText declaration will also be displayed. Whereas tabulators will be filtered and are therefore not displayed, so that they can be used to format the source code.

Syntax: optional wordwraps
Optional wordwraps are defined by the characters \-, whereby an additional \ character in front of the sequence will lead to its display, but also has the effect of eliminating its functionality as optional wordwrap. By adding further \ characters, it's possible to combine its display and its functionality.

Examples: optional wordwraps

in\-for\-ma\-tion: has 3 optional wordwraps
\\- will be displayed as \- and has no optional wordwrap
\\\- will be displayed as \ and has one optional wordwrap
\\-\- will be displayed as \- and has one optional wordwrap

In addition to the ability to align the whole block, it's also possible to align the content of each text block (each text line) by the parameter TextAlignment to the left or right side or to center it.

Like container blocks, text blocks are also able to get a background color and/or image, which is particularly useful when designing tables or creating menu items. Nevertheless it's mostly better to define table backrounds at the container representing the corresponding row/column than at the text block.

Example:

TB= { Right; TextAlignment='Center'; BGColor='0xFFFFFF';
            OffMouseColor='0xFF0000'; OnMouseColor='0x00FF00'; Target='_blank'
            Font='standartFont'; Color='0x000000';

    Text='This textblock will be aligned to the right side of its container and each line of its content will be centerd within the textblock.
'
    Color='0x0000FF';
    Text='This text starts in a new line, will be displayed in blue and contains an '
    Font='newFont'
    URL='www.exsys.net'
    Commands={Layer='all'; Stop}
    ActiveText='Active Component'
    Font='standartFont'
    Text=' that will be displayed in another font and performs a hyperlink call and a command sequence.'
}

Parameter:

4.6.3 Image-Block

Example:

IB= { Bottom; Width='100'; ImageAlignment='Center'; Target='_blank'
    URL='www.exsys.net'
    Commands={Layer='info'; Load='exsysInfo.jet'}
    Image='img1'
    ActiveImage='img2'
}

Parameter:

4.6.4 Space Block

Space blocks (SB) are used to vertically align or separate top level container blocks (not encapsulated in another container block) from each other. Therefore space blocks can only be defined at top level.

Mostly the information of a layer is structured by several top level container blocks, each having a different context and treating a different theme. Often it's desired to visibly separate this context blocks (represented by containers) from each other, or even to ensure that only one container is visible at a time. An usual implementation would be to pause the automatic scrolling after centering (vertically) the context block while ensuring that no other block is visible. This can be done by entering a fix space between the containers, but will be significantly easier by applying a separation rule, because it must not be adjusted when modifying the content or applet size. This rules can align a content block to the top or bottom of the display area, center the block, or even insert a space area, which size depends from the size of the display area. Command sequences defined after a space block will be performed just after reaching the position given by the space block.

The position of labels will also be affected by space blocks. A space block, that places space above of a context/container block (center or bottom), considers already present space areas, so that the position of a label on top of the block will be influenced, because the space block doesn't add the full space and therefore the label isn't placed at the top of the display area. In order to still get the desired label position, there are the substitute rules FixCenter and FixBottom, which will add all the required space, regardless of the already present space.

Example:

Label='main'
{
    TB = {
        // specify text block content
    }
}
SB = 'Top'
Commands={Pause='3000'}

Label='intro'
{
    TB = {
        // specify text block content
    }
}
SB = 'FixCenter'
Commands={Pause='5000'}

Space block values and rules

Fix value: integer value > 0:
Inserts a fix space area of the indicated size in pixel

Center:
Centers the previous container block and takes care that no other block is visible. This rule considers already present space areas by subtracting their size.

Top:
Adds as much space as needed to align the previous container block at the top of the display area while preventing the display of the following container.

Bottom:
Adds as much space as needed above of the previous container to align it at the bottom of the display area while preventing the display of other containers. This rule considers already present space areas by subtracting their size.

FixCenter:
Centers the previous container block and takes care that no other block is visible. This rule does not consider already present space areas, so that the full space will be added.

FixBottom:
Adds as much space as needed above of the previous container to align it at the bottom of the display area while preventing the display of other containers. This rule does not consider already present space areas, so that the full space will be added.

ClearScreen:
Adds a space area as large as the display area. This rule considers already present space areas by subtracting their size.

FullScreen:
Adds a space area as large as the display area. This rule does not consider already present space areas, so that the full space will be added.

4.8 Commands & Command Sequences

Position dependent execution
This kind of command sequence will always be defined at top level (not within any container or data block) and are executed in dependency of their definition position and the current display position of the layer.
Position dependent command sequences support the additional keywords Top and Bottom, which are used to state whether the sequence is executed after reaching the top or the bottom of the display area. 

Because each restart of the automatic scrolling checks if a position dependent command sequence must be executed at the current display position, it's recommended to avoid the Stop command within such command sequences. This Stop command will stop the automatic scrolling just after beeing restarted by the Start command. By using the Pause command instead of the Stop command, the command sequence will not be re-executed when the pause elapses or a Start/Continue command is performed.

Effect:
Regardless of the block size, the automatic scrolling will be paused for 2 seconds just after the container block (and therefore also the data block) is aligned at the bottom of the display area.

Effect:
Regardless of the block size, the speed of the automatic scrolling will be changed just after the container block (and therefore also the data block) scrolls out of the display area (at the upper border) and therefore is no longer visible.

Effect:
Case 1: Container/data block is larger than the display area
The automatic scrolling  will be paused for 2 seconds as soon as the end of the container block (and therefore also the data block) is displayed at the bottom of the display area.

Case 2: Container/data block is smaller than the display area
The automatic scrolling  will be paused for 2 seconds as soon as the container block (and therefore also the data block) is displayed/aligned at the top of the display area.

Execution by Event Macros
The command sequence of an Event Macro will automatically be executed by the occurence of the event represented by the