once:radix Documentation

Technical Notes

oCLI Server Addressing

A typical server address takes the form:

http://address:port_number/web_services_directory/application.html
       ?s=session_key&key-1= switch-1.. &key-n= switch-n

Where:

address Server IP address or domain name
:port_number Not required if set to port 80. The default address for Tomcat is port 8080. To change this port number, edit the file: ../Tomcat/conf/server.xml.
web_services_directoryThis is typically:
/usr/local/tomcat/webapps/once/ (Linux/Unix)
or
c:\once-project\Tomcat\webapps\once\ (Windows)
application.html
oADMINAdmin.html
oCLI Client.html
oED Editor.html
oLOGON start.html
s=session_key This Address Line Switch is mandatory. It contains a 40-character string randomly generated by Apache Tomcat. It is usually the first key=switch combination in the URL so it starts with ?. All subsequent key=switch combinations begin with &.
key=switch

Address Line Switches can be set at the first log on screen or, after logging on, by appending them to the full address (after the default language_switch). By convention, the first switch must begin with a question mark (?) with subsequent switches prefaced by an ampersand (&).

Note: Only four switches (c, d, l and s) can be set at log on. Other switches must be appened to the address after entering the application.

The language_switch is set automatically by the application based on a cookie stored in the browser. The cookie can be change by clicking a nation flag on the logon screen. It can also be overridden by typing the language_switch in the URL. See below for more details about the switch options available.

Back to Top

Logging On

If the browser is used regularly to run a once:radix based application, it is recommended that the 'Always show the tab bar' option is checked and the Home Page option is set to the log on address in the browser Preferences. On a local area network, this is typically something like:

http://192.168.111.4:8080/once/ or http://192.168.111.4:8080/once/start.html

This will display the first log on screen whenever a new window is opened in the browser.

After submitting a valid user name and password, the second logon screen is displayed. The address remains unchanged.

Subject to user access privileges, three options can be selected: oCLI, oADMIN and oED. Typical addresses after logging on to one of these applications are shown below:

oCLI

http://192.168.111.4:8080/once/Client.html
       ?s=d23122d7884a2d039e0617400695318e13492d02&l=en-us

oADMIN

http://192.168.111.4:8080/once/Admin.html
       ?s=65649f4c9e55fc3317a948313719c60538aa4708&l=en-us

oED

http://192.168.111.4:8080/once/Editor.xhtml
       ?s=65649f4c9e55fc3317a948313719c60538aa4708&l=en-us

Shortcut keys on the logon page

EEditor
ENTER        Client
A Admin
ESC Log off

Back to Top

Address Line Switches

With the exception of the session key, the Address Line Switches include:

c=c Display Owner Organisation
d=d Debug Mode
l=xx-yy Language
load=path/to/block Starting Block
ps=ps Strict Parsing Mode
s=s Session Key
t=xxxxx Theme

c=c Display Owner Organisation

Adds the currently selected owner organisation to the title bar for oCLI.

d=d Debug Mode

  1. This enables performance logging and displays shading around lock icons to show image boundaries.
  2. It disables the "Are you sure you want to leave this page?" and "Do you want to log off Once?" prompts.

  3. Enable/disable keyboard shortcuts and the right-click menu. All mouse/keyboard bindings are disabled though associated scripting runs normally. So while the context menu is disabled, the code that prevents the default context menu from being displayed is also disabled. Also, mouse bindings for elements (as well as those in palettes) are not affected, so scripting still functions.

    Press CTRL+F12. This message is displayed: 

    The page at http://192.168.111.4:8080 says: 
Debug mode keyboard/mouse. 
Context menu disabled.

    Press CTRL+F12 again to re-activate the keyboard shortcuts and the right-click menu. A message is displayed: 

    The page at http://192.168.111.4:8080 says:
