webCOMAND Components

Components visually represent repository objects and web application features.

Content Action - A button that calls a content type method with optional popup form to specify parameters.
Content View - Display an object or collection based on a cPath. May provide options to edit objects.
Field Editor - Display an object field's value for one or more types (layout, data and content types). A field view may also provide options to edit the field value(s).
Widget - jQuery Plugins and other reusable user interface building blocks.

Content Action

A button that calls a content type method with optional popup form to specify parameters. The button will display in an Action Bar, after the standard object (Submit, Save, Cancel) and collection buttons (Open, Delete, New, Import, Export), if the corresponding Content View represents an object of the Content Type associated with the Content Action's Method.

Parameters Popup

If the corresponding method takes parameters, a down-arrow is displayed in the lower-right of the button. When clicked, a popup Form Content View is displayed with a Content Field for each parameter. Parameter defaults will be prepopulated.

A Content Action is an Attribute that references a Content Type Method and defines the button icon, title and optional description for the tooltip to display when the mouse hovers over the button.

Method - Reference a content type method. If the method has parameters, they will determine the popup form. If the method is static and takes one list parameter with a type that matches the method's content type, then it will be made available in aggregate/collection context, when one or more objects of the content type are selected (List View, etc).
Title - The name of the action, as it should appear in the action bar below the icon.
Icon - Optional icon to represent the action, which will be displayed in the action bar above the title.
Privileges - Determines which privileges are required by a user to execute the action. QUESTION: Is this extra layer useful, or should we just pick up on the method permissions to keep it simple?
Description - Optional brief summary to display in webCOMAND or other interfaces to describe the action. Typically displayed as a tooltip when the mouse hoves over the action UI.
Help - Optional help to display in webCOMAND or other interfaces to describe the action. Typically displays above the parameters in the popup.
Script - cScript used to set parameter defaults. The script is executed in the context of the object. Parameter values are set by setting a variable with the same name to the desired value.

Content View

Display an object or collection of objects. Content Views may be read-only, but typically provide object navigation, selection, editing and other interactive features.

Content View Toolbars

Content Views typically enable the following standard features.

