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 React HTML 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.