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 all Lycia clients which makes it the preferred way to add custom behaviors 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. For more details, refer to Loading plug-ins at runtime.

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, or LyciaTouch. 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. For more details, refer to Embedding LyciaWeb into a web site.

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 (please, do not confuse it with a WebComponent widget available for Lycia 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 or LyciaTouch unless you repackage) because the imported scripts (created with the help of emulation libraries such as http://www.polymer-project.org/) 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.

The first argument is the URL of the imported style. You can use any URL pattern, including qx:// <> to access files which are already part of the project.

The second argument is an optional value 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” string as its second parameter.

The third argument is an optional ID attribute 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 Lycia 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.

Example programs:

CVS server: client.querix.com

CVS repository: /presentation

User: client

Project: lyciaclient-extentions

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

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

It requires two parameters.

The first parameter is the 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.

The second parameter is optional: It 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 Lycia project in LyciaStudio:

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

Example programs:

CVS server: client.querix.com

CVS repository: /presentation

User: client

Project: lyciaclient-extentions

Embedding LyciaWeb Into a web site

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:

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 the following fields:

The embedding web page must include the following styles:

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

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

as well as the following 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: https://github.com/ebay/cors-filter.

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