catreact/DOCS_README.md

Catavolt Core React Components

## Catavolt Javascript SDK and React Components  
### Overview  
The Catavolt Javascript solution is comprised of three layers, all independently usable, and all providing a different level of programmatic access and customization opportunies.  
  
1. **The Catavolt Javascript SDK** - A pure Javascript API, providing low-level access to the Catavolt data model and server API.   
1. **The Catavolt Core React Components** - A set of components that provide declarative access to many of the SDK functions, making the construction of custom Catavolt Apps much easier.  These components provide very minimal, default styling, and allow the client to fully control the document structure (i.e. html and css)   
1. **The Catavolt Extended React Components** - A set of components that provide default styling, include some html markup, but still allow for customization and the application of a custom style.  The components are also built so that any single component could be replaced (or wrapped) with a custom component if desired.     

The Catavolt React Component hierarchy mimics the Catavolt Extender (server model) as well as the object model used in the Catvolt SDK. Please see [this document](../componentOverview.pdf).
   
### Catavolt ‘Core’ React Components (‘core’ package)  

**<{@link CatavoltPane}/>**  
Required root component. Initializes the SDK and supplies the ‘context’ with support objects    
Accepts {@link CatavoltPaneProps}  

**<{@link CvLogin}/>**  
Allows for declarative access to Catavolt’s login service. Publishes the Login Event to the EventRegistry for other components to consume.    
Accepts {@link CvLoginProps}

**<{@link CvAppWindow}/>**  
Analogous to the Catavolt AppWinDef object. Exposes the AppWinDef to the context scope and makes multi-window apps possible.    
Accepts {@link CvAppWindowProps}

**<{@link CvWorkbench}/>**  
Provides access to the workbench via workbenchId.    
Accepts {@link CvWorkbenchProps}

**<{@link CvWorkbenchMenu}/>**  
Allows for the construction of ‘menu’ of the current workbenches in the current AppWindow scope.    
Accepts {@link CvWorkbenchMenuProps}

**<{@link CvLauncher}/>**  
Provides a mechanism to custom render a launcher and handle a ‘click’ action.    
Accepts {@link CvLauncherProps}

**<{@link CvNavigation}/>**  
Represents a ‘target’ for a navigation action.  Also ‘subscribes’ to all Navigation Events, and handles those that match its ‘target’ value.  
Accepts {@link CvNavigationProps}

**<{@link CvForm}/>**  
Handles the ‘logical’ rendering of a Form definition, hosting pluggable ‘component’ renderers for each type of ‘pane’ that may be a ‘child’ of a Form.  
Accepts {@link CvFormProps}

**<{@link CvListPane}/>**  
Provides access to a ‘ListContext’, it’s associated data, and list paging controls.  
Accepts {@link CvListPaneProps}

**<{@link CvQueryPane}/>**  
Provides access to a ‘QueryContext’ subtypes and their associated data
Accepts {@link CvQueryPaneProps}

**<{@link CvDetailsPane}/>**  
Provides rendering of a ‘DetailsContext’ a data editing controls.  
Accepts {@link CvDetailsPaneProps}

**<{@link CvRecordList}/>**  
Should be used as a child of ‘{@link CvListPane}’. Allows for the specification of a rendering function to render the ‘EntityRecords’ supplied by a parent ListPane.  
Accepts {@link CvRecordListProps}

**<{@link CvRecord}/>**  
Corresponds to an ‘EntityRecord’.  Provides a context for accessing the ‘Properties’ of a record.  Also provides a default click handler for a record.  Publishes Navigation Events.  
Accepts {@link CvRecordProps}

**<{@link CvAction}/>**  
Allows for the direct creation of a Catavolt ‘Action’.  Provides ‘click’ handling options as well as the base logic for ‘{@link CvMenuItem}’.  Publishes Navigation Events.  
Accepts {@link CvActionBaseProps}

**<{@link CvMenuItem}/>**  
Allows for the recursive, nested construction of ‘MenuDef’s.  Provides click handling options.  Publishes Navigation Events.  
Accepts {@link CvMenuItemProps}  

There are several ways to use CvMenuItem  

1. Simple wrapper - Provide an actionId OR menuItem and (optionally) a wrapperElem and wrapperElemProps.  
This will render your child tags wrapped in wrapperElem with an onClick that fires 'this' action  
1. Function for submenus - Provide an actionId OR menuItem and a subMenuItemRenderer
see {@link CvMenuItemProps.subMenuItemRenderer}.
Providing this function will allow you to render all 'child' MenuDefs (but not 'this' MenuDef).
The result will be wrapped in wrapperElem (if provided)
1. Recursive rendering of child menus - Omit both an actionId and menuItem and (optionally) specify a parentMenuItem
The render method will render each child of the parentMenuItem (provided or found in scope) passing along all
additional properties to new child {@link CvMenuItem}s

