Overview
Extending widely the functionality of a product just within the product team is a tough task. Allowing developers all over the world to contribute to the project using their skills and bright ideas gives a big boost in the product features variety and a huge benefit for the product users.

This is the reason our team opens the SiteKreator platform for adding more and more functionality and excitement to the product.

Users are allowed to choose from a catalog of applications and install any of them on their site. The applications may look like normal SiteKreator elements added from the "Add Content" menu, or be as items in the Control Panel. The applications can use the SiteKreator DB API to store data they need to process, the SiteKreator Object API to store the SiteKreator object properties and SK URL API to create SEO friendly URLs that suit the applications' needs.

Application Engine
Management Interface
Applications are managed through the Applications management console in Control Panel. The console runs in two different modes depending on if you are a developer or an end user. As this documentation is about developers, it will focus only on the developer's view.

Applications can be installed, de-installed and updated by a developer. Applications can exist in a sandbox or in the official catalog. They can't be installed directly in the catalog, but first should be installed in the sandbox and then published. However updating of an application can happen directly in the catalog (as well as in the sandbox obviously).

Every developer can update or deinstall their own application only. The application is tagged with the ownership of the account where it was installed from.

The developer usually starts with a JSON file ready to be installed as a Sandbox application. For this purpose one should open the Applications dialog and click on the "Get More Applications".


Then at the bottom of the page there is an "Install Other Application" link.


When clicking it, it displays the dialog so that the URL can be pasted here and installed in your sandbox.


The developer can enter either an Access Code or a URL to the JSON file. The Access Code is used for installing applications that are not in the catalog.

In this case the developer wants to install an application in the sandbox by a provided URL. The applications in sandbox mode are the first in the list of installed applications and have an appropriate icon.



Now the developer can start testing the code of the application according to its set description. Тhe description can be changed at any time by pressing the "Update" button when there is a prompt for setting a URL.

Application Structure
An application is installed and upgraded by a reference to its application description which is a file in a JSON format where all the application meta data and integration points are described. The meta information is mainly for presentation purposes (name, description, price, version, etc...) while the integration points serve as the entry points to the application's business logic (how it behaves when a certain event X occurs).

The integration points are called bindings. There are different types of bindings, but all of them have something in common — they refer to a chunk of code which is used at certain cases. These chunks of code are URLs which are requested when needed. The response from the URL is what is used as a result from the code reference. As these code references are dynamic and they may need information about the environment of execution. This information is passed to the URL using a POST HTTP request.

If the application's code files are stored on a server which allows server-side processing the passing of the parameters is definitely a better option for processing. However there is an option for client-side initialization of the code for files that reside on a static server. This means the code is fetched from the server (the same way with a POST request passing the environment information) and after it's displayed on the page an initialization code line is executed that also contains the environmental information. This way the code can do its business logic entirely client-side. Client-side processing is not recommended when working with sensitive data.

Application Description

The application description (AD) is a JSON that has the following structure:

• framework_version — application framework version (currently 1.0)
• id (int) — unique application ID
  
• name (string) — application name
• description (string) — short application description
• icon (url) — the 96x96 icon for application catalog.
• tags (array of strings) — tags the application can be categorized in
• version (string) — a freely used versioning format, where a simple string compare can determine which version is newer.
• authors (array of strings) — list of application authors
• site (url) — The URL of application site
• price (int) — the application price (0 means free)
• currency (string) — the currency of the price (required if price > 0)
• availability (string) — one of the following: "public", "reseller", "private" which mean:
• public — the application will be publicly visible
• reseller-only — the application will be visible only by the users of the reseller who owns the website of the developer account. However users from another resellers can install the application if they supply an Access Code.
  
• private — the application is not visible in the catalog, but can be installed via an Access Code.
  

