Data Viewers¶
Data Viewers are widgets that are used to display viewers and editors about a certain data set. The root controller will load the base data and supply it to the data viewers as props. The root controller will manage the layout and its models, which allows data viewers to be added and removed in particular locations. The root Layout consists of two main sections and four surrounding auxilary sections ( top, bottom, left, right ). These sections are fixed to the screen current screen size, meaning that they do now scroll off the screen: the top is fixed to the top of the area, the bottom to the bottom, left and right to the sides, and the remaining section is divided amongst the two main sections. Any one of these sections can be null, and its space is given to the other data viewers. A special DashboardDataViewer that support Cards allows these sections to be further divided and scrolled.
DataViewers are made available for use via the Plugins mechanism under the key DataViewer
. DataViewer plugins will act handle to the various parts of the DataViewer: the name/usage, the DataViewer's settings model, and the React component used to display the data to the user. The DataViewer's interface looks like this:
Filed | Type | Description |
---|---|---|
id | string | The unique DataViewer plugin id |
type | string | The unique type of the DataViewer. |
name | string | The human readable name of the plugin |
icon | string | The url or font icon class name of the image used to represent the icon. |
location | string or array of strings | Specifies where in the layout the DataViewer is usable. See Locations |
matches | object or function | This is used to determine if the DataViewer should be used in controllers layout. See below. |
createSettings | function(props) | Creates and returns the DataViewer's Settings model. |
updateSettings | funciton | Optional function( { settings, props } ) to allow upgrading of the settings model. |
component | React.Component | A react component to use to render. Only this or render should be supplied. |
render | function | A function given props. It should return the create react component. Only this or component should be supplied. |
getCardTitle | function | Used with card location. A function( model, dashboardContext ) that returns the card's title, if it is visible |
getCardIcon | function | Used with card location. A function( model, dashboardContext ) that returns the card's icon, if it is visible |
getCardRequired | function | Used with card location. This ( model, factory, dashboardContext ) returns the required support models/editors that should be present at the dashboards root. |
getCardMenuEditor | function | Used with card location. A function( props ) that returns an editor for the card's editor menu. |
getCardFooterEditor | function | Used with card location. A function( props ) that returns an editor for the card footer. |
getDefaultCardContentOptions | object or function | Used with card location. A function( props, dashboardContext ) that returns an object that can specify the card contents height, minHeight, and maxHeight. or an object such as { height : '300px' }. The props are the same as the dashboardContext.sharedProps object, which will the props given to the DataViewer. |
getDefaultCardOptions | object or function | Used with card location. A function( props, dashboardContext ) that returns an object that can specify the card default card options, such as width (span), height (span), style, titleVisible or or an object such as { width : 2 } The props are the same as the dashboardContext.sharedProps object, which will the props given to the DataViewer |
Match Context¶
Not all DataViewers will work with all root controllers. The DataViewers will use the match mechanism to determine if the root controller supplies the appropriated context that will allow the DataViewer to work. The root controller defines the match context used when determining the possible DataViewers to use and can consist any fields. In Molten, the GroupScreen and ItemInfoScreen are used alot. Their match contexts look like this:
Match Field | Value | Meaning |
---|---|---|
type | 'GroupDataViewer' or 'ItemInfoDataViewer' | This is legacy, and defines a similar concept as the client below. |
client | 'GroupScreen' or 'ItemInfoScreen' | This is the type of the root controller. |
clientType | string | The specific client type. If the implementation does not supply this, it will be either 'GroupScreen' or 'ItemInfoScreen' |
path | string | The relationship path |
objectType | string | The type of objects at the relationship path |
relationship | Relationship | The relationship object |
mobile | boolean | True or false depending on if this is a mobile client or desktop client |
Location Strings¶
DataViewers can restrict where they can be used via its location field:
Location String | Meaning |
---|---|
main | This DataViewer can be used the two center layout sections. |
aux | This DataViewer can be used the on of the four auxilary sections. |
card | This DataViewer can be used as a card in the DashboardDataViewer. Its DataViewer can have card specific functions. |
any | This is the same as [ 'main', 'aux', 'card' ] |
hidden | All hidden data viewers are loaded for the layout, but will not be seen. The purpose of hidden DataViewers is to load or prepare other data. It should be a viewless component, meaning its render function returns null. |
support | Not for use by the root controller, but meant as support for other DataViewers. |
Example¶
File MyDataViewer.js.
import I18N from '@leverege/i18n'
const { tf, tfIcon } = I18N.ns( 'my.MyDataViewer' )
export default {
id : 'my.MyDataViewer',
type : 'my.MyDataViewer',
name : tf( 'name' ),
icon : tfIcon( 'configIcon' ),
location : [ 'main' ],
matches : { client : 'GroupScreen },
createSettings : ( props ) => {
return MyDataViewerModel.create()
},
settingsUpdaters : ( { settings, ...opts } ) => { },
component : MyDataView,
}
Be sure to install your plugin in your PluginSetup.js file.
molten.addPlugin( 'DataViewer', MyDataViewer )
GroupScreen and ItemInfoScreen DataViewer Props¶
When a DataViewer is used in a GroupScreen or ItemInfoScreen, the following props will be supplied the Component or render function.
Prop | Type | Description |
---|---|---|
... | All of the fields in the match context | |
actions | object | Deprecated. The Delegate object |
data | object | The current data. The data.items maybe sparce if multiple non-sequential pages have been loaded. Use the pagination to access a single page. The values in data are |
dataViewer | DataViewer | The DataViewer |
dataViewerId | string | The id of the data from the LayoutModel |
dataViewerInstanceId | string | An id tied to the current incarnation of the data viewer component. Useful as a key in dashboard style layouts. Using dataViewerId in a situation like this can lead to duplicate ids when a data viewer's model is copied |
dataViewerModel | object | The DataViewerModel |
dataViewers | DataViewer | Object containing the available data viewers and context. { context : {...}, dataViewers : [...] } |
delegate | object | An object used to request creations, delections, etc from the server. The actions should be dispatched. |
dispatch | object | The redux dispatch |
filter | object | The FilterSourceModel. This is only present in the GroupScreen. |
filterName | string | The key used to store the filter object within the FilterSourcesModel. Used as then data property when calling the onFilterChange function. This is only present in the GroupScreen. |
filters | object | The FiltersSourceModel. This is only present in the GroupScreen. |
history | object | The connected react router history object |
isMobile | boolean | True or false depending on if this is a mobile client or desktop client. repeat of mobile. |
item | ObjRef | The current object ref. This is only present in the ItemInfoScreen. |
layout | object | The root layout model. (GroupScreen only) |
loading | boolean | True if the data is being loaded |
location | object | The connected react router location object |
match | object | The connected react router match object |
model | boolean | The settings component of the dataViewerModel |
objectType | string | The object type, which is the blueprint's alias or id |
onFilterChange | function | Invoke this when the data screen wishes to change its contribution to the filter and sort. The argument should be an event contining { data : filterName, value : newFilterModelObject }. This is only present in the GroupScreen. |
onSettingsChange | function | the function to call to modify the settings object. |
overrideModel | Obejct | The current overrides for this data viewer. May be null. Key value pairs set using overrides. |
overrides | Obejct | Use overrides.set( dataViewerId, key, value ) to store settings outside of settings model. |
paginator | object | The object used to manage pagination. |
parentItem | ObjRef | The parent object ref, if available. |
path | string | The data path of the current screen (e.g. location.vehicles) |
profile | object | The current users profile |
reloadData | function | A function to call to retrigger data loading |
rolloverKey | string | The key used with Selections to manage objects that are rolled over |
selectionKey | string | The key used with Selections to manage objects that are selected |
settings | object | The DataViewer's settings model: |
settingsData | any | DataViewers must give this as the data option to the change event fired in onSettingChanged |
settingsPath | string | The path used with UserSettings to save data. |
targetKey | string | The key used with Selections to manage objects that are targeted |
vertical | boolean | If the DataViewer is used in a header/footer capacity, this will indicate the direction the component will be layed out. This is undefined for primary DataViewers. |