Path Bar (Alt+P) - Title of the object or collection objects with option to expand repository navigation breadcrumbs. The main Content View options may also appear to the right, along with a menu.
Action Bar (Alt+A) - Buttons for common object or object collection actions are displayed in the action bar, followed by Content Actions associated with the Content View object(s).
View Bar (Alt+V) - Some Content Views provide their own view-specific controls here.
Collection Bar (Alt+C or Alt+F) - When a Content View displays a collection of objects, the collection bar provides selection options, access to common actions (new, open, delete, import, export, share, etc.), a search input and a count of the number of items in the collection (after filters are applied). Selection options include: All, None, Invert, Copy and Paste. When in list field selection context, where the collection contains selected and unselected items, a Restore option is also availble to restore the selection to its initial state (undo back to state in repository). The search input can take keywords or a cPath filter starting with an open bracket ( [ ). The magnifying glass icon drops-down a simple cPath editor. The editor lists all fields of the base content type. Click a field to add a filter on that field by selecting a value or range/items. Each fields set value or range appears to the right of the field, right-aligned in the editor, and is added to the cPath filter with a logical AND. If there is enough horizontal space, some filter editor fields (preference for checkbox and choice fields) may become visible to the right of the search input to make them easier to select.

Content View Menu

The following options may be available in the Content View menu.

Action Bar - Toggle visibility of action bar.
View Bar - Toggle visibility of view bar.
Collection Bar - Toggle visibility of collection bar.
All Help - Toggle the display of all help items in current view (typically this refers to form view field help, but may be implemented by other views as well).
Edit Path - Toggle path bar cPath editor.
Change View - Change the current view component.
Navigate - Open selected object(s) in current content view (update content view history/back button).
Open With - Open the selected object(s) in a new application or panel.
Minimize - Roll-up the content view to just display the Navigation Bar, making more room for components below.
Maximize - Expand the content view to the full browser window.
Add Child Panel - Add a child panel with content view that is "chained" to this one (click an item to display it in child content view, selecting an item with the checkbox will not display in child view).
Close Panel - Remove this content view and parent panel from the interface, making room for others. The last panel can not be closed.

Content View Options

The following options customize list and form content views, as well as any others that respect them. Default values are denoted for [Full-Panel] and (Field).

cpath - cPath query that references the object or collection to display in the content view.
title_bar - [(show)], hide, disabled - Only available when content view references a collection of objects.
title_bar_style - [path], path_expanded, summary - Summary displays only object icon and title/summary with no path breadcrumb feature, or as many objects in a collection as will fit followed by the number of objects in the collection.
title_bar_back - [auto], show, hide, (disable) - Auto will show when there is a history or parent in the cPath, but be hidden otherwise.
title_bar_forward - auto, show, hide, [(disable)]
title_bar_menu - [(show)], hide, disable - Display "hamburger menu" at very right of Navigation Bar.
title_bar_menu_expand - [(auto)], hide, or array of items to expand when enough room priority items first, where each item is one of the following strings: edit_path, action_bar, view_bar, collection_bar, view, minimize, maximize, navigate. auto is equal to all options as listed here except Navigate, unless displayed for a field, which is then just "ViewBar, View".
title_bar_menu_items - [(auto)], or array of items to include in menu. Options are [edit_path, action_bar, (view_bar, collection_bar, change_view, navigate), all_help, minimize, maximize, add_child_panel, remove_panel].
action_bar - [show], hide, (disabled)
view_bar - [show], (hide), disabled - Only available when the content view has a view bar.
collection_bar - [(show)], hide, disabled - Only available when content view references a collection of objects.
open_with - object with the following fields:
- request_url - URL of the webCOMAND app (must define launch() method)
- component - Fully qualified identifier of the component to display the object or collection. For example, "com.webcomand.form".
- callback - Name of the callback method.

Field Content View

In addition to the full-panel form of a content view describe above, content view features can be scaled back to work in content type field editors, action parameter popups and other places. To enable this, a number of different options are available when creating a content view, which should be respected by each content view whenever possible.

Content Views use the model view controller (MVC) paradigm. Create one with the following steps.

Model - Create a Panel Component Instance based on the Panel Content Type.
View - Create a file based on the webCOMAND JavaScript Content View Prototype.
Controller - Create a file based on the webCOMAND PHP Content Controller Prototype.

Simple Content Views are built with just those 3 steps, but additional PHP, JavaScript, CSS and image files may be added.

Map or Gallary panel screenshot.

Field Editor

A Field Editor is associated with one or more field types (ie. a Data Type, Content Type or Layout Type). Themes and user preferences determine which field editos are used.

Form Fields should always display several common elements:

Title - The field summary (the field Title if exists, otherwise the field Identifier).
Description - Optional field description to display more information about the field immediately after the title.
Controls - Form field controls are provided to manipulate the value from icons that can be clicked. Form field editors that provide controls must display in vertical layout (full-width with Title above Editor/Value) to make room for the control icons on the right side of the field label. For example, Rich Text editors display text formatting controls, and embedded or list content type fields display new, search, and navigation controls. If the form field area is too narrow to fit all controls, some or all controls may be "rolled-up" into a single hamburger menu control, which will scroll if needed.
Help - Optional field help with information about the field, how it is used and expected values.
Editor/Value - An input or widget to enter, update or remove the field value, which may include a popup widget. Popup widgets are typically indicated with a clickable icon in the right of the input or other editor.
Validation - Fields that provide dynamic validation feedback should indicate whether or not the current value is valid. Typically the field editor's background will be green when valid and red when invalid. When invalid, a reason or other help should be displayed below the field to help the user enter a valid value.
State - Normal (no user is currently editing the field), Active (user is editing), Locked (another user is editing).

The exact styling of form fields is defined by a Theme.

Content Views

Some field editors display a Content View, instead of a simple input. For example, an embedded object field displays an object Content View (typically Form View). Embedded list and reference list fields display a collection Content View (typically Simple List View).

When a Content View is displayed for a field editor, the field label serves as the Content View Navigation Bar. In other words, the typical Content View Navigation Bar with a path and breadcrumbs is not available. Instead, the standard field label is used, with controls to the right, similar to the controls found to the right of the Content View Navigation Bar.

When a read-only field value view is also available (ie. the list and count of selected items), an arrow will appear to the left of the field title, which will toggle between the read-only value and full Content View.

Popup Editors

Some field editors display a read-only summary of their value with a popup icon to the right that will popup an editor. For example, object reference fields display a summary of the referenced object(s) with a down-arrow to the right. When the down-arrow is clicked, a popup editor is displayed that contains a Content View.

Popup editors reduce the clutter on a form and can improve load times because the editor and contained objects and options may only need to be loaded when the popup is displayed.

Field Editor Content Type

A Field Editor is a Type attribute. That is, a Field Editor object references one or more Type objects, or more specifically a Data Type, Content Type or Laytout Type objects.

Title - The name of the field editor.
Types - Reference to one or more Types.
Priority - Optional icon to display in webCOMAND or other interfaces to represent the editor.
Interface Method: ToFormInput - Method to convert the field value in the repository to the value that will be passed to the client-side editor.
Interface Method: FromFormInput - Method to convert the field value in the client-side editor to the format that will be stored in the repository.

Widget

App and Panel user interfaces are typically composed of user interface widgets provided by the framework. Most user interface widgets are jQuery plugins, but this is not required. In addition to the "stock" widgets listed below, custom widgets can be developed as well.

Like Apps, Themes, and other Components, Widgets can be packaged and uploaded to the Market.

High-Level Widgets

High-level elements provide a rich user experience to access a collection, object or field.

Tree (jsTree)
Grid (SlickGrid)
Rich Text Editor (CKEditor)
Code Editor (Ace)
Plain Text Editor - Includes basic editing features like find-replace, word-wrap, convert special characters (special quotes to regular quotes), consolidate whitespace (trim ends and reduce groups of one or more whitespace characters to single space), etc.
Form - A set of form field rows. Used by Form Content View and for the Content Action parameters.
Breadcrumbs - Expandable list of icon/title pairs with left-right slide scrolling layout (see Layout below). Also provides option to reduce left, middle or right to ellipsis instead of scrolling, or stack/overlap and expand on item click/tab. Used for object path bar, but can be used to represent any trail of breadcrumbs.
Pathbar - Combines breadcrumbs with history and optional back and forward buttons.
Toolbar - Builds on layout and buttons with optional tabs to make it easy to build simple custom toolbars, including options similar to Microsoft ribbons.
Sidebar - Builds on layout with optional tabs to slide out a Content View from a layout edge.

Low-Level Widgets

In addition to the high-level elements above, more basic elements are also provided as building blocks to more complex interfaces.

Button - Title, icon, tooltip and optional color and drop-down.
Tabs - Set of tab control followed by optional help text for the active tab.
Group - Frame around a group of items with optional help text at top.
Layout - Organize elements into a row, column or a grid, with option to scale cells or overflow to drop-down (>>) or slide scrollers (< >).
Notifier - Title bar with expandable details. When closed, notifications will slide out from where the notifier would normally appear. The alert bar is an example of a notifier.

A collection of preferred Components, and their look can be defined with Themes.