• bindings (hash) — defines how the application is bound within the user site. Each of the binding has a name (the key in the hash) and an array of definitions for this binding (the value of the hash). Here are the available bindings:
  • add_content — an array of hashes, each of them with the following structure:
    • id (string) — a string to identify that element. This "id" should be the same within current application's versions, because element instances that are already added refer to it
    • caption (string) — text for the item in Add Content
    • icon (url) — icon for the item in Add Content (50x50 icon); if not the exact dimensions, will be stretched inside the browser
    • properties_add — this is the definition of the application binding when the property sheet for adding an element is displayed. It's not cached. It has the following members:
      • source (url) — URL to the source code. The URL may contain HTTP GET parameters too (e.g. "http://myserver.com/app/properties.html?mode=add")
      • init (string) — constructor name (optional) — if specified, the response from the "source" will be suffixed with a JavaScript chunk such as "new ()", where is the "init" specified herе. The "init" is optional in all other bindings while the "source" is mandatory if the binding exists in the JSON.
      • display_options (hash) —  a hash used for the way the popup window will be displayed. May contain "width" or "height" keys or both, e.g.
        { "width": "640", "height": "480" }
        
    • properties_edit — used when displaying the property sheet for editing an existing application element instance. It's not cached.
      • source (url)
      • init (string) — again optional as in properties_add
      • display_options — as in properties_add
        
    • display_admin
      • source (url)
      • init (string) — optional
        
      • cache (seconds) — if 0, the chunk will not be cached. If not specified it will be taken as 0 in admin view
      • cache_debug (seconds) — used for sandbox applications
      • display_options — as in properties_add
    • display_user
      • source (url)
      • init (string)
      • cache (seconds) — if not specified will be set for 24 * 60 * 60 seconds
      • cache_debug (seconds) — used for sandbox applications
      • display_options — as in properties_add
  • control_panel — an array of hashes, just like add_content. These items are those added in Control Panel. Each of the hashes can have the following structure:
    • id (string) — unique ID within the scope of the control_panel items
    • caption (string) — the caption of the item in Control Panel
    • source (url)
    • init (string)
    • display_options — as in properties_add
  • lifecycle — a hash structure. It defines the code that will be executed during the application management within the Control Panel > Applications window. During that phase the application may store data in its own configuration pool (see the set/getConfiguration methods). This configuration is free format and is available in the environmental information being passed to each one of the bindings.
    • install — defines the code that will be executed when the application is installed
      • source (url)
      • init (string)
    • deinstall — defines the code executed when an application is removed from the user applications list
      • source (url)
      • init (string)
    • update — executed when a sandbox application is updated from Control Panel > Applications or when a catalog application is updated and the user who uses the application logs in and the system detects there is a new version. NOTE: If the version in the new AD is not changed there will be no "update" execution when the user logs in.
      • source (url)
      • init (string)
  • pages — a hash structure. It defines the references that are executed on every page from the site
    • header_admin — put in the header of every page in admin view
      • source (url)
      • init (string)
    • footer_admin — put in the footer of every page in admin view
      • source (url)
      • init (string)
    • header_user — goes in the header of every page in user view
      • source (url)
      • init (string)
    • footer_user — displayed in the footer of every page in user view
      • source (url)
      • init (string)
  • cron — an array of hashes just like add_content. These are the code snippets executed on a regular basis.
    • [TODO] Not implemented yet
  • dashboard [TODO] Not implemented yet
    

Code Execution
Environment
All client-side JavaScript code is executed in an environment that has MooTools installed.

The source code that's displayed within a popup (properties_*, control_panel) has libraries that help the applications mimic the standard SiteKreator interface. The properties_* code follow the property sheets guidelines while the control_panel items do not have a mandatory UI format. However if you want to stay up-to-date with the SiteKreator standard interface use SiteKreator Application Framework UI documentation.

Flow

The basic execution flow for an installed application that happens to be at a certain integration point is:

1. We are in the context of application "Application"at integration point X
   
2. The action Action is taking place (where Action can be properties_add, properties_edit, control panel item clicking, etc...)
3. If the AD contains a code to execute (at least the "source" is specified)
   • Compose a URL from the "source" and append parameters with the environment information
   • Request it with an HTTP POST method
   • Output the response
   • If there's an "init" specified generate a JavaScript code such as:
     
     
   • The output of all code references (together with the SiteKreator framework code) may be cached. If so, the code reference source is not requested unless the cache of this chunk is purged

