webCOMAND Apps

webCOMAND Apps are web applications that provide features and functionality within webCOMAND.

The webCOMAND Framework, COMAND API, webCOMAND API, and Market provide a structured and streamlined approach to App development and distribution.

Basic App

Basic Apps don't need a user interface (UI). They may just do something and return a text or HTML result. For example, an App may just display the root object in a COMAND repository.

The diagram above shows the elements that need to be in place for an App to function. Each element can be created manually, or

Basic App

Need diagram of app with UI.

Discuss app with UI.

Layout & Panels

Apps typically utilize the standard layout with a central primary region surrounded by secondary regions. Each region can contain zero or more panels. A region will stack multiple panels vertically, dividing them equally or as needed. A region with no panels will not display or take up any space.

Minimum Region Width

The minimum region width is the narrowest width in pixels for a region to be usable. The minimum region width is determined based on the detected device and browser, but will never be less than 320 pixels wide. Some examples include:

• Earlier iPhones (up to 3GS) with a 320 pixel wide display use 320 pixels.
• Newer iPhones (4+) with a 640 pixel wide display use 640 pixels.
• Small desktop and tablet screens will typically use 320 pixels.
• Larger/wider desktop and tablet screens sometimes use more than 320 pixels.

Wide Layout

Wide Layout, as illustrated above, will be used when the browser width is large enough to display all visible Left, Center and Right regions at the minimum region width or wider. For example, if the minimum region width is 320 pixels and the Left, Center and Right regions are visible, Wide Layout will be used if the screen is at least 960 pixels wide. If the minimum region width is 320 pixels and only the Left and Center regions are visible, Wide Layout will be used if the screen is at least 640 pixels wide.

Narrow Layout

As the name suggests Narrow Layout is used for narrow browser windows and device screens. More specifically, Narrow Layout is used if the browser window is narrower than the width required for Wide Layout. If a browser window is resized, the user interface will automatically switch between Wide Layout and Narrow Layout as appropriate.

Narrow Layout uses most of the browser for the center region, with a vertical scroll if neccessary. The Top, Left, Right and Bottom regions are initially hidden. Subtle arrows at each screen edge are used to reveal the corresponding region (click, tap, drag or swipe). A subtle arrow in the reverse direction is used to hide a revealed region.

The Top region includes a condensed version of the webCOMAND Header. If the Top or Bottom region heights are shorter than the browser height, only a portion of the Center region will slide out, leaving the remaining portion visible and functional. Only one region can overlap the Center region at a time. Left and Right regions always utilize most of the browser.

Regions Stack Panel UIs

Each region within a layout can be assigned zero or more panels.

When multiple panels are assigned to a region in Wide Layout, they will be vertically stacked in the region, equally divided vertically to fill the region. If a panel can not be resized to an equal height, the remaining space will be divided equally between remaining panels, and so on. If the panels do not fit in the region vertically, the region can be scrolled (with a scroll bar or swipe).

When multiple panels are assigned to a region in Narrow Layout, they can be swiped up and down, with the Top and Bottom regions at the beginning and end. This is mildly confusing and less usable than a single panel in the center region, so it is generally discouraged in Narrow Layout.

Custom Layouts

The Wide and Narrow Layouts provide an intuitive and consistent interface for most apps. However, apps can define custom layouts as well. To define a custom layout, populate the Center region with a custom layout and the standard layout options will be disabled automatically, except the Top region will always include the webCOMAND header.

Responsive Regions

Each of the five regions may be sized from the minimum region width to infinity. The Left and Right regions will initially be the minimum region width, but in Wide Layout may be resized to utilize more of the screen, as long as the Center region remains the minimum region width or greater. The center region width will utilize whatever space is available between the Left and Right regions.

The interface should follow responisive web design principles. More specifically, each region should use a fluid grid that can be sized down to 320 pixels wide to handle the minimum supported width.

Create a New App

Create a new app with the follow the steps.

• Create App Folder - Create a new folder in the file system under the webCOMAND packages folder (comand_app/packages), which will contain all app software files. Give it a name unique to the developer and app in the form "com_domain_app_name", where:
  • "com_domain" is the domain or hostname owned by the developer, with its parts reversed. This ensures it is unique from other apps by other developers, and groups apps by developer.
  • "app" indicates this folder contains files for an app.
  • "name" is the app identifier, which is a file system safe version of the app title. It may contain underscores.
• Create "name.php" file - This is the main PHP class file based on the Sample App Class File.
  • Name it with the app identifier (identical to portion of folder name). For example, "name.php".
  • The class should be assigned a unique namespace, typically based on the package folder name. For example:

    namespace com_webcomand_app_console;

  • The class declaration must implement the Launchable interface, which requires a constructor that will receive the webCOMAND Framework and App objects used to instantiate the application, as well as a launch method that will be called to launch it. This is typically done by extending com_webcomand_app_standard_app. For example:

    class name extends \com_webcomand\standard_app {
    	/**
    	 * The launch() method is the only method required for an app.
    	 * It is called by the webCOMAND when the app is to be launched.
    	 *
    	 * The launch() method is used to prepare the app interface for
    	 * subsequent interaction through ajax requests.  It should
    	 * return one of the following:
    	 *
    	 * 1. a string, which will be printed by the framework
    	 * 2. a JSON object, which will be passed to javascript
    	 *    framework UI for processing
    	 * 3. TRUE, which indicates success (framework shouldn't do
    	 *    anything)
    	 * 4. FALSE, which indicates failure (framework will report
    	 *    that an unknown error occured)
    	 */
    	public function launch() {
    		return	Apps->app->Title .
    			" App with repository root: " .
    			Apps->webcomand->repo->get_root();
    	}
    }

• Create Package - Create a new Package object in the repository.
  • Enter the the folder name used above in the Namespace field. For example, "com_domain_app_name".
  • Enter the app title in the Title field.
  • Enter the app version number in the Version field (ie. "1.0.0").
  • Leave the other fields with their default values for now.
• Create App - Create a new App object in the repository.
  • Enter the app title in the Title field.
  • Enter the app identifier in the Identifier and Launcher fields. The Identifier field will appear in the URL of the web browser, and does not need to be the app identifier.
  • Select the package just created in the Package field.
  • Leave the Options field empty for now.

The app title should now appear in the webCOMAND interface under apps. Click the app title to launch the app, which will call the launch method in the PHP file and display "Hello World".

Hello World screenshot.

A responsive user interface can be added to an app with Panels.

• < webCOMAND Framework
• Components >