**<{@link CvResource}/>**  
Provides access to remote resources.  (Currently images via the GMLAssetsURL)  
Accepts {@link CvResourceProps}

**<{@link CvProp}/>**  
Should be used as a child of ‘{@link CvRecord}’.  Allows for accessing or custom rendering a ‘property’.  Renders binary properties as responsive images.  
Accepts {@link CvPropProps}

**<{@link CvMessagePane}/>**  
Allows for the rendering of {@link CvMessage} events  
Accepts {@link CvMessagePaneProps}

**<{@link CvLogout}/>**  
Handle end session  
Accepts {@link CvLogoutProps}

Additional Mixins/Helpers
{@link CvQueryBase} (module)  
Base Mixin for {@link CvQueryPane} and {@link CvListPane}

**CvReact** (module}  
Base, common components.  
{@link CvBaseMixin}, {@link CvEventRegistry}, {@link CvEvent} and {@link CvEventType}  definitions and utility functions.  

  
### Catavolt ‘Extended’ React Components (‘ext’ package)  
  

**<{@link CvLoginPanel}/>**  
Basic styled, configurable Login Component  
{@link CvLoginPanelProps}

**<{@link CvWorkbenchManager}/>**  
Basic Workbench ‘switcher’ composed of a {@link CvDropdownWorkbenchMenu} and {@link CvGraphicalWorkbench} by default.  ‘Pluggable’ with other implementations of these.  
{@link CvWorkbenchManagerProps}

**<{@link CvGraphicalWorkbench}/>**  
Provides a styled, ‘icon-based’ view of a workbench and launchers, with configurable number of columns.  
{@link CvGraphicalWorkbenchProps}

**<{@link CvDropdownWorkbenchMenu}/>**  
Provides ‘Workbench selection’ menu implementations for selecting an active workbench.   Currently a basic ‘drop-down’ menu  and a ‘Tabbed’ menu are available.  
{@link CvGraphicalWorkbenchMenuProps}

**<{@link CvNavigator}/>**  
Renders a ‘Navigation Request’ using a default, Catavolt styled {@link CvFormPanel}  
{@link CvNavigatorProps}

**<{@link CvWebNavigator}/>**  
Renders a ‘Web Navigation Request’ by opening the url in a browser  
{@link CvWebNavigatorProps}

**<{@link CvFormPanel}/>**  
Builds ‘styled’ subtypes of Form layouts (tabbed, 3-pane, ordered, etc.).  Provides pluggable access for new or custom form layouts.  
{@link CvFormPanel}

**<{@link CvListPanel}/>**  
Default tabular list renderer.  
{@link CvListPanelProps}

**<{@link CvDetailsPanel}/>**  
Default ‘cell’ based detail renderer.  Provides editing/saving support.  Uses {@link CvCellValueDef}’s to render cells.  
{@link CvDetailsPanelProps}

**<{@link CvCellValueDef}/>**  
Render’s a Catavolt ‘Cell Value Definition’.   AttributeCellValueDef, LabelCellValueDef, etc.  
{@link CvCellValueDefProps}

**<{@link CvDataAnno}/>**  
Applies default style to a properties and records, based on the Data Annotations attached to the entities (if any).  
{@link CvDataAnnoProps}

**<{@link CvHeroHeader}/>**  
Convenience component to add a logo or company header  
{@link CvHeroHeaderProps}

**<{@link CvDropdownMenu}/>**  
Renders MenuDef’s as a basic ‘Dropdown’ menu  
{@link CvMenuProps}

**<CvBarcodeScanPanel/>**  
Render a default, styled barcode scan detail panel  

**<CvGeoInfoPanel/>**  
Render a default, styled geo location or geofix detail panel  

**<{@link CvMapPanel}/>**  
Render a default, styled map panel  
{@link CvMapPanelProps}

**<CvCalendarPanel/>**  
(pending implementation) Render a default, styled calendar  

**<{@link CvGraphPanel}/>**  
Render a default, styled graph
{@link CvGraphPanelProps}

**<CvImagePickerPanel/>**  
(pending implementation) Render a default, styled image picker panel  

**<{@link CvMessagePanel}/>**  
Uses a {@link CvMessagePane} to display a "toast-like" notification of messages (based on toast.js)
{@link CvMessagePanelProps}