webCOMAND Framework

The webCOMAND Framework builds on COMAND Repositories, the PHP API and Web Services to provide a foundation for developers to create Apps, Components and Themes, and customize webCOMAND with Hooks and Workflows.

It is important to understand the following concepts when working with the framework.

Components
Messages
Hooks
Workflows

Components

webCOMAND and webCOMAND apps are composed of a hierarchy of components, similar to how a web page is composed of a hierarchy of document objects. Each component is typically responsible for the look and function of a region of the user interface.

webCOMAND - The top of the component hierarchy. No visible UI, but manages all components.
- Header - User interface to key features (dashboard, apps, profile) and content (search/query).
- App - A web application that can be easily discovered, purchased, installed and launched.
  - Panel - A component that occupies a rectangular region within an app layout.
    - Components - Reusable objects that represent a specific user interface feature.

Additoinally, the following components may be utlized at any level in the hierarchy.

Theme - Set of styles (CSS) and components to use within webCOMAND, a panel or app.

Component Types

Each type of component listed above is represented by a corresponding content type that extends the Component content type. The Component content type has the following fields, which are inherited by all component types and used to list, install, load and instantiate a component.

Title - Name of the component.
Summary - Short description of the component.
Icon - Image to represent the component.
Package - Package that contains objects used to install and/or use the component.
Class Name - Path within the package to the primary component class.

For more information, see the Component Content Type, and the more specific component content types that extend it.

Messages

Components use messages to communicate with each other and respond to changes in the webCOMAND environment. A component can subscribe to the types of messages it is interested in listening for, and it can broadcast messages to components that are listening.

Messages can originate from:

User Interaction - A component can send a message in response to user interaction. For example, when a user clicks/taps a button component, it can send a message to other components listening for type of message it will send.
Component Events - Components can iisten for events triggered by other components. For example, a timer component might send a message after it has counted down to zero.
Repository Changes - Components interested in changes in a repository can listen for changes anywhere in the repository, or for a subset of objects and events. For example, a component that displays a collection of objects may want to listen for changes to the collection and all objects in it, to update the interface in reponse to changes.
Repository Events - Components can iisten for scheduled events and triggered events that may be defined in the repository. For example, an object may perform a task that does not neccessarily update a repository object, but instead broadcasts a message.

Message Path

The webCOMAND component is responsible for monitoring the repository for changes and then broadcasting the corresponding messages down the component hierarchy. Components can prevent the message from continuing down to its sub-components by returning false in response to the message. Otherwise the message will continue down the hierarchy.

When webCOMAND is launched in a web browser, it tries to maintain a persistent connection to the server to efficiently monitor for repository changes and events with minimum lag. When possible, a persistent connection remains opened with the server as long as the webCOMAND interface remains open in the browser (no web page / browser reload occurs). As events occur on the server side, they are streamed to the webCOMAND component, which can immediate broadcasts them to listening client-side components. If a persistent connection is lost, the framework will try to re-establish it. If a persistent connection can not be made at all for some reason, the framework will fall back to periodic polling via ajax requests (which may indirectly utilize an HTTP persistant connection). The webCOMAND component may also chose to close the connection when appropriate (ie. no user activity), to conserve server resources, and then poll or re-establish the connection later.

Hooks

Content Type Methods customize webCOMAND's internal processes.

webCOMAND checks Content Types for the existence of certain methods when actions are performed in the user interface. For example, when a user saves a content record, the Validate method of the content record's content type is called to ensure the content record is valid, if it exists. If the content record is valid, the Save method is called next, if it exists.

webCOMAND processes, such as Validate and Save, can be customized with content type methods. Methods with a recognized identifier will be called by webCOMAND in place of its standard processes. For example, if a Validate method is defined for the Image content type, it will be called in place of webCOMAND's standard validation process when a user saves an Image content record.

webCOMAND-specific Methods

In addition, the COMAND API has Recognized Content Type Methods as well.

Workflows (v4)

Workflows and their individual steps can be developed to coordinate and automate business processes.

Workflow
Workflow Components