View components
- Michal Nawalany (Unlicensed)
- Krzysztof Nadolski
- Marcin Kubala (Unlicensed)
3. view components
In this chapter we eill present list of all functional element that can be used in view defining.
3.1 general structure
Every component has structure:
<component type="componentType" name="componentName" reference="referenceName" basicOptions>
// HERE YOU PUT COMPONENT CONTENT
// HERE YOU PUT ADDITIONAL OPTIONS
// HERE YOU PUT LISTENERS
// HERE YOU PUT SCRIPT
</component>
Where:
- componentType - defines type of component
- componentName - is an identifier of plugin corresponding to this view definitions
- referenceName - reference name of component. It can be used to acces component in scripts, listeners or hooks.
- basicOptions - here you put basic component options in form key="value".
Basicly addiotional option has structure:
<option type="optionType" value="optionValue" />
3.2 common basic options
3.2.1 field
value type: text
default value: none
description: Defines relation between this component and its field component. It takes source component's entity and gets its field using defined path. It is defined using notation
#{componentReferenceName}.fieldName
where 'componentReferenceName' is reference name of component and 'fieldName' is the field that should be used as field value.
3.2.2 source
value type: text
default value: none
description: Defines relation between this component and source component. It takes source component's entity and gets its field using defined path. It is defined using notation
#{componentReferenceName}.fieldName
where 'componentReferenceName' is reference name of component and 'fieldName' is the field that should be used as source.
3.2.3 model
value type: text
default value: none
description: Binds component with the specified model type.
3.2.4 plugin
value type: text
default value: identifier of plugin which contains view (or in other words - 'current plugin')
description: A "model" attribute's companion property - defines identifier of plugin which contains model. Its value is optional.
3.2.5 defaultEnabled
value type: true | false | never
default value: true
description: Defines if component is enabled by default. If set to 'never' then component can't be enabled using ComponentState.setEnabled(boolean) or its JavaScript equivalent.
3.2.6 defaultVisible
value type: true | false
default value: true
description: Defines if component is visible by default.
3.2.7 hasLabel
value type: true | false
default value: true
description: Defines if component has label. This option is not avalible in form component.
3.2.8 hasDescription
value type: true | false
default value: false
description: Defines if component has description. This option is not avalible in form component.
3.3 common additional options
3.3.1 labelWidth
value type: integer
default value: none
description: Defines element label width in percentage. This option is available for all components with label.
3.3.2 textRepresentationOnDisabled
value type: true | false
default value: false
description: Defines if component is simple label when disabled. This option is available for text, checkbox and select components.
3.4 form
Form is basic container. It can contain all types of components. You should use form to group components presenting data of one entity.
3.4.1. additional options
header
value type: true | false
default value: false
description: Defines if this form fills window header with it's content.
expression
value type: expression
default value: none
description: Expression that describes entity info on header when window is in edit mode. For more informations see expressions section.
3.5 basic elements
3.5.1. input
Input is simple, one line component that allows user to enter text.
additional options
- alignment - [right | left] defines input content alignment. Default value is "left"
3.5.2. textarea
Textarea is simple, multiline component that allows user to enter text.
additional options
- rows - [integer] optional parameter that defines area lines number. Default value is 4.
3.5.3. calendar
Calendar is a component that allows user to enter or choose date.
additional options
- withTimePicker - [true|false] optional parameter that defines if component show input for time. Default value is 'false'.
3.5.4. checkbox
Checkbox is a component that allows user to enter boolean value (checkbox can be selected or deselected).
additional options
- align - [right | left] optional parameter that defines align of checkbox field. Default value is 'left'.
3.5.5. select
Select is component that allow user to choose one value from set of defined values.
additional options
- values - comma separated select values. That values are set as select source when select is not reference to any field.
3.5.6. password
Password is simple browser 'password' field.
additional options
none
3.5.7. button
Button is element that represents simple button. Currently only action supported by Qcadoo MES system is 'redirect'.
additional options:
- url - [string] parameter that defines redirect url (if you define this option, all corresponding options will be ignored)
- correspondingView - [string] defines name of view ('pluginName/viewName') to which this button redirects.
- correspondingComponent - [string] defines reference name of component in correspondingView to which button inserts it's value.
- correspondingViewInModal - [true | false] optional parameter that defines if button should open correspondingView in modal window (default value is 'false').
- modalWidth - [integer] optional parameter that defines modal width (default value is 600).
- modalHeight - [integer] optional parameter that defines modal height (default value is 400).
3.5.8. label
Label represents static localized text.
additional options:
- labelStyle - [normal | label | text] - if set to 'normal', label content will be bolded with increased line height, as required field component's label. If set to 'label', label content will look like not required standard field label. If set to 'text', label content will be displayed as regular text, with normal font weight. (default value is 'normal')
Example:
<component type="label" name="description">
<option type="labelStyle" value="text" />
</component>
3.5.9. file
File is a component that allows user to add file attachment to entity.
additional options:
- thumbnail - [true | false] - if set to true, there is preview of attachment visible on two rows of layout below file component. Preview is possible for some formats only (png, jpg...). (default value is 'false')
Example:
<component type="file" name="photo" field="photo">
<option type="thumbnail" value="true" />
</component>
3.6 advanced elements
3.6.1. grid
Grid component is table representation of entities.
columns
Grid columns are defined as additional options. It's xml structure has matches pattern:
<option type="column" name="columnName" fields="columnFields" options/>
Where:
- columnName - identifier of column (must be unique)
- columnFields - name of fields from model that will be presented in this column. Currently system support only single field name.
- options - list of options as key="value"
Column additional options:
- expression - [string] expression that defines what should be desplayed as column content (see expressions section)
- link - [true | false] this parameters defines if column content should be link to corresponding view (default value is false)
- width - [integer] defines width of column. Default value is 100. Widths in grid are calculated proportionally.
- hidden - [true | false] this parameters defines if column is visible (default value is false)
- classesNames - [string] defines additional CSS classes for column (classes should be defined in CSS files, this parameter doesn't work with link = true option) - example classesCls="wrap-date green-cell"
- classesCondition - [string] defines a condition that tells whether classes should be added to a cell in a column (you could use a standard js comparison operators for example: >,=== and logical operators for example: &&, ||, in addition, you can use entity fields with notation rowObject['fieldName']) - example "rowObject['producedOrderQuantity'] >= rowObject['masterOrderQuantity']"
- align - ["left" | "right"] column's content alignment (default value is "left" except column binded with numeric field)
additional options
- correspondingView - [string] required option that defines name of view that is 'details view' of entities presented in this grid ('pluginName/viewName').
- order - [other] required parameter that defines default oreder of grid. Has two parameters:
- column - [string] name of default order column
- direction - [asc | desc] default order direction
- correspondingComponent - [string] defines reference name of component in correspondingView to which grid inserts it's value.
- correspondingViewInModal - [true | false] optional parameter that defines if grid should open correspondingView in modal window (default value is 'false').
- paginable - [true | false] optional parameter that defines if grid has paging (default value is 'true').
- multiselect - [true | false] optional parameter that defines if grid has multiselect (default value is 'false').
- searchable - [list] list of coma separated column names in with search is enabled. If no column specified, filters toolbar below column names will be unavailable (permanently hidden).
- multiSearch- [list] list of coma separated column names in with search is enabled. If no column specified, advanced search button will be unavailable (permanently hidden).
- orderable - [list] list of coma separated column names in with search is enabled.
- creatable - [true | false] defines if grid has 'new' button on its header (default value is 'false').
- deletable - [true | false] defines if grid has 'delete' button on its header (default value is 'false').
- width - [integer] defines width of grid (in pixels).
- height - [integer] defines height of grid (in pixels).
- fullscreen - [true | false] if true, grid expands to all available space on page. Default value is 'false'.
- hasPredefinedFilters - [true | false] defines if grid has predefined filters (see below). Default value is 'false'.
- prioritizable - [true | false] defines if grid show change priority arrows when corresponding model is prioritizable. Default value is 'true'.
- filtersDefaultVisible - [true | false] defines if filters toolbar should be visible by default. Default value is 'true'.
- footerRow - [true | false] if true is switched row summary
- columnsToSummaryTime - list of columns to summary with time data
- columnsToSummary - list of columns to summary with numeric data
predefined filters
Grid can contain predefined filters that helps user to find set of records more efficiently. Predefined filters has structure:
<predefinedFilters default="predefinedFilterName">
// HERE YOU PUT PREDEFINED FILTERS
</predefinedFilters>
Where:
- predefinedFilterName - [string] name of the default predefined filter (see name attribute in <predefinedFilter /> element)
Every predefined filter has structure:
<predefinedFilter name="predefinedFilterName">
<filterRestriction column="restrictionColumnName" value="restrictionValue" />
// HERE YOU CAN PUT MORE RESTRICTIONS
<filterOrder column="orderColumnName" direction="orderDirection" />
</predefinedFilter>
Where:
- predefinedFilterName - [string] name of predefined filter
- restrictionColumnName - [string] name of restriction column
- restrictionValue - [string] value of restriction
- orderColumnName - [string] name of order column
- orderDirection - [asc | desc] order direction
Restrictions and order are optional. There can be only one 'filterOrder' parameter.
row style resolvers
Grid can mark they rows with additional CSS classes. Row style resolver is a hook-like method which gets row entity and returns set od CSS classes to be applied for. For more details and examples see 'row style resolvers' section
criteria modifiers
Criteria modifier is a hook-like method which pass SearchCriteriaBuilder used by grid component to fetch row entities and allow you to modify them. For more details and examples see 'criteria modifiers' section
3.6.2. lookup
Lookup is a component that allows user to choose related entity. It is presented as simple one-line input with entity description. User can either enter entity code from keyboard (system will automatically search corresponding entity and update this field) or choose entity from pop-up grid.
additional options
- expression - [string] expression that defies what to display in lookup when entity is selected (see expressions section).
- fieldCode - [string] name of entity field that will be used to search for entity
- modalWidth - [integer] custom width of pop-up grid's modal window. Default value is 600.
- modalHeight - [integer] custom height of pop-up grid's modal window. Default value is 560.
header
value type: true | false
default value: false
description: Defines if this lookup show window header. If you would like to pass some parameters to header, you should add 'headerValue' parameter to lookup grid FilterValueHolder. REMEMBER - you must define criteriaModifier, if you would like to use FilterValueHolder.
popup options
In lookup you must define options for popup grid:
- column
- searchable
- orderable
- prioritizable
All options has the same structure as in grid component.
Popup grid has by default first column with value defined in 'fieldCode' option which will be also searchable.
row style resolvers
Lookup can mark they rows with additional CSS classes. Row style resolver is a hook-like method which gets row entity and returns set od CSS classes to be applied for. For more details and examples see 'row style resolvers' section
criteria modifiers
Criteria modifier is a hook-like method which pass SearchCriteriaBuilder used by lookup component to fetch row entities and allow you to modify them. For more details and examples see 'criteria modifiers' section
3.6.3. awesomeDynamicList
Awesome Dynamic List is complex component that can display and edit entities defined in 'has many' relation.
content
to define Awesome Dynamic List you must specify content of its elements. Structure of this definition is:
<components>
// HERE YOU PUT INNER COMPONENTS DEFINITION
</components>
where inner components are standard xml component definitions.
additional options
- hasButtons - [true | false] optional parameter that defines if list has 'new' and 'delete' buttons (default value is 'true').
- hasBorder - [true | false] optional parameter that defines if list has border
- flipOrder - [true | false] optional parameter that defines if add button prepend an element instead of append it (default value is 'false')
selection of inner Awesome Dynamic List components
Sometimes you need to select specific component inside Awesome Dynamic List Component. In example: to assign error messages or mark inputs as mandatory.
AwesomeDynamicListComponent provides two helpful methods: getComponents() which returns list of rows (each row is independent FormComponent containing components described in <components />) and getComponent(Long entityId) which returns FormComponent corresponding to entity with given id or null if not found.
Also FormComponent provides findFieldComponentByName(String name) which returns first FieldComponent that match given name.
With combination of above methods you can select specific components in given row(s). For example code below sets specific component in second row as mandatory:
AwesomeDynamicList adl = givenViewDefinitionState.getComponentByReference("ourAdlComponent");
List<FormComponent> adlRows = adl.getComponents();
FormComponent secondRowForm = adlRows.get(1);
FieldComponent someComponent = secondRowForm.findFieldComponentByName("someComponentName");
someComponent.setRequired(true);
3.6.4. tree
Tree can present entities in tree form. Its model must be tree type.
additional options
- hasNewButtons - [true | false] optional parameter that defines if tree has 'new' button (default value is 'true').
- hasDeleteButton - [true | false] optional parameter that defines if tree has 'delete' button (default value is 'true').
- hasEditButton - [true | false] optional parameter that defines if tree has 'edit' button (default value is 'true').
- hasMoveButton - [true | false] optional parameter that defines if tree has 'move' button (default value is 'true').
- selectableWhenDisabled - [true | false] optional parameter that defines if tree should allow node selection (and also propagate select & hover events) when it is disabled (default value is 'false').
- hasCustomActionButton - [true | false] optional parameter that defines if tree has 'custom action' (default value is 'false'). It should be used with custom translation keys - customActionTitle and customActionConfirm
- customActionIcon - [string] optional parameter that defines icon for custom action button (should be used with option hasCustomActionButton).
node type definition
To define tree you must define node types that this tree contains. Every node has structure:
<dataType name="nodeTypeName">
// HERE YOU PUT NODE TYPE OPTIONS
</dataType>
Where:
- nodeTypeName - [string] name of node type
node type options
Available node type options are:
- nodeLabelExpression - [string] expression that should be used to calculate node text value (see expressions section)
- correspondingView - [string] required option that defines name of view that is 'details view' of entities presented in this node type ('pluginName/viewName').
- correspondingComponent - [string] defines reference name of component in correspondingView to which this node type inserts it's value.
- correspondingViewInModal - [true | false] optional parameter that defines if tree should open correspondingView in modal window (default value is 'false').
- nodeIcon - [string] path to node icon for this type
- newIcon - [string] path to 'new' button icon for this type
3.6.5. staticPage
Static page allows to include HTML content into view definition.
special options:
- page - [string] Required parameter that defines url to page that is included.