Environment Information
Code chunks are initialized with parameters passed as POST requests to the code URL and (if "init" method supplied) with a JavaScript initialization code. These parameters should allow the applications to

• Display itself on a proper place on the page
• Read its properties
• Use the SiteKreator API which needs an authentication token, user ID, node ID
• Use the current session ID (usable mainly for actions in admin mode)

This information will be passed both to the URL to the source code and in the JavaScript initialization. The difference is that in the POST request the parameters below will have an extra leading underscore (e.g. instead of "placeholder" it will be "_placeholder") and all the current URL parameters will be passed.

• placeholder (string) — the ID of the DOM element where the application can put extra content in
• properties — a serialized JSON with a key-value hash of properties of the element
• configuration — a serialized JSON with the configuration that may have been set during the installation of the application or its last update
  
• session_id (string)
• node_id (integer)
• user_id (integer)

A URL that we use for a POST would have the following parameters (a GET request example is used for being more descriptive):

http://mydomain.com/app/1.0/properties_add.html?_placeholder=app12345&_node_id=12345&_user_id=54321&_session_id=1234567890&_properties=%7B%22name%22%3A%22CEO%20Smith%22%7D

When the "init" method is supplied these parameters are passed as a hash:

First Name       default_value="John" validate_as="not_empty">    class="collapsed">    Options              Last Name

There are FIELDSETs each containing a field that has a default value. The reason the fields are separated into two FIELDSETs is to display the ability to create collapsible sections of the property sheet. The default values are used only when adding an element. In this case they are "John" for the first name and "Smith" for the last name. The fields are named in a special way — property__FirstName and property__LastName. When opening the element's properties the framework will look for fields with a property__ prefix and will set the stored values in them. The first name is validated when the Add button is clicked and the type of validation is "not_empty" which means there will be an error if the value is empty (for more validations refer to the property sheets documentation).

There is a line of code that initializes the framework for property sheets using the MooTools syntax:

   $( window ).addEvent( 'load', function() { new SK.UI.Properties( ).init(); } );

In general there's no particular need for having different property sheet files for adding an updating elements, but that's made for special cases where it's easier for the developer to have them separated.

If the property sheet simply accepts values and stores them as element properties — this is the way to do it. For more complex property sheets you can refer to the property sheet framework documentation.

After the element is added you will see its output on the page just like that:

If you publish the page you will see the same kind of text, but with "(user)" in the parentheses. The code that was executed in administrator mode was display_admin.html, while in the published view it's display_user.html. Both chunks are similar. Here's the display_admin.html:

Looks hairy at first sight, but it's very simple. The "init" for "display_admin" was set to be "SK__HelloWorld.DisplayAdmin". For this purpose the code defines a JavaScript hash SK__HelloWorld which has a key "DisplayAdmin". The value of that key is the definition of a class instance using MooTools. The class has just a constructor which accepts the environmental properties previously discussed. In this case we want to display the properties. They are inside "options.properties" where the "options" is passed to the constructor. The names of the properties are the same defined in properties.html but without the property__ prefix. The code assembles a string and displays it in the placeholder referred by "options.placeholder".

A similar code is used for the display_user binding.

Next you can see is the Control Panel which contains one extra item which was defined in the Hello World application description file:

When clicking on the "Hello World Configuration" item a popup is opened that displays the result from the "configuration.html" code execution:

This is similar to the properties.html as interface, because it uses the framework for building standard system buttons. Everything else is left to the creativity and business purposes of the developer. In this case we just display a text in the middle of the screen and a "Close" button that closes the popup. The code configuration.html obeys the rules of the SiteKreator Application Framework UI documentation:

Hello World Configuration!

The "init" method in this case is SK__HelloWorld.Configuration. It inherits the SK.App.Popup  which is used for building the "Close" button at the bottom of the page.

Here one may want to provide interface for storing some site-wide configuration in a SiteKreator Database using the Database API.

That's the whole story about this simple application. Be sure to check the other application examples at the bottom of the page.