You are here:

LyciaClient plug-ins

After custom JavaScript is loaded into a LyciaClient, it will be able to use JavaScript API for adding custom front end functions or for changing widget appearance by means of wrappers. New front end functions can be called by the 4GL program. LyciaClients employ jquery and jquery-ui libraries: So, they are loaded and can be reused in plug-in’s scripts and themes.

In MDI mode, children applications run in the invisible IFRAME context but their widgets are created in the visible parent container. The same browser window can hold 4GL windows from several applications. Windows from the same 4gl application are grouped by the qx-on-<ID> class and distinguished by their automatically generated identifiers. Each AUM element also has its ID attribute specified as <child application ID>-<element ID>. The number inside the application context can be obtained from the querix.childId variable and then employed by custom JavaScript functions for creating CSS selectors which can be used to refer to specific widgets.

From inside the child application’s context, refer to the querix.$ field to get

jquery objects for manipulating the parent’s DOM,
parent’s rangy library for manipulating text selections.

Custom front-end functions

Scripts imported by means of the scriptImport() front end function can register their own front end functions to be called latter in 4GL code. Front end function modules are simple JavaScript objects, the fields of the querix.plugins.frontCallModuleListglobal object (also accessible by frontCallModuleList).

Front end functions can be either synchronous or asynchronous. Asynchronous functions can be used to provide user interaction. In this case, control exits the function, and the front end function output is sent to server by a specified UI event (e.g., button click). Synchronous functions simply return output values using a simple JavaScript return statement. To make an asynchronous function, you call this.async() which will return another function to be called after the front end function is ready to provide output. The output value is supplied as an argument of the function returned by this.async().

UI properties can be extended by registering their names in querix.properties global object. Field name on the object sets the property name, and field value is a special object on which getters and setters can be performed.

setter is a simple function which receives the property value as its only argument.

getter is a more complex, asynchronous function which has 3 arguments:

a function to be called if the value is taken successfully and can be sent to the server (this value becomes the function’s argument),
a value received from the server,
a function to be called if any error occurs.

So, to apply the property, the custom code must call the function received as its first argument if not the one received as its third argument, but only one function at a time and only once.

CSS framework

CSS framework can use specific class names to attach style to any definite parts of a widget. LyciaClient also uses jquery-ui themes framework class names which means that themes generated or downloaded from jquery-ui themes roller can be applied immediately.

By default, LyciaClient converts any .qxtheme into CSS, so custom styles set by master and user themes can interfere with styles defined by custom CSS. You can disable .qxtheme styles by applying nativestyle Lycia class to a widget:

disabling .qxtheme for the entire application:

</DoStyleAction>

disabling .qxtheme for the descendants of the widget with specified ID:

<?xml version="1.0" encoding="utf-8"?>

</DoStyleAction>

</StyleSheet>

</DescendantFilter>

</StyleSheet>

</ElementIdFilter>

</StyleSheet>

</ElementFilter>

</StyleSheet>

Applying nativestyles and disabling .qxtheme can cause unexpected compilation and runtime effects beyond the scope of the Querix team.

Please, do not take this step unless you are a competent web-developer and have a considerable experience of such modifications.

Lycia widgets are expanded into the hierarchy of HTML tags. There is only one main tag which has qx-aum class. It can have ancestors and/or descendants generated by the same widget. The qx-o-aum class is used to mark the outer boundary of a widget; the qx-h-aum class is used to mark the header area separated from the content of some widgets such as TabPage.

Here are some predefined class names which you may find useful:

qx-identifier-XXX

qx-h-identifier-XXX

qx-o-identifier-XXX

are added to main, header, and outer HTML tags if their widgets have 4GL identifiers:

ext_4glIdentifier_01

ext_4glIdentifier_02

qx-c-XXX

qx-h-c-XXX

qx-o-c-XXX

are added to all Lycia classnames applied to widgets:

ext_4glClassName_01

ext_4glClassName_02

qx-aum-XXX

qx-c-aum-XXX

qx-h-aum-XXX

specify the type of a widget, provide names for the whole hierarchy of subclasses:

ext_aum_elementFilter_label_01

ext_aum_elementFilter_label_02

ext_aum_elementFilter_tabPage_01

ext_aum_elementFilter_window_01

ext_aum_h_elementFilter_tabPage_header_01

ext_aum_o_elementFilter_window_outer_01

qx-active

qx-h-active

qx-o-active

refer to enabled fields:

ext_active_inactive_01

ext_active_inactive_h_header_01

ext_active_inactive_o_header_01

ext_aum_elementFilter_tabPage_active_inactive_h_01

qx-inactive

qx-h-inactive

qx-o-inactive

refer to disabled fields:

ext_active_inactive_01

ext_active_inactive_h_header_01

ext_active_inactive_o_header_01

ext_aum_elementFilter_tabPage_active_inactive_h_01

qx-readonly

qx-h-readonly

qx-o-readonly

