FrameTrail API Docs

FrameTrail is a distributed application with a server part and several clients.

For the server, every compatible HTTP server can be used that supports PHP.

The clients are single-page applications, which are composed of javascript modules. They all access the common server.

Fork the project at Github | Installation | Contributing

File Structure

The top-level of the directory in a production environment contains the following special directories:

  • _data: Contains all the user-generated content. It is managed by the server, which needs to have write permission for this directory. All data is stored in files, not in a database.
  • _lib: Contains all the external libraries.
  • _server: Contains all the server-side logic of the app (which is used solely via AJAX requests)
  • _shared: This directory contains all javascript code, css definitions and other resources, which are shared between the different client apps.

The other top-level directories are the several client apps, which work with the server. They all have one index.html in it.

  • player is the actual player (and editor) app.
  • projectmanager let’s you the manage the different projects of the server’s environment.
  • resourcemanager is a stand-alone client app for managing resource files.

The FrameTrail Object

The client apps all use the FrameTrail core, placed in _shared/frametrail-core/frametrail-core.js.

When you are you new developer for FrameTrail, have a look at the sample files in the same directory, and make sure you examine the global object FrameTrail in the browser’s console.


“Modules” are the basic building blocks of every FrameTrail client app

Please have a look at the sample file _shared/frametrail-core/_templateModule.js.

Modules are defined with FrameTrail.defineModule('myModuleName', aFunction).

The function contains all the private variables and private function definitions necessary for the module. It serves as a closuring environment for all the modules local code and data.

The module is then initialized with FrameTrail.initModule('myModuleName'), which simply executes the function. The module function should return a “public interface object”, which makes the private functions accessible to the outside, or defines getter/setter functions for accessing the private variables.

The module’s public interface can then be used from other modules with FrameTrail.module('myModuleName').

A module can be unloaded with FrameTrail.unloadModule('myModuleName') which frees the memory.


“Types” in FrameTrail are a simple layer on top of javascript’s native prototype system. They allow for simple definitions of types of objects, which can then be created from FrameTrail.

Please have a look at the sample file _shared/frametrail-core/_templateType.js.

A type is defined with FrameTrail.defineType( 'MyTypeName', // necessary 'NameOfParentType', // optional (inheritance feature) function(){}, // contructor function {} // prototype object );

A type can be instantiated with FrameTrail.createObject('MyTypeName', [arguments to constructor ...] ).

In all other aspects, there are no peculiarities other than native javascript’s object-oriented features.

Global State

The FrameTrail core provides a simple way, to hold global states in one “safe” place, which can be accessed by all modules. All data is stored as key-value pairs in one object managed by FrameTrail.

This global state also provides a simple event management system. Whenever a change of a global state variable occurs, FrameTrail informs all those modules, which have declared interest in that variable in their public interface object, by calling their respective handler function.

To read or write global state, simply use FrameTrail.getState('nameOfGlobalVar') and FrameTrail.changeState('nameOfGlobalVar', newValue) or FrameTrail.changeState({ 'nameOfGlobalVar1': newValue1, 'nameOfGlobalVar2': newValue2 })

Any module can “listen” to changes of global state variables by exporting in its public interface object a onChange property, which is an object mapping the respective global variable names to the local handler function.

The local handler function will get two arguments, the new and the old value of the global state variable.

Please have a look at the sample file _shared/frametrail-core/_templateModule.js for detailed use.

Starting a client app

All the client apps are started (after “document ready”) with one call to

FrameTrail.start('startModuleName', { initial global state object })