IFRAME API¶

Using the IFRAME API you can integrate own content seamlessly into LiveConfig and thus extend its features. This is done by embedding content from an external URL into the LiveConfig user interface using an <IFRAME> tag. The external page gets informations about the logged-in user via CGI variables.

Creating “Custom Links”¶

Log in to LiveConfig and go to Administration -> LiveConfig -> Custom Links. The links created here will be visible to all users of the same administration level as well as all own customers (but not to the customers of resellers!).

Managing sections

All custom links are managed in sections (which equals the sections in the navigation menu). So you need to create at least one section to use it for custom links. The options for a section are:

Title: the title of the new section (displayed in the navigation menu)
URI: the URI path for this section (only characters, decimals, dot, dash and underscore allowed). The complete URL to a custom link is built from: /liveconfig/ext/ + <section URI> + / + <link URI>.

Managing links

The options for custom links are:

Section: section where this link should be displayed
Icon: icon to be displayed in the navigation menu
Title: title of the link (displayed in the navigation menu)
URI: URI path for this link (see above)
Sort Order: for ordering multiple links within the same section
Destination URL: the complete URL which will be opened within an <IFRAME>. This has to be a HTTPS URL (SSL), otherwise a browser won’t open it for security reasons (“mixed content”). This URL also may not contain and CGI parameters, because LiveConfig automatically appends some parameters (see next section).
Password: the password for the checksum when calling the destination URL (see next section).

Note

It is not possible to provide direct links to external content within the navigation menu (like e.g. to webmail or phpMyAdmin) for usability and for security reasons. If you want to link to external content, provide a separate <IFRAME> page containing these links (see examples).

Creating own content¶

When clicking on a custom link page, LiveConfig creates an <IFRAME> which contains the configured destination URL. This IFRAME has a width of 100%, and its height is scaled by JavaScript to the height of the embedded content - so usually no separate scrollbar should appear.

Example code can be found at https://github.com/LiveConfig/iframe-api.

There are nearly no limits when designing the pages to be embedded. Only a few things have to be considered:

include lc-iframe.css and lc-iframe.js

To automatically adjust the size of the IFRAME, these two resources need to be included directly from the LiveConfig server.
CGI parameters sid, ts and chk

LiveConfig automatically adds the CGI parameters sid (session ID of the LiveConfig user), ts (current time stamp) and chk (checksum) to the destination address to be called. With the checksum, manipulations in the CGI parameters can be quickly recognized. With the help of the session ID, a call to the REST API can be used to check whether the user is currently still logged in to LiveConfig - additional information is also returned, including the login name, the full name and a list of all assigned accounts.

We provide a PHP include file (lc-api.inc.php) which cares for the session validation. All you need is to prepare an API key (read-only access is sufficient).

If you use your own input forms within the embedded page, it is best to pass on these CGI parameters so that you can check the validity of the session at every processing step. In more complex applications, you can also create your own PHP session for this visitor and store the CGI parameters mentioned as session data.

For a complete example please take a look at demo.php in the example package (see above).