Release mode keyboard/mouse.
Context menu enabled.
  4. Details of errors are always displayed in their verbose format. i.e. There is no need to click Details when an error is reported.
  5. Displays most element names in tool tips. They are displayed by pausing the cursor over most elements in Find, Browse and Edit mode. Images, boxes and rules do not show tool tips. Most tool tips take the form shown in the following example:

    #7: ID: Firstname14 (data/contacts_person_small.First_Name) tab2

    Where:

    #n: The element is the nth item in one of a number of internal lists of tab-able controls. They record information about text boxes (single and multiline), buttons, combo boxes, checkboxes, list boxes, radio buttons, file upload controls, calendars, subblocks and Gantt charts. In this example, it is the seventh item in the field list. This information is for system development. It is not useful to users or application developers.
    ID: Displays the Script Id. In this example, the Script Id is Firstname14.
    (path/ model.alias) If the element is linked to a database field, the path/model.alias is appended to the Script Id. In this example, it is (data/contacts_person_small.First_Name).
    tab

    If the field can be reached by pressing the tab key, this parameter is included at the end of the tool tip. If an element can be reached by pressing tab but no Tab Index is set in the Properties palette, no number is displayed. In this example, it is set to 2. When the page is first displayed, this field can be reached by pressing the Tab key twice.

    Labels follow a slightly different format as shown in the following example:

    ID: label389

    Where:

    ID: Displays the Script Id.
    In this example, the Script Id is label389.

ps=ps Strict Parsing Mode

This enables analysis tools that scan for problems in pages that oCLI would not normally look for (for performance reasons).

On loading a page, oCLI scans validates the page, reporting each error in a separate pop-up dialog box. 

The page at http://192.168.111.4:8080 says:
ERROR #31: Mismatched script binding
Details:
Script name: find
Block name: contacts/person_personal_details

l=xx-yy Language

This specifies a translation for oCLI to use for messages and interface elements. xx is a two-letter code for the language and yy is a two digit code for the region if applicable. Examples: 

l=en-au	l=ru-ru.

This switch is set automatically by the application based on a cookie stored in the browser. The cookie can be change by clicking a nation flag on the logon screen. It can also be set manually by typing the Language switch in the URL.

oCLI language references are defined in ../Tomcat/webapps/once/classes/client/Language.js

Note: To create applications in different languages, create a subdirectory for each language in:

../Tomcat/webapps/once/Application/

For example, to build a Russian version of an existing English application, create two subdirectories:

../Tomcat/webapps/once/Application/EN/ and ../Tomcat/webapps/once/Application/RU/

Move the existing English application (contained in the Application directory) into the ../Application/EN/ directory. Then move a copy of those same files into the ../Application/RU/ directory. Then edit all blocks to translate all labels and messages into Russian.

To build a Russian version of an exiting set of English Help files, create two subdirectories:

../Tomcat/webapps/once/help/EN/ and ../Tomcat/webapps/once/help/RU/

Move the existing English help files (contained in the help directory) into the ../help/EN/ directory. Then move a copy of those same files into the ../help/RU/ directory. Then edit all pages into Russian.

When a flag is clicked, the load = path switch should also be set. In the above example, the path to the English version would be: &load=EN/index and the path to the Russian version would be: &load=RU/index

Other blocks can be loaded overriding the load=path switch in the address panel as described below.

load=path Starting Block

Instructs oCLI to load an alternate starting block. For example:

&load=contacts/person_personal_details

oCLI will start on the person page rather than the default home page (index).

s=s Session Key

This Command Line Switch is mandatory. It contains a 40-character string randomly generated by Apache Tomcat. It is usually the first key=switch combination in the URL so it starts with ?. All subsequent key=switch combinations begin with &.

t=theme_name Theme

Themes can be created to customize the Top Menu, floating palettes and other menus. Typically this involves setting the background colour and text format. Users normally set their preferred theme through the context menu Tools > Preferences option. Once this is set, it is stored with other user preferences in a cookie in the browser.

This switch overrides the user selected menu theme. The theme must be specified as an internal name.

Adding a switch after logging on

If a switch is appended to the address after logging on, oCLI will display the message:

Are you sure you want to navigate away from this page?

Navigating away from this page will exit oCLI.

Press OK to continue, or Cancel to stay on the current page.

Click OK.

A second message is displayed:

Log Off

Do you want to log off Once?

Click No.

Back to Top

Logging Off

Like logging on, logging off is a two-stage process. A typical address on the intermediate log on screen after logging off from oCLI, oADMIN or oED would be something like:

