Main /


Scripts must, after initializing (loading preAmble.php), invoke an App class and use it.
The context for an App is the type (vertex/edge/planar) and the mode (list/view/edit/count)

An application declares a Canvas to work in.

  $app  = new boxaryApp($canvas, $appType, $mode);     // create App of type vertex/edge/planar in $mode list/view/edit/count

A Canvas will contain or reference all objects the application is using. Distinguished are objects that work with external data, aka database data, and objects that will use the derived structure of the external data. A Canvas can compute these structures.

A Capsule is an incomplete specification of the external storage, aka database. This specification will limit itself to those data entities that the application is about. Multiple capsules will merge themselves. Capsule is loaded into a Canvas, either by script, either by config.

A Capsule defines the vertices and edges of the graph to be processed. It associates primary keys and names foreign keys. It computes an adjacency list and assigns candidate keys to reference values. Some capsules refer to metadata on attributes and properties. When defining properties of vertex/edge, names are assigned and mapped to the column names. The application works with these names, NOT with the real column names.

An application retrieves a Face to work with. Important is here, that the App needs data (a vertex/edge/planar) and a template to be constructed. This template is identified by requestedApp, which is simply an external configuration and/or specification of the processing needed to transform data into the response.

  $myFace = $app->assignPropertySet($requestedPlanar, $requestedApp);         // load planar by name and construct, returns planarFace

Assigning a Face implies specification of the layout for rendering. Such layout contains named slots for rendered content. While processing, any rendered component is put into or added to a specifically named slot. A Face loads a configuration of templates to use to render the retrieved data.
There are different versions of a Face for a single vertex, a single edge, and a variable Planar. A Face will handle list, view, edit and count modes.

After declaring a canvas, loading a capsule and having a face available, the application sets the boundary conditions for a query in a Criteria.
Mostly done thru parameters the visitor exchanged in a POST - or GET - HTTP request.

  $id     = $app->introSpection($id, $tk1, $tk2);                             // check id and secondary keys tk1, tk2; create criteria

A Criteria will accept a given-when-then-pattern, analyses it, loads the needed vertices/edges, and creates a basic SQL statement. There are different versions of a Criteria for a single vertex, a single edge, and a variable Planar. To handle the SQL, Criteria makes use of a Command (a simple SQL command), a Query (complex SQL statement). Since the application uses local names, a SqlToken is used to translate these local names into the external database name.

A Canvas plays an important role in retrieving the external data, manipulating their structures, and rendering the result in a Page or Response. In order to do so, it attaches a Lexicon and uses Semantics.
A Lexicon contains metadata on Properties, Attributes, and Slots. It computes items from properties and attributes and links to Slots (rendering functions) for these items. Rendering takes place in a coin minting metaphor: assign a Shape, create a Stamp, and then Print an occurrence.
Semantics is a general utility that implements various and complex graph operations.

A Face contains the rendering of Groves. This rendering acts as an application within the application, with 'own' Criteria, but within the very same Canvas

  if (!empty($options['groves'])) {
    $models = $app->constructTree($id);

The application executes the App based on the mode. This executes the Criteria and transforms the retrieved data using the Face.

  switch ($mode) {
    case 'edit' : $app->appEdit($id, $tk1, $tk2); break;
    case 'view' : $app->appView($id, $tk1, $tk2); break;
    case 'list' : $app->appList($id, $tk1, $tk2); break;
    case ''     : break;
    default     : leavenow("no $mode functionality here"); break;

Though the execution of the Criteria is straight forward, the transformation of the retrieved data is not. The workhorse here is Face and Lexicon. Addition of Groves in the final layout is complex.

Rendering of content uses templates. These templates come in various forms; a Snippet that is able to replace text in (multiline) strings, a Templet that adds the inclusion of external files, a Template that adds the use of simple logic, and a Stencil that adds the use of themes.

The application orders to render it all.


The Face will collect all layout in the configured order and launches the process of autoTag replacement. After that, the proxied portal will assemble a Response or Page.