refer to read-only fields:

ext_aum_elementFilter_textfield_readonly_01

qx-on-XXX

defines the integer ID for every child application in the MDI container

Some HTML development tools allow using other classnames as well. However, we do not recommend you doing this: The names may be changed in later versions. We also do not recommend you loading .css to the applications which will be used only as children in the MDI mode because their processing will take operation time but will not influence their appearance.

JavaSctipt API

There is a small subset of stable API functions which can be used by plug-ins. Users can use browser’s developer tools reverse engineer the meaning of other functions; however, we do not recommend you doing this as the interface may be changed in later versions.

Stable API functions are defined in the querix.plugins.api object.

querix.plugins.api.setData(widget, value) - sets the value of the widget to be sent to the server at the next update
querix.plugins.api.writeConsole(text) - writes the text to the console
querix.plugins.api.getOuter(widget) - returns the outer boundary of the widget
querix.plugins.api.getHeader(widget) - returns the header tag of the widget
querix.plugins.api.getUIWidget(widget) - returns the tag which was used to creating a jquery-ui widget
querix.plugins.api.sendAction(name) - sends the action name to the server which can be handled by the ON ACTION name block
querix.plugins.api.leaveFocus(widget) - simulates that the focus leaves the widget
querix.plugins.api.getType(widget) - returns the type of the widget
querix.plugins.api.getWindow(widget) - returns the HTML DOM window object for the element (for LyciaDesktop, it is the native window where the element is displayed). The window object will contain the $ field to refer to the jquery library loaded into the context of the native window
querix.plugins.api.topWindow - returns the jquery element point to the currently focused window
querix.plugins.api.go - starts the framework which will be called in order to embed applications into any other web site, but not to be used for loading plug-ins at runtime

Widget argument in these functions can be either DOM elements or CSS selectors.

Lycia front-end functions

LyciaClient has a predefined set of front end functions in the HTML5 module:

scriptImport()	imports script files by URL the arguments: URL (qx:// <> URL pattern can be used) optional value nowait specifying whether the function should exit immediately without waiting for the successful script uploading
styleImport()	imports CSS styles by URL the arguments: URL (qx:// <> URL pattern can be used) optional value copy specifying whether the imported style should be copied to native windows in LyciaDesktop optional identifier to be used as ID attribute
htmlImport()	imports HTML5 WebComponents a new experimental HTML importing facility currently not supported by browsers, so it is unlikely that it will work properly unless some simulation libraries are loaded
fileinfo	returns size, MIME type, and time of previous modification for any file specified as an argument for LyciaWeb, will work only if there is a TextField in an .fm2 form with the FileUpload class
eval	executes java scripts provided as an argument can be either synchronous or asynchronous, similar to front end functions
getLocalStorage()	returns values stored in the HTML5 local storage by the name specified as an argument
setLocalStorage()	sets the value specified as its second argument to the value of the HTML5 local storage by the key specified as its first argument

Wrappers

Wrappers are high level tools which can be used to extend clients. You can employ a wrapper so that to adjust or completely change the default rendering of the widget.

Wrapper can be set

for a specific element from an .fm2 form,
for a set of elements via a .qxtheme file,
for a set of elements from a 4GL program using abstract model manipulation functions.

Wrapper field has two subfields, namely Name and Parameter. Name corresponds to the field name in the querix.plugins.wrapper global object, and Parameter is any string to be treated by the wrapper in a certain predefined way (e.g., a simple string or integer or JSON expression for complex parameters). Wrapper names are supposed to be case insensitive so wrapper developers usually use only lower case letters to name them.

Wrappers are registered by means of scriptImport() or styleImport() (if they have any dependencies like CSS or JavaScript files).

Wrappers are objects with these fields:

wrap

is called when the wrapper applied to a widget, this may happen before the widget is created because of some property change, e.g. the widget is selected and there is some wrapper for the Selected pseudo-class.

Receives the widget DOM element as its first argument and Wrapper.Parameter as the second one.

Returns wrapper handler objects which are used to communicate with the LyciaClient framework. It may also return NULL in cases when the wrapper does not need to perform any further actions on the wrapped element.

unwrap

methods to be called when a widget is deleted or another wrapper is attached.

Cleans all classes and additional tags created by the wrap method.

Is similar to the remove method used in wrapper handler objects but is useful if the wrapper creates no handlers.

Basic methods used to manipulate handler objects are:

attach	is called before attaching the element to DOM tree. When returns false, the framework will perform no default actions. Takes the DOM element where the other element will be attached as its first argument.
prop(name, value)	signals that the property value changed. When returns false, the default action on the property will be suppressed. name is a dollar-separated string specifying the path to the property in the abstract model (e.g., MinSize$Height for minimal height).
detach	is called before detaching the element from DOM tree
remove	is called before removing the element
focus / blur	is called than the element receives or loses 4gl focus at runtime
noHeavyInit	suppresses any heavy initialization actions performed by LyciaClient API