http://192.168.111.4:8080/once/start.html
       ?s=d23122d7884a2d039e0617400695318e13492d02&l=en-us

That is, only the application name changes from Client.html, Admin.html or Editor.html to start.html.

The session_key is removed from the address panel after returning to the first log on screen. In the example above, the address becomes:

http://192.168.111.4:8080/once/start.html?l=en-us

Back to Top

Error Handling

Error messages are returned when a condition occurs in an application or system that prevents an operation from being completed. The error number and a brief description are displayed:

For a more detailed description of the problem, click Details. Full details are displayed, as shown in the example below:

Most error messages are straightforward with enough details to allow for quick diagnosis, as shown in the first three examples below:

Example 1

ERROR #02: Insufficient block permissions
Details:
No permission for block: accounts/ap_invoice_details
Session: {933cec313fc33e61af644ecc9a2846c56f36c638}

Example 2

ERROR #01: Invalid or missing model information
Details:
com.once.server.data.DataAccessException: 
    Unable to get model from file:
C:/once-fabrik/Tomcat/webapps/once/models/data/
    accounts_apinvoiceheader.mdl

or in Windows:

C:\once-fabrik\Tomcat\webapps\once\models\data\
    accounts_apinvoiceheader.mdl

The system cannot find the file specified.

Example 3

ERROR #08: Database configuration or model error
Details:
com.once.server.data.DataAccessException: Unable to perform SQL
queryorg.postgresql.util.PSQLException: 
    ERROR: invalid input syntax for type timestamp: "1209945600"

Example 4

The example below combines Java exception reporting from the server and from the PostgreSQL JDBC driver. The first part of the error message usually provides enough information to diagnose the problem. However if there is a fault is in the server code, the extra information should enable a Java programmer to identify the source of the problem.

The first item is the Java class in the server corresponding to the type of exception raised:

../Tomcat/webapps/once/WEB-INF/classes/com/once/server/data/
    DataAccessException.class

This is followed be a description of the Java class exception:

Unable to perform SQL query

Next is the JDBC driver exception within the PostgreSQL library:

org.postgresql.util.PSQLException

This is followed by a description of the JDBC driver exception:

ERROR: insert or update on table "personmember" 
    violates foreign key constraint "supplier"

Finally, the PostgreSQL error details are provided along with the Stack Trace at the time the server exception was generated. This information is only of use to a Java server programmer.

Key (fksupplier)=(0) is not present in table "supplier".

The complete error message described above is shown below:

ERROR #08: Database configuration or model error
Details:
com.once.server.data.DataAccessException: 
    Unable to perform SQL query org.postgresql.util.PSQLException: 
    ERROR: insert or update on table "personmember" 
    violates foreign key constraint "supplier"
Detail: Key (fksupplier)=(0) is not present in table "supplier".
com.once.server.jdb.DataAccessor >> executeUpdateAsync >> 309
com.once.server.data.source.sql.SQLDataSourceInsert >> execute >> 235
com.once.server.data.DataWrapper >> executeQuery >> 116
com.once.ActionSQL >> doPost >> 187
com.once.ActionSQL >> doGet >> 197
javax.servlet.http.HttpServlet >> service >> 690
javax.servlet.http.HttpServlet >> service >> 803
org.apache.catalina.core.ApplicationFilterChain >> 
    internalDoFilter >> 269
org.apache.catalina.core.ApplicationFilterChain >> 
    doFilter >> 188
com.once.server.UTF8Filter >> doFilter >> 57
org.apache.catalina.core.ApplicationFilterChain >> 
    internalDoFilter >> 215
org.apache.catalina.core.ApplicationFilterChain >> doFilter >> 188
org.apache.catalina.core.StandardWrapperValve >> invoke >> 213
org.apache.catalina.core.StandardContextValve >> invoke >> 174
org.apache.catalina.core.StandardHostValve >> invoke >> 127
org.apache.catalina.valves.ErrorReportValve >> invoke >> 117
org.apache.catalina.core.StandardEngineValve >> invoke >> 108
org.apache.catalina.connector.CoyoteAdapter >> service >> 151
org.apache.coyote.http11.Http11Processor >> process >> 874
org.apache.coyote.http11.Http11BaseProtocol$Http11ConnectionHandler 
    >> processConnection >> 665
org.apache.tomcat.util.net.PoolTcpEndpoint >> processSocket >> 528
org.apache.tomcat.util.net.LeaderFollowerWorkerThread >> runIt >> 81
org.apache.tomcat.util.threads.ThreadPool$ControlRunnable >> run >> 689
java.lang.Thread >> run >> 595
Back to Top

oCLI Error Messages

Below is a brief description of typical causes for all once:client error messages.

01 Invalid or missing model information

Screen layouts are stored as blocks. Blocks refer to the database through a system of models and metamodels. One or more errors in the metamodel and/or model files, referred to by this block, prevented oCLI from making a request to the database.

02 Insufficient block permissions

The user has insufficient access privileges to display the parent block layout. The System Administrator can allow a user access to the block (and subblocks) by setting the relevant Read option/s in the Security > Block screen for one of the Groups of users in which that user is a member.

Note: If a user is denied access to a subblock, no error is returned. The subblock is simply rendered as a blank area on the layout.

03 Reserved

04 Invalid or missing block file

Blocks and subblock files are stored as XML and CSS file sets (of the same name but with .xml and .css extensions) in the server. This error occurs when a script tries to load a block or subblock whose name does not match a block name stored on the server.

05 Missing export/print template

Exporting and printing are generated by JasperReports using template files created with i-Report. This error is generated when a script requests a template that is not stored on the server or whose name has been changed.

06 Invalid export/print template

Exporting and printing are generated by JasperReports using template files created with i-Report. This error is generated when a template file stored on the server is invalid. e.g. a field is referenced that doesn't exist, an image location is invalid, a mismatched field type (such as using a string for a float), or a Java function in the template contains errors.

07 Browser configuration error

A compatible web browser must be configured correctly. To do this, enter about:config in the browser address panel, then double-click the sign.applets.codebase_principal_support entry to change it from false to true.

08 Database configuration or model error

The database is defined by a system of models and metamodels. Syntax errors or missing information in a model file leading to incompatibilities between the model/metamodel files and the database generates this error. It can also be caused by a syntax or logic error in a database trigger or function.

09 Unable to index position for find all

This condition occurs after a record has been found and then, before it is referenced in a subsequent operation, the record is deleted by another user. e.g. If a record is displayed then, before a Find All operation is performed, another user deletes that record from the database.

10 Record insert not permitted

A script is trying to create a new record. The user has insufficient access privileges to execute the script that would create or edit database records in the specified table. The System Administrator can allow a user access to the table by setting the relevant Write and/or Modify options in the Security > Table screen for that Group of users.

11 Record unlocked by another user

once:radix supports a system of multiple read/single write. i.e. any number of users can read a record concurrently but only one may unlock the record at a time. Note that this refers to records in parent blocks and subblocks.

The record is re-locked if: 1. the user who has unlocked the record submits their changes or presses Escape to cancel edit mode; 2. A timeout period (approx. five minutes) is exceeded. If an automatic re-lock occurs, an attempt is made to auto-unlock the record on submit. If the submit fails, an 08 is returned and the changes are lost.

12 Syntax error in script

Scripts are written in Javascript. This error is returned when a page loads that contains an invalid statement.

The message details include the general javascript error which, though not always accurate, may be of some assistance in diagnosing the problem.

The line number displayed is of little use as it counts all javascript loaded, including the script containing the error. However it does display the function name.

Example:

Error #12: Syntax error in script
Details:
Script name: test
Type: SyntaxError
Message: missing ) after argument list
Line: 1766
This script will be ignored.

13 Duplicate script IDs in block

Elements such as buttons, labels and fields in a screen layout should be identified by unique script IDs. If two or more elements have the same script IDs, this error is returned. Note: A layout may contain subblocks. Care must be taken to ensure that a script ID in the parent block is not repeated in the subblock.

14 Insufficient system access privileges for oCLI

This error is returned when the user account doesn't have permissions set to allow access to once:client. This is usually set by clicking the oCLI Program Access check box on the User Details screen.

15 Unsupported export type

JasperReports supports a number of export formats including: CSV, XML, HTM, XLS, PDF and RTF. This error is returned if an export template does not support the selected export format.

16 Invalid model list in metamodel

The database is defined by a system of models and metamodels. Each metamodels defines relationships which link the models referenced in one or more screen layouts. Each model represents some or all of the fields contained in a table. This error is returned if the names of one or more of the models listed within a relationship do not match the names of actual model files.

17 Block list corrupt or invalid group

This error occurs when an attempt to run a cleanBlockPermissions or cleanTablePermissions script command fails. These commands are executed when the Refresh button is clicked on the Block Details or Table Details screens.

18 Access denied

A user is trying to create a new record or update update an existing record by attempting to unlock the record. The user has insufficient access privileges to create or edit database records in the specified table. The System Administrator can allow a user access to the table by setting the relevant Write and/or Modify options in the Security > Table screen for that Group of users.

19 Invalid session in page address

The session ID displayed in the address panel at the top of the browser is valid, provided the connection does not time out. If a time out occurs, the user is prompted to re-enter his or her password. If this is done, connection is re-established with the server and the user is allocated a new session ID. If the user later uses the old session address to create a new browser window or tab, this error is displayed.

20 Directory listing failed

This error is returned when an Open, Export, Template or Upload palette fails to return a list of files in a directory. This is usually due to the server having insufficient security access privileges to one or more directories or a file system error.

21 oCLI core overwritten by scripts

once:client is designed to not be overwritten by application scripts. In the unlikely event that this occurs, it indicates a failure of oCLI and should be reported without delay.

22 Lost connection to server

The link to the server is down. This is usually due to a physical network failure or the server has stopped running. This error can only occur during file upload or printing.

23 Unable to open file

This error occurs when the user specifies a local file to upload, but that file doesn't exist at the time of uploading. It could be due to the pathname being changed from the path displayed using the Browse function, the file being deleted midway through the upload operation, a linked drive disconnecting after the pathname was found or a file system error.

24 Inoperative server email configuration

oCLI tried to send an email but the server failed to make an SMTP connection. Ensure that the SMTP address, port, user and password are set correctly in the server's configuration.dat file.

25 Server scripting error

This error is returned if a server-side script fails. This could be caused by any number of Javascript syntax or logic errors or missing information in a model file leading to incompatibilities between the model/metamodel files and the database. It can also be caused by a syntax or logic error in a database trigger or function. Click Details when this error is returned for more information about the source of the problem.

26 Unable to display palette

Palettes such as the Sort, Export, Open and Field Index can generate this error. It is usually due to a showPalette command having an invalid palette name or by two scripts associated with one or more palettes running at the same time.

27 Invalid subblock link

This error is returned when the link between the subblock element and the parent block on which it is placed (Refer Properties palette.) is not valid. This typically occurs when a subblock element is copied and pasted onto a new parent block without re-setting its link.

28 Submitting during a submit operation

An attempt has been made to submit a record to the database while another submit operation is still in progress.

29 Error inserting stylesheet rule

Each block is stored as an XML and CSS file pair. This error occurs if the CSS file is invalid. It could be caused by an oED error when saving a block or more typically, by the CSS file being manually edited.

30 No template file specified for export

An attempt has been made to export records using an export template whose name does not match any template stored in the server.

31 Mismatched script binding

This error, which only occurs in Strict Parsing mode, is returned when a script or event is bound to an element, where:

  • The script does not exist;
  • There are more elements than events in a script binding;
  • There are more scripts than events in a script binding; or
  • The presence of excess spaces around the element scriptIDs or event names.

Note: Strict Parsing mode is used to perform page optimisation. It is entered by adding &ps=ps to the session id.

32 Invalid file link

This error occurs when a link is no longer valid for a file that has been uploaded to the server. e.g. If an uploaded file, has been moved, deleted or renamed directly on the server while the old link remains in the database.

oCLI failed to upload a file to the server. Ensure that the upload pathname is set correctly in the server's configuration.dat file and that it has the correct access permissions set.

[Repositories]
...
Upload=/upload/
...

34 Bad group membership configuration

The user has insufficient access privileges to display the home page (index.xml). The System Administrator can allow a user access to this block by setting the relevant Read option/s in the Security > Block screen for one of the Groups of users in which that user is a member.

35-n Unknown error

This message should never be displayed as all errors should be trapped prior to reaching this level. If this error is displayed, please contact your System Administrator.

Back to Top

oADMIN error messages

Below is a brief description of typical causes for all once:admin error messages.

01 Insufficient system access privileges for oADMIN

This error is returned when the user account doesn't have permissions set to allow access to once:admin. This is usually set by clicking the oADMIN Program Access check box on the User Details screen.

02 Unable to display palette

This error would be returned if oADMIN were unable to display a palette such as Restore or Schedule. If it occurs, try reloading oADMIN. If the problem continues, please contact your System Administrator.

03 The palettes XML could not be parsed

The adminpalettes.xml is validated when oADMIN is loaded. This error is returned if the file fails to validate due to the file becoming corrupted.

04 Communication with the Once server timed out

The link to the server has timed out. This is usually due to a physical network failure or the server has stopped running.

05 Server communication error

oADMIN is unable to start communication with the server for all oADMIN operations except the Run SQL command. This is usually due to a physical network failure or the server has stopped running. For the Run SQL command Error 09 is returned.

06 Unable to restore database

Typical reasons why oADMIN is unable to restore a backup copy of the database:

  • The backup file may be corrupted.
  • The Restore command in configuration.dat may be invalid.
  • The database may be set up with an authentication password. This is not required for local access. oADMIN expects no password to be set.

07 Browser configuration error

A compatible web browser must be configured correctly. To do this, enter about:config in the browser address panel, then double-click the sign.applets.codebase_principal_support entry to change it from false to true.

08 Cache rebuild failed

A cache re-build operation has failed usually because the user has expired or the user record has lost access to oADMIN. This could occur if someone unchecked the oADMIN checkbox while the cache rebuild was in process.

09 Communication initialisation error

oADMIN is unable to start communication with the server using the Run SQL command. This is usually due to a physical network failure or the server has stopped running. For other oADMIN operations Error 05 is returned.

10-18 Unknown error

This message should never be displayed as all errors should be trapped prior to reaching this level. If it occurs, please contact your System Administrator.

19 Invalid session in page address

The session ID displayed in the address panel at the top of the browser is valid, provided the connection does not time out. If a time out occurs, the user is prompted to re-enter his or her password. If this is done, connection is re-established with the server and the user is allocated a new session ID. If the user later uses the old session address to create a new browser window or tab, this error is displayed.

Note: The system is unable to set the browser window to the new session ID due to security restrictions in the browser. To avoid this error, it is recommended that users log out, then log back in again if the system times out.

20-n Unknown error

This message should never be displayed as all errors should be trapped prior to reaching this level. If it occurs, please contact your System Administrator.

Back to Top

The once:help System

once:help is fully implemented in oCLI and oLOGON, partly implemented in oED, but not implemented in oADMIN.

It is recommended that a Help button be included on all log on and application home pages. This will ensure that new users have visible access to the help system.

oCLI Top Menu

Selecting Help on the top menu links to:

../Tomcat/webapps/once/help/Client/index.html

Application developers can redirect the link to another location

oCLI Context Menu

To access Help options within the context menu, right-click the mouse button (or Ctrl-click on a single button mouse in Mac OSX) then click Help. There are five options available:

Overview    Ctrl - H

Loads ../Tomcat/webapps/once/help/Client/index.html

The default page (index.html) can be set to automatically redirect control to any other address. An example re-direction page is shown below:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 

"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"gt;
<headgt;
<title>application - Help

This example would re-direct the browser to load:


./Tomcat/webapps/once/help/Application/tutorial/intro.html


This Screen    F1


If the current application page page is called:


..Tomcat/webapps/Application/section/any_parent_block.xml


This option would attempt to load a help page called:


..Tomcat/webapps/help/Application/section/any_parent_block.html


About This User    Ctrl-?


	Displays information about the user currently logged onto the system. This command is also available by selecting About User in the Top Menu.


About Page    Ctrl-Shift-?


This function is used by application developers. It displays details about the current page, listing the block pathname, Metamodel and Relationship names for the parent block and all subblocks, as shown in the example below:


About oCLI    Shift - F1


Displays the oCLI flash palette, showing the copyright message software version number.


Back to Top


Customizing the Top Menu


General structure of the clientMenuBar.xml file:


	<menubar>
		<menu caption="menu 1">
			<item caption="item 1" target="target" />
			<separator />
			<item caption="item 2" target="target" />
			.
			.
			<item caption="item n" target="target" />
			<menu caption="submenu 1">
			<item caption="item 1.1" target="target" />
			<separator />
			<item caption="item 1.2" target="target" />
				.
			.
			<item caption="item 1.n" target="target" />
	</menu>
			<menu caption="submenu 2">
			<item caption="item 2.1" target="target" />
			<separator />
			<item caption="item 2.2" target="target" />
				.
			.
			<item caption="item 2.n" target="target" />
	</menu>
			.
			.
			<menu caption="submenu n">
			<item caption="item n.1" target="target" />
			<separator />
			<item caption="item n.2" target="target" />
				.
			.
			<item caption="item n.n" target="target" />
	</menu>
		</menu>
		<menu caption="menu 2">
			<!-- As above -->
		</menu>
		.
		.
		<menu caption="menu n">
			<!-- As above -->
		</menu>
	</menubar>


The Menubar Element


A menu bar XML file must contain one and only one menubar element as the root element of the file. The menubar element has no attributes with any effect.


The Menu Element


The menubar element can contain any number of menu elements. In addition to this, each menu element can contain any number of menu elements. In the menubar element, a menu element defines a menu. In a menu element, a menu element defines a submenu. The following attributes can be present in a menu element:


caption	The text that appears in the title of the menu


The Item Element


A menu element can contain any number of item elements. An item element cannot contain any elements. An item element defines a menu item. The following attributes can be present in an item element:


captionThe text that appears in the title of the menu item


target
Generally, this the path to a block file relative to the block repository minus its .xml or .css extension. There are also a couple of special commands that can be used instead of block file paths. They are defined as follows:


#log off#Logs out of (quit) oCLI


#help#Opens the help system (the equivalent of selecting Help->Overview)


#about user#Opens the About User dialogue box






The Separator Element


A menu element can contain any number of separator elements. A separator element cannot contain any elements and it has no attributes with any effect. A separator element defines a horizontal rule that separates menu items in a menu.


Tell client to clear their cache and shift reload once they have logged in.

Back to Top


How to create a new Theme


Themes can be created to customize the Top Menu, floating palettes and other menus. This sets the background colour and text format. Users normally set their preferred theme through the context menu Tools > Preferences option. Once set, it is stored with other preferences in a cookie.To create a new theme, add the sections below to the file "once/css/common/menu2.css", making changes as necessary. Replace xxx with a short (one word) identifier for the theme you're creating.


This section specifies overall background and foreground colours for a menu theme.


body[theme=xxx] .menuBar, body[theme=xxx] .menu
{
	background-color    : #rrggbb;
	color               : #rrggbb;
}


This section specifies a background image to be used for the menu bar.


body[theme=xxx] .menuBar
{
	background-image    : url('../../images/menu2/myImage.png');
}


This section specifies a background image to be used for menus. 


body[theme=xxx] .menu
{
	background-image    : url('../../images/menu2/myImage.png');
}


This section allows you to (optionally) override the appearance of the menu bar grabber. Remove it if the default will do. 


body[theme=xxx] .menuBarRow > .menuBarGrabber
{
	background-image    : url('../../images/menu2/myImage.png');
	width               : 9px;
}


This section allows you specify how menus appear when selected in the menu bar. 


body[theme=xxx] .menuBarRow > .menuBarTitle[selected=true]
{
	color               : #rrggbb;
	background-color    : #rrggbb;
	background-image    : url('../../images/menu2/myImage.png');
	 /* Optional */
}


This section allows you to specify how selected menu items appear in menus.


body[theme=xxx] .menuItem > td[selected=true], *:hover body[theme=xxx]
 	.menuItem > td[selected=true]
{
	color               : #rrggbb;
	background-color    : #rrggbb;
}


This section allows you to specify how inactive (disabled) menu items will appear. 


body[theme=xxx] .menuItem[inactive=true] > td, body[theme=xxx] 
	.menuItem[inactive=true] > td[selected]
{
	color               : #rrggbb;
}


