Loading LyciaClient plug-ins

Custom styles and scripts can be included either

• by altering the web page by a 4gl program with the help of front end function calls, or
• by embedding a LyciaClient into a web page where styles and scripts are imported using <link>, <script>, or <style> HTML tags.

The first option - namely using 4GL code to alter web pages - will work for both LyciaWeb and LyciaDesktop which makes it the preferred way to add custom behavior and styles. Special front end functions can be used to embed JavaScipts and CSS styles at runtime, and scripts and styles can use Lycia CSS classes and API functions to alter appearance and behavior of any widget.

The second option - namely embedding a LyciaClient into some other web page - currently works only for LyciaWeb, and may be helpful if you embed a 4GL application into a web site, where web pages are generated by other technologies, e.g. JSP, ASP.NET, etc. It cannot be used to change styles and behavior of any application when run by LyciaDesktop. Initial templates are stored in the package, so to change it, you need to repackage it. At the moment, Querix doesn’t provide tools for repackaging so, please, contact the Querix support team if you need it.

Loading plug-ins at runtime

Any custom script or style can be added to LyciaClient by calling styleImport and scriptImport front end functions of the HTML5 module.

There is a third option which can be used to load HTML5 WebComponents - namely the htmlImport function (do not confuse it with a WebComponent widget available for .fm2 forms) - but we do not recommend you to use it because of several reasons:

• it employs a new HTML5 import feature which isn’t fully supported by browsers yet;
• it is available only for LyciaWeb (not LyciaDesktop unless you repackage) because the imported scripts (created with the help of emulation libraries such as this) should advance any other scripts;
• it reduces the performance significantly.

styleImport front-end function is called to import styles:

CALL ui.Interface.frontcall("html5", "styleImport", ["<arg1>", "<arg2>","<arg3>"], [])

It requires three arguments:

• URL of the imported style. You can use any URL pattern, including qx://<> to access files which are already part of the project.
• optional copy which specifies whether the imported style must be copied to native window context for LyciaDesktop. Each native window of LyciaDesktop runs in separate browser context. Widgets displayed in these native windows are out of scope of CSS style sheets loaded into the root context where LyciaDesktop is executed. So, e.g., to tell LyciaDesktop to copy theme to the window context, you must specify copy as its second parameter.
• optional ID set for the imported style. It may be referred to by other functions: when switching themes or by removing old tags and adding new ones, etc.

E.g., to include a CSS added as a resource to a 4gl project in LyciaStudio:

CALL ui.Interface.frontcall("html5", "styleImport", ["qx://application/extensions/messages.css", "copy"], [])

To include a jquery-ui ui-lightness theme from CDN:

CALL ui.Interface.frontcall("html5", "styleImport", ["https://code.jquery.com/ui/1.11.3/themes/ui-lightness/jquery-ui.css", "copy", "custom-theme"], [])

This style will be copied to all native windows, and the ID attribute for the imported style will be set to custom-theme. Later this id can be used to refer to the imported style, e.g., to removing it with the help of the eval function of the HTML5 module or any JavaScript plug-in function.

 

scriptImport front-end function is called to import script files:

CALL ui.Interface.frontcall("html5", "scriptImport", ["<arg1>", "<arg2>"], [])

It requires two parameters:

• URL of the imported script. Similar to styleImport, you can use any URL pattern, including qx://<> to access files which are part of LyciaStudio project.
• optional nowait that defines whether it is necessary to wait for the successful script uploading. By default, the function waits till the file is loaded and will freeze if it is not loaded because of any error or wrong URL. If nowait is specified as the second parameter, the front end function will exit immediately without waiting. However, it will be impossible to immediately use the imported script, and you will need to add certain functionality to the scripts in order to handle loading events or errors. In most cases, where will be no need to call the function without waiting, especially when the reliable script file is uploaded from your project. If there are any networking issues, the LyciaClient will fail anyway.

E.g., to include a CSS added as a resource to a 4gl project in LyciaStudio:

CALL ui.Interface.frontcall("html5", "scriptImport", ["qx://application/extensions/custom.js"], [])

Embedding LyciaWeb into a website

The simplest to embed LyciaWeb into a web site is to run it inside <IFRAME>. However, in this case, embedded applications will not inherit styles from the parent web page.

If you need your 4GL application to have similar appearance to any other web site content, you can use another embedding option: specify the application to be run, import 2 styles and 2 scripts from the LyciaWeb servlet, and execute Lycia API functions to running the application.

The web page which will hold a LyciaWeb application, must have HTML tags with specific ids, namely:

qx-container-toolbars	specifies there to place toolbars of the container application
qx-container-menu qx-menu-inner	specify there to place menus of the container application: the second tag must be descendant to the first one in the DOM tree
qx-container qx-container-body	attaches the container application and child applications
qx-container-status-bar	specifies there to output status bar of the container application

To specify the application which will be run inside the web page, you must define the JavaScript global variable lwDetails before including the LyciaWeb scripts. This must be an object containing these fields:

i	string defining the application name
c	command line
s	URL of the optional server to connect to (by default, the URL of the embedding website will be used)
u	optional user name
p	optional password

The embedding web page must include these styles:

<LyciaWeb servlet URL>/css/libs.min.css

<LyciaWeb servlet URL>/css/lyciaweb.min.css

as well as these scripts (they must be included after specifying the 4GL program in lwDetails):

<LyciaWeb servlet URL>/js/libs.min.js

<LyciaWeb servlet URL>/js/lyciaweb.min.js

After the necessary styles and script are included, and the application runs, it is attached to the web page by calling:

<script> querix.plugins.api.go("<LyciaWeb servlet URL"); </script>

If the embedded 4gl application and the embedding web site run on the same Java web server, LyciaWeb can be deployed by /LyciaWeb/ instead of <LyciaWeb servlet URL>. This is the easiest configuration.

If the embedded 4gl application and the embedding web site run on different servers, the default configuration - /LyciaWeb/ - will fail to run the application the web site and LyciaWeb servlet will have different origins: Security facilities of the browser will prohibit LyciaWeb from running. In this case, web site administrators will be required to add Cross-Origin Request Sharing (CORS) headers into HTTP responses. E.g., here is a Java Servlet Filter which can be used for web sites running on Java web containers.

With the embedding done in a proper way, the web site scripts have the full access to LyciaWeb API, and its CSS style sheets will specify the appearance of all widgets in the embedded application.