These sections allow you to specify images for selected and unselected bullets and ticks. 


body[theme=xxx] .menuItem > .menuItemIconGeneral > div.tick
{
	background-image    : url('../../images/menu2/myImage.png');
}
body[theme=xxx] .menuItem > .menuItemIconGeneral > div.bullet
{
	background-image    : url('../../images/menu2/myImage.png');
}
body[theme=xxx] .menuItem > .menuItemIconGeneral[selected=true] 
	> div.tick
{
	background-image    : url('../../images/menu2/myImage.png');
}
body[theme=xxx] .menuItem > .menuItemIconGeneral[selected=true] 
	> div.bullet
{
	background-image    : url('../../images/menu2/myImage.png');
}


These sections allow you to specify images for disabled bullets and ticks. 


body[theme=xxx] .menuItem[inactive=true] > .menuItemIconGeneral 
	> div.tick, body[theme=xxx] .menuItem[inactive=true] 
	> .menuItemIconGeneral[selected] > div.tick
{
	background-image    : url('../../images/menu2/myImage.png');
}
body[theme=xxx] .menuItem[inactive=true] > .menuItemIconGeneral 
	> div.bullet, body[theme=xxx] .menuItem[inactive=true]
	 > .menuItemIconGeneral[selected] > div.bullet
{
	background-image    : url('../../images/menu2/myImage.png');
}


And finally, these sections allow you to specify selected, unselected and disabled images for the submenu arrow shown when a submenu is present. 


body[theme=xxx] .menuItem > .menuItemIconSubmenu 
	> .menuItemIconSubmenuPresent
{
	background-image    : url('../../images/menu2/myImage.png');
}
body[theme=xxx] .menuItem > .menuItemIconSubmenu[selected=true] 
	> .menuItemIconSubmenuPresent
{
	background-image    : url('../../images/menu2/myImage.png');
}
body[theme=xxx] .menuItem[inactive=true] > .menuItemIconSubmenu 
	> .menuItemIconSubmenuPresent, body[theme=xxx] 
	.menuItem[inactive=true] > .menuItemIconSubmenu[selected] 
	> .menuItemIconSubmenuPresent
{
	background-image    : url('../../images/menu2/myImage.png');
}


Adding a New Theme to the List of Themes in Preferences


1. Locate the <select> tag with the ID "Client(c)PreferencesPalette(c)cmbTheme" in data/clientPalettes.xml


2. Add a new <option> tag inside the <select> tag. The 


<option value="shortname">$$LABEL_THEME_SHORTNAME$$</option>


where shortname is the short one word name for the new theme. It can be inserted between other <option> tags (to maintain alphabetical order) or placed before the closing </select> as shown below:


	    	<select class="textarea" id="Client(c)PreferencesPalette(c)cmbTheme" style="margin(c)bottom: 2px; width: 200px;">


	    		<option value="fab">$$LABEL_THEME_FAB$$</option>


	    		<option value="mac" selected="true">$$LABEL_THEME_MAC$$</option>


	    		<option value="rad">$$LABEL_THEME_RAD$$</option>


	    		<option value="standard">$$LABEL_THEME_STANDARD$$</option>


			<new option tag goes here>


	    	</select>


3. Insert a new LABEL_THEME_SHORTNAME constant in oCLI's classes/client/Language.js file for the new theme. Shortname is once again a chosen short name for the theme. The new constant will need to be inserted once for every translation currently available in oCLI. Here's an example of a new language constant for the theme LABEL_THEME_SHORTNAME:


	LABEL_THEME_SHORTNAME:        "Really really long name",


If no translation can be provided for the long name of a theme in a given language, use English instead.

Back to Top


Attributes not yet supported in oED 


  • Gantt chart elements, thumbnail controls and calendars are not properly supported in oED
    • 

  • <SUBBLOCK>
    • 

  • alternatebackgroundcolor - Specify a background colour used for displaying alternating row colours in a subblock. 
    • 

  • linkmodelor, linkdatatypeor, linkaliasor - Specify two subblock links joined by an OR condition
    • 

  • tabindex - Specify a position in the tab order for a subblock
    • 


Back to Top