Views, widgets and layout

Views

View declaration files override the default detail view (generated by Skyve).

View files are located within the views folder in the document package. Typically, users interact with a detail view after zooming into the document from a list.

Two detail views can be declared for each document.

View Description
edit.xml The basic view declaration for detail editing of a bean (normally accessed by zooming into a row from a list).

Menu items can also target edit views directly. In this case the menu item will trigger newInstance() and a new document instance will be returned (and therefore displayed). To show a singleton (a document instance which is the only applicable existing instance within the context), the newInstance() method can be overridden to select and return an existing bean in place of the newly created instance.

If a create.xml is supplied, the edit.xml file is only used after the document is created.
create.xml A special case of edit view which is used if create.xml supplied and if isCreated() is false similar to the following

View declaration

Create view

The create view concept is useful in cases where a several-step wizard type view is required specifically for the creation of a new record where this is signficantly different to the typical data entry view, though in most cases, the edit view is satisfactory.

To use a separate create view, create a view called create.xml and ensure the name property within the view file is create.

Skyve will use the create view if the document declares a created condition.

<condition name="created">
	<description>Created</description>
	<expression>
		<![CDATA[isPersisted()]]>
	</expression>
</condition>

An example of a create view can be found in the Skyve admin module for the User document. In this case, a create view is useful because creating a new User involves several steps not normally required for simple data entry. Compare this with the admin.Contact document - where the basic edit view is sufficient for creating new Contacts and a create view is not required.

Containers

Containers are layout devices which contain other elements.

Containers share basic properties:

Property Description
invisible Whether the container (and contents) are invisible to the user.

Invisibility may be set to true, false or the result of a declared condition.
percentageHeight Percentage of the vertical visible area over which the container (and contents) will be stretched.
percentageWidth Percentage of the horizontal visible area over which the container (and contents) will be stretched.
pixelWidth Width of the container in pixels.
pixelHeight Height of the container in pixels.

Container properties

Autofit behaviour

Rendering behaviour is specific to browsers, however Skyve will attempt to render the view as declared. Unless pixel sizes are specified, Skyve will stretch view elements to cover the available window size, according to the proportions and layout properties defined in the view.

Where the absolute size of the view exceeds the window space available, the view will render with scroll bars. Containers may overflow if the view definition doesn’t adequately take account of the number and nature of items contained.

ContainerDescriptionSpecific propertiesExample
hboxElements are laid out horizontally in the view and may contain other containers.
  • border - whether a border is displayed
  • borderTitle - the text to be displayed as a border title
  • pixelMemberPadding - padding (in pixels) between members
  • pixelPadding - padding (in pixels) around all members
hbox
vboxElements are laid out vertically in the view and may contain other containers.
  • border - whether a border is visible
  • borderTitle - the text to be displayed as a border title
  • pixelMemberPadding - padding (in pixels) between members
  • pixelPadding - padding (in pixels) around all members
vbox
tabPane, tabA tab pane contains tabs.
Tabs may contain other containers.
  • name - a logical way of referring to the tabPane
  • disabled - whether the tabPane is disabled
  • disabled (tab) - whether the tab is disabled. A disabled tab will display the tab header, but cannot be accessed.
  • title (tab) - the title of the tab
  • selected (tab) - whether the tab is opened by default when the view is accessed. Selected can be set to *true*, *false* or the result of a defined condition.
tabPane

View containers

Form

Forms contain columns and rows. Rows may only contain items.

Columns may be defined with or without pixelWidth or percentageWidth. If no width type is displayed, the column will be sized according to the impact of other elements of the view. percentageWidth will size the column accordingly, provided this is possible.

Form Example

<form>
  	<column percentageWidth="20" />
  	<column />
  	<column />
	<row>
  		<item>
  			<textField binding="name" />
  		</item>
	</row>
  	<row>
  		<item>
  			<textArea binding="description" wrap="true" />
  		</item>
	</row>
</form>

Form declaration

In the above example, 3 columns are declared. The two rows contain only a single widget, however the textField and textArea widgets include labels. These widgets therefore fill the two leftmost columns, leaving the third column empty. Together the 3 columns stretch the width of the entire available horizontal window space.

Form declaration

Most widgets span two columns - one for the widget label and one for the actual widget itself. If the number of columns exceeds the number of columns declared in the form, the row will overflow to another row. The spacer widget is provided to allow position of widgets to odd columns and for widgets with no label component.

Items within rows always fill from the leftmost available column. The spacer widget is provided to allow items to fill from other than the leftmost column.

If two unsized columns are defined, they will be stretched so that each column will fill the available horizontal space. If one column is sized and the other is not, the unsized column will stretch to fill the rest of the available horizontal space.

Tip: To allow the view to autofit and resize correctly, leave at least one column unsized.

Table

Deprecated. This feature is now met by using a disabled dataGrid.

Item

Property Description
align Controls alignment of the item (left, right or centre).
colspan The number of columns which the item spans.
help tool-tip help text for the item
label A label to be displayed irrespective of the type of widget the item contains.
labelAlign Controls the alignment of the item label.
required Whether the contained widget must have a value set before any actions can be completed.
rowspan The number of rows which the item spans.
showHelp Whether the contained widget will include a tool-tip help icon button, for a widget with an attribute which has a shortDescription defined.
showLabel Whether the label of the contained widget will be displayed.

Item properties

Widget

Skyve provides a number of view widgets, which can also be defined as document attribute defaultWidget. When widgets contain labels, the label will be displayed in bold type if the attribute is required.

</td>
Widget Description ExampleAllowed containers
blurb displays the contained markup inside a div with binding substitutions
Unlike other widgets, the blurb is not required to be contained within a form container
blurb All
button can be placed within the view when the inActionPanel flag for an Action is set to false

If the Action is declared to be in the Action Panel, then no button widget is required to be declared.
button All
checkBox Tri-state check box (null/true/false) - for a two-state checkBox set the property `triState="false"` checkBoxForm
checkMembership Providing for checkbox multiselectionNon-form
colourPicker displays a text box containing the colour code value together with a sample square of the colour

Clicking on the sample square activates a colour selector popup.
colourPicker In this example, the colour button at the RHS will open a colour selector as shown below:
colourPicker
Form
combo drop-down selector for enumerations or where a domain type is specified for the document attribute combo Form
comparisondisplays the differences between two beans instances and the ability for the users to apply differences between the instances (for an example, see the *Audits* function in the Skyve admin module comparisonNon-form
componenta component declares the inclusion of other view declarations, or sections of view declarations, allowing re-use of view declarationNon-form
contentImage displays the loaded image along with an upload action contentImage Form
contentLink displays a hyperlink to open the content in a new browers window together with an upload action contentLinkForm
dataGridNon-form
dataGridRepeaterNon-form
default If used in a view, this will render whatever the default widget is.

Either the defaultWidget declared on the document attribute or the Skyve default control for the attribute type.
Form
dialogButton Not yet implemented.All
geoLocator Geolocator will render a Map button, when pressed, a Geolocation window will appear with a pointer to the address or position bound to the Geolocator widget.

A new address or location can be selected within the Geolocator Map if the Geolocator is not disabled.

The Geolocator Widget has multiple bindings which interact with the map:
  • addressBinding
  • cityBinding
  • stateBinding
  • postcodeBinding
  • countryBinding
  • latitudeBinding
  • longitudeBinding
When the Map button is clicked, the geolocator (shown) will be displayed in a modal window. geoLocatorAll
geometry displays a Well Known Text (WKT) representation of the geometry, with a map-based selection toolForm
html displays HTML content together with an Edit button

When the edit button is clicked, a popup HTML editor window is displayed allowing users to create rich HTML.
htmlForm
inject allows the inclusion of javascript snippets within the view injectNon-form
label Simple text. labelAll
link provides a link style approach to Skyve platform features (partially implemented)
options include
  • actionReference - perform an action
  • contentReference - access a content item
  • defaultListViewReference - open a default list view
  • editViewReference - open an edit view for a binding
  • externalReference - a link to an external resource
  • implicitActionReference - perform a Skyve implicit action
  • queryListViewReference - open a list view based on a query
  • reportReference - perform a report action (view a report)
  • resourceReference - view a Skyve resource
linkAll
listGridlist grid component included in a view - the listGrid provides the same functionality as menu lists within the context of a custom view for the management of unrelated or informally-related bean instanceslistGridNon-form
listMembershiplist-based multi-selection toollistMembershipNon-form
listRepeaterbasic scrollable list for displaylistRepeaterNon-form
lookup Deprecated. Form
lookupDescription lookupDescription is used to display an association to another document, and combines a combo with a pick button.

Users may select a value from the combo, or type values into the text box which will locate a matching value in the combo drop-down list if found.

When the pick button is pressed, a Pick window containing a listGrid is displayed, showing eligible values as declared in the document association.

Whereas normally double-clicking in a grid will zoom into the row, double-clicking in a Pick grid will select that value, close the popup and set the value of the lookupDescription combo next to the Pick button.

The down-arrow button reveals options to Edit (i.e. Zoom), New or Clear the reference.
More features of the lookupDescription are explained in the next section.
lookupDescription
In this example the bizKey of the currently associated document instance is displayed in the control. To use another attribute change the lookupDescription's descriptionBinding attribute.
If the Pick button is clicked, a listGrid of eligible document instances is shown in a modal window.
pick
The down-arrow selector button will display options for Edit (edit the referenced document on-the-fly), New (create a new potential reference on-the-fly) and Clear (clear the reference).
lookupDescription actions
Form
mapNon-form
password a textField which obfuscates the entered value passwordForm
progressBar Not yet implemented.Non-form
radio radio selector for enumerations or for document attributes where a domain type is specified

Radios may be laid out vertically or horizontally, using the property vertical.
Vertical arrangement is the default arrangement for radio selectors when no arrangement is specified.

Radios can also be used for boolean attributes. To do this, declare a constant domain for the attribute, and override the `getConstantDomainValues` Bizlet method to return two domain values
  • `new DomainValue(Boolean.TRUE.toString(), "Yes");`
  • `new DomainValue(Boolean.FALSE.toString(), "No");`
radio Form
richText provides a rich text area together with formatting toolbar richTextForm
slider Numeric slider.

Properties include:
  • min
  • max
  • numberOfDiscreteValues
  • roundingPrecision

May be displayed vertically when vertical is set to true.
sliderForm
spacer a widget provided to fill a column when no other widget is required

Items within rows always fill from the leftmost available column. The spacer widget is provided to allow items to fill from other than the leftmost column.
The spacer widget displays nothing.All
spinner numeric spinner allowing users to either type or select a value using the arrows

Properties include:
  • min
  • max
  • step - the amount to increment/decrement for each arrow button press
spinnerForm
staticImage displays a static image staticImageAll
staticLink hyperlink to a static URL

Properties:
  • ref - the URL
  • value - the value displayed in the link, this defaults to the URL if not supplied.
  • newWindow - whether the target will be displayed in a new window
Not yet implemented.Form
textArea basic data entry field for long text

textArea provides a wrap property to control whether the contained text is word wrapped.
textAreaForm
textField provides basic data entry for text attributes

textField responds to the type of the bound attribute, and will display converter hint if the value is null.

For date and dateTime types, a calendar selector is displayed.
textField calendar
This example is a textField widget bound to a text type attribute.
textField
This example is a textField widget bound to a time attribute using the HH_MM converter.
textField time
This example is a textField widget bound to a date or dateTime attribute. The calendar tool on the right will either include time or not depending on which of these types the attribute is.
Form
treeGriddisplay and navigate hierarchical structurestreeGridNon-form

Change event action (client-side events)

User interactions can be customised via the use of change event handlers declared on view widgets. For example, a textField widget provides handlers for blur, change and focus events.

A change handler can be included in a widget declaration as follows:

<textField binding="name">
	<onBlurHandler>
		<server action="recalculate" />
	</onBlurHandler>
</textField>

The above declaration will call the custom recalculate server-side action when the blur event occurs on the textField (i.e. as the focus moves from the textField).

The availability of change event handlers is specific to the type of widget. For example, a blur event is relevant for an input widget, but a remove event is not relevant for a textField.

The following tables shows which change handlers are available for each type of view widget.

Widget blur change focus added cleared deleted edited picked removed selected
blurb                    
button                    
checkBox Y Y Y              
checkMembership Y Y Y              
colourPicker Y Y Y              
combo Y Y Y              
comparison                    
component                    
contentImage                    
contentLink                    
dataGrid       Y   Y   Y Y Y
dataGridRepeater                    
default                    
dialogButton                    
dynamicImage                    
geoLocator                    
geometry Y Y Y              
html                    
inject                    
label                    
link                    
listGrid           Y Y     Y
listMembership   Y                
listRepeater                    
lookup       Y Y   Y Y    
lookupDescription       Y Y   Y Y    
map                    
password Y Y Y              
progressBar                    
radio Y Y Y              
richText Y Y Y              
slider Y Y Y              
spacer                    
spinner Y Y Y              
staticImage                    
staticLink                    
textField Y Y Y              
textArea Y Y Y              
treeGrid           Y Y     Y

View containers (vbox, hbox, tabPane, form etc) do not provide change handlers.

Multiple event actions can be defined for the single event, and the order of execution will follow the order in which the handlers are declared.

<combo binding="treatmentType">
  <onChangeHandlers>
    <server action="recalculate" />
    <setDisabled disabled="zeroValue" />
    <rerender />
  </onChangeHandlers>
</combo>

Example of multiple onChangeHandlers

Change event actions can be defined for the change of value of widgets defined within a view.

Event Action Description
rerender hits the server, reevaluates the UI conditions, but maintains user edits.
server executes a server-side action.
setDisabled sets the widget to disabled based on a condition (SmartClient renderer only)
toggleDisabled checks the state of the widget pointed to by the binding and toggles the disabled state. (SmartClient renderer only)
setInvisible sets the widget to invisible based on a condition. (SmartClient renderer only)
toggleInvisible checks the state of the widget pointed to by the binding and toggles the disabled state. (SmartClient renderer only)

OnChange Event Actions

List selection and refresh

A common gesture is to select a row in a list as the basis of some action.

To achieve this, set the onSelectedHandler on the widget as shown below.

<listGrid query="qTimesheets" 
	selectedIdBinding="selectedTimesheetId" 
	postRefresh="refreshTimesheetList">
	<onSelectedHandlers>
		<server action="TimesheetSelected" />
	</onSelectedHandlers>
</listGrid>

The selectedIdBinding is the binding name of a document attribute that holds the bizId of the selected row - so that you can use the result of the selection gesture in server-side code.

In this case, the document would include an attribute declared as follows:

<id name="selectedTimesheetId" persistent="false" trackChanges="false">
	<displayName>Selected Timesheet</displayName>
</id>

Typically the result of the user selection is not persisted (persistent="false") and the bean would not normally be considered to be dirty because of the selection (trackChanges="false").

The result of the selection can then be used in server-side code as a normal bean attribute:

	//retrieve the timesheet selected in the list by the ser
	Timesheet t = CORE.getPersistence().retrieve(Timesheet.MODULE_NAME
		, Timesheet.DOCUMENT_NAME
		, bean.getSelectedTimesheetId()
		, false);
		
	//do some processing with the selected timesheet t
	...

Lists are refreshed lazily and only when they are accessible to the user. For example, if a listGrid is on a tab which is not currently selected, the listGrid will not be refreshed until the tab is active. However, lists will be refreshed after server-side activity, and so developers need to consider the impact using the selected event may have.

postRefresh allows you to specify refreshing of the list conditionally - to guard against situations where the results of the onSelectedHandler causes a continuous list refresh.

Note that with postRefresh="false", the list will still be refreshed the first time it is made available to the user, so that an empty list isn’t returned.

Also note that lists will be refreshed if the list is accessible by the user from scrolling - so if the list is outside of the area currently visible but still on the active part of the view, the list will be triggered for refresh unless controlled by a postRefresh condition.

Update property

The update property (PrimeFaces renderer only) implements the PrimeFaces update property - which allows developers to limit rerendering to a specified container.

Update property for change handlers

In the above example, only the container with a widgetId of citizenship will be rerendered when the value of the combo is changed.

The lookupDescription widget in detail

The lookupDescription widget is unique to Skyve and provides comprehensive ability to display and select document references.

Property Description
binding The association attribute to which the widget is bound.
descriptionBinding The binding in the associated document which will be displayed in the text box when an reference is selected. In most cases, the descriptionBinding will be set to the bizKey attribute of the reference, which defines a short text representation of the entire document being referenced.

bizKey is always available for query based widgets and does not need to be declared as a column within the query definition.
disabled Controls whether all aspects of the widget are disabled.
disableAdd Controls whether the Add function (New) is disabled (allowing on-the-fly creation of the foreign reference).
disableClear Controls whether the Clear function is disable (clearing the reference).
disableEdit Controls whether the Edit function is disabled (allowing on-the-fly editing of the foreign reference).
disablePick Controls whether the Pick list is accessible.
invisible Controls whether the entire widget is invisible.
pixelWidth Width of the text box component in pixels.
query By default, a lookupDescription will use the defaultQuery for the document specified in the association attribute declaration for both the combo/drop-down and pick list. If the association nominates a metadata query then this query will be used. If the widget nominates a query in this attribute, this query will be used.

Note that bizKey is always available for queries and does not need to be declared as a column in the query.

Properties of the lookupDescription

lookupDescription

Multi-column drop-down/combo lookupDescription

By default the lookupDescription will display only the bizKey for each row returned by the effective query in the drop-down. However, lookupDescription can alternatively nominate a subset of query columns for display in the drop-down.

<lookupDescription binding="bankAccount" descriptionBinding="bizKey" query="docQueryBankAccount" >
    <filterParameter operator="equal" name="active" value="true"/>
    <dropDown>
        <column>bsb.bsb</column>
        <column>accountNumber</column>
    </dropDown>
</lookupDescription>

Multi-column drop-down lookupDescription

Filter parameters for lookupDescription

Filter parameters can be applied to the lookupDescription widget, which will apply additional filtering (over and above any filtering defined in the applicable query). Filter parameters can be value (for a static value) or binding (filtering the list of eligible references by the value of a binding from the document being viewed).

<lookupDescription binding="contact" descriptionBinding="bizKey" disabled="notManager">
  <filterParameter name="contactType" value="Person" />
</lookupDescription>

Filter parameters for lookupDescription

If filterParameters have been defined and the user creates a reference on-the-fly (using the Add/New action), the created document will have the filterParameter values set by default.

<row>
  <item>
    <lookupDescription binding="codeListAllocationCode" descriptionBinding="bizKey">
      <filterParameter name="codeListSchemeCode" binding="parent.codeListSchemeRound.codeListSchemeCode" />
    </lookupDescription>
  </item>
</row>

Example lookupDescription with filterParameter

In the above example, the lookupDescription for binding codeListAllocationCode has a filterParameter using the current document binding of parent.codeListSchemeRound.codeListSchemeCode used as the filtering value on the column named codeListSchemeCode in the related data set or query (using the name of the reference implies the use of the bizId field).

If the user opts to create a new codeListAllocationCode reference, then the attribute called codeListSchemeCode in the new codeListAllocationCode instance will be set to the value of parent.codeListSchemeRound.codeListSchemeCode.

Note that any number of filterParameters can be declared.

OnChange handlers for lookupDescription

Rather than a generic OnChange action event, the lookupDescription provides the ability to define actions for each type of event which the widget supports.

The available event handlers are:

  • onAddedHandlers,
  • onClearedHandlers,
  • onEditedHandlers, and
  • onPickedHandlers.
<lookupDescription binding="contact" descriptionBinding="bizKey" disabled="notManager">
  <onAddedHandlers>
    <server action="applyRules" />
  </onAddedHandlers>
  <filterParameter name="contactType" value="Person" />
</lookupDescription>

The onAddedHandler event action

In the above example, if the user sets a reference by creating a document on-the-fly, the server-side action applyRules will be executed after the Add action is completed.

The action events available are the same as for all other event actions as described in Table 14. As with all OnChanged handlers, multiple event actions can be executed for the same event.

dataGrid

A dataGrid displays members of a collection.

The dataGrid widget has the following properties.

Property Description
binding the collection to which the grid is bound
disabled an overall control disabling all aspects of the grid

This setting overrides all other settings if disabled = true.
disableAdd disables the ability to add members to the collection (add button and context Add are disabled)
disableEdit disables the ability to edit within the grid (edit button and context Edit)
disableRemove disables the ability to remove members from the collection (remove button and context Remove are disabled)
disableZoom disables the ability to zoom into the member
editable removes all access to the grid toolbar
enableAdd enables the ability to add members to the collection (add button and context Add are disabled)
enableEdit enables the ability to edit within the grid (edit button and context Edit)
enableRemove enables the ability to remove members from the collection (remove button and context Remove are disabled)
enableZoom enables the ability to zoom into the member
inline allows editing of the grid row in-line rather than by zooming into the member’s edit view
invisible hides the grid
maxPixelHeight, maxPixelWidth, minPixelHeight, minPixelWidth control the maximum and minimum height and width of the grid in pixels
percentageHeight, percentageWidth height and Width in terms of percentage of available space
pixelHeight, pixelWidth height and Width in terms of pixels
responsiveWidth control the width of the grid using the responsive layout concept
selectedIdBinding if a selectedIdBinding is provided, the attribute will hold the Id of the selected row - this enables user interactions based on which row is selected
showAdd show or hide the Add (i.e. new child row) control
showDeselect show or hide the Deselect row control
showEdit show or hide the Edit contol (for inline row editing)
showRemove show or hide the Remove control (for removing a child row)
showZoom show or hide the Zoom control
title the title of the grid
visible whether to show or hide the grid
widgetId an identifier for the grid - a way to uniquely identify the grid component
wrap default setting for contained widgets which controls whether the display of text should wrap (expanding row sizes) or whether text should truncate (so that only text which fits in the column width is displayed)

dataGrid properties

By default, the dataGrid widget displays with an action tool bar relevant for managing the collection. datagrids support drag-drop for ordering, provided this is allowed as per the declaration of the collection.

dataGrid declaration

Columns

Grid columns are bound to attributes of the collection member document - the document specified in the declaration of the collection. If no input widget is declared the column will use the default widget for the attribute, or the default widget for the attribute type.

dataGrid provides two types of columns containers:

  • boundColumn
  • containerColumn

A boundColumn is a column for a binding and the boundColumn properties include:

Property Description
alignment whether the column is aligned left, centre or right
binding document attribute to which the column is bound
editable controls whether the attribute is editable within the dataGrid
pixelWidth width of the column in pixels
title a column title to use instead of the attribute’s displayName

dataGrid boundColumn properties

A containerColumn provides more control over the widget type contained in the column and properties include:

Property Description
alignment whether the column is aligned left, centre or right
pixelWidth width of the column in pixels
title a column title to use instead of the attribute’s displayName

dataGrid containerColumn properties

A containerColumn can contain the following widgets:

  • blurb
  • contentImage
  • dynamicImage
  • label
  • link
  • staticImage

The widget declared in the containerColumn controls the input widget when the value is edited, in preference to the default widget.

Event handlers for dataGrid

The dataGrid widget offers the following event handlers:

  • onAddedHandler - what events to perform after a new row is added to the grid
  • onEditedHandler - what events to perform after a row is edited
  • onRemovedHandler - what events to perform after a row is removed/deleted
  • onSelectedHandler - what events to perform after a row is selected

listGrid

Views may also contain an embedded listGrid which is identical to the main list feature.

A listGrid can be used for showing collections of document instances and can be used to show loosely defined relationships, for example, if the Contact view was required to include a list of other Contacts with the same Post Code (even though no formal relationship to a Post Code document is implemented).

listGrid declaration

Property Description
autoPopulate whether or not the list results will be populated as soon as the list is due to be rendered - if autoPopulate is set to “false”, the list will not populate results until filter criteria have been provided and the filter control is actioned
disableAdd disables the ability to add members to the collection (i.e. the Add button and context menu item Add are disabled)
disabled an overall control disabling all aspects of the grid
disableEdit disables the ability to edit within the grid (i.e. the Edit button and context menu item Edit)
disableRemove disables the ability to remove members from the collection (i.e. the Remove button and context menu item Remove are disabled)
disableZoom disables the ability to zoom into the member
continueConversation whether events occurring within the scope of the listGrid activity are to be handled within the same transaction as events on the bean on which the view, containing the listGrid, is based
enableAdd enables the ability to add members to the collection (i.e. the Add button and context menu item Add are enabled)
enabled an overall control enabling all aspects of the grid
enableEdit enables the ability to edit within the grid (i.e. the Edit button and context menu item Edit)
enableRemove enables the ability to remove members from the collection (i.e. the Remove button and context menu item Remove are enabled)
enableZoom enables the ability to zoom into the member
invisible hides the grid
maxPixelHeight, maxPixelWidth, minPixelHeight, minPixelWidth the maximum and minimum height and width of the list in pixels
model the list model on which the rows of the list are populated
percentageHeight, percentageWidth height and width in terms of percentage of available space
pixelHeight, pixelWidth height and width in terms of pixels
postRefresh whether the list is automatically repopulated after the rerender event
query the query defining the results displayed in the grid. Unlike lookupDescriptions, which can use default document queries, listGrid must have a query nominated (and therefore declared in the module.xml)
responsiveWidth the width of the list according the responsive layout concept
selectedIdBinding if a selectedIdBinding is provided, the attribute will hold the Id of the selected row - this enables user interactions based on which row is selected
showAdd whether to show or hide the Add (new instance) control
showDeselect whether to show or hide the Deselect row control
showEdit whether to show or hide the Edit control
showExport whether to show or hide the Export control
showFilter whether to show or hide the Filter controls (both simple and advanced filter controls)
showRemove whether to show or hide the Remove (row delete) control
showSnap whether to show or hide the Snapshot control
showSummary whether to show or hide the Summary control
showTag whether to show or hide the Tag control
showZoom whether to show or hide the Zoom (zoom into a row) control
title the title of the listGrid (displayed above the listGrid)
visible whether or not the listGrid is visible

listGrid properties

Where a query is declared, the ability to edit individual column values will be as declared by the query unless the grid is disabled or editing is disabled using the disableEdit property.

Where continueConversation is set to “false”, listGrid events will not be managed within the same transaction as other events in the view.

For example, if a user zooms into a row of a listGrid the edit view zoomed to will display OK and Save actions by default (unless the edit view declares otherwise). Changes to the zoomed to document will be in a separate transaction to any activity on the document in the view where the listGrid is located.

Where a model is declared, population of list rows is handled by the model code. List models support paging, summaries and filtering , where filter controls can manipulate predicates to impact on the list results.

Filter parameters for listGrid

Filter parameters can be applied to the listGrid widget which will apply additional filtering (over and above any filtering defined in the applicable query).

Filter parameters can be value (for a static value) or binding (filtering the list of eligible references by the value of a binding from the document being viewed).

If filterParameters have been defined and the user creates a new document from the grid (using the grid Add action), the created document will have the filterParameter values set by default.

listGrid with filterParameters

In the example shown above, the filterParameter name ‘supplier’ corresponds to the binding of the ‘qProducts’ query column being filtered. The filterParameter binding ‘bizId’ refers to the binding in the current document view which provides the value for the filter (in this case bizId). Note that the binding does not need to be included in the view declaration to be able to be used for a filterParameter.

In the example above, the effect of filtering by binding bizId is that the listGrid will only display products from the qProducts query where the supplier column matches the supplier displayed in the view.

Event handlers for listGrid

The listGrid widget offers the following event handlers:

  • onDeletedHandler - what events to perform after a row is deleted
  • onEditedHandler - what events to perform after a row is edited
  • onSelectedHandler - what events to perform after a row is selected

newParameter

The newParameter section enables the context of one view to be passed to another view, when new documents are being created.

For example, if a view contains a listGrid which is filtered for Contacts of type Person and the user adds a row to the listGrid in that context, the fact that this new row implicitly belongs to a filtered set needs to be passed, and so the Person type value should be set by default in the new Contact. (It would be unexpected for example, to add a new row to a list of Person type Contacts which is not a Person type Contact.)

For parameters to be passed in this way, the newParameters named in the target view must match the names of the filterParameters being passed.

The name of each newParameter in the target view matches a binding in the document of the target view. The binding does not need to be present in the target view definition, but it must be a valid binding in the target document.

<newParameters>
  <parameter name="model" />
  <parameter name="type" />
</newParameters>

newParameters section

Action declaration

The action section of the view declares which actions will be available to the user and under what conditions.

Typically, scaffolded views contain the tag - this represents the group of actions Skyve deems to be valid in the specific context given the user’s privileges. Alternatively, default actions can be declared individually (e.g. OK, Save, Cancel etc.).

Skyve will automatically hide actions that are not appropriate for the user or situation (for example, if the new action is declared, but a user’s privileges do not include the create privilege for the relevant document).

Note that action buttons can be located either in the ActionPanel or using the widget within a view form, however the action itself must be declared in the section of the view.

Tip: You must declare all actions in the action section even if they will not appear in the ActionPanel.

Report actions (described below) provide access to defined report objects (for example Jasper reports) and must also be declared in the actions section of the view.

ActionPanel

The following table lists the properties for each action declaration.

Property Description
className the name of the Java action class to be executed when the button is pressed
clientValidation whether or not to perform validation in the client, prior to (i.e. to determine whether) the action should be allowed to be performed - if clientValidation is set to “false” the the action will be permitted whether “required” or other validation types may not yet be met
confirm a confirmation message to be displayed requesting confirmation by the user

If no confirmation message is supplied, no confirmation is requested.
disabled whether the button is shown in a disabled state
displayName the text which will appear on the button
inActionPanel controls whether the action button is included in the Action Panel at the top of the view

If a button is not to be displayed in the ActionPanel a button widget will be required elsewhere within the view for the action to be accessible.
iconStyleClass the icon class to use as the icon for the action using the fontawesom icon style classes - note that special action types (ok, save, delete, cancel, zoomOut, remove, download, upload, import, export) have predetermined icons - e.g. “fa fa-file-photo-o” will use the fontawesome (“fa”) style class “fa-file-photo-o”
invisible whether the action button is invisible
relativeIconFileName the filename of an icon which will be displayed together with the displayName on the button

Filenames are usually relative allowing the Skyve overriding mechanism to locate the absolute path to the file based on the context of the user.
name where multiple actions may refer to the same action but with different options, the name property distinguishes which property set declaration to use (for example, to send different parameters to the same report)
toolTip tooltip help to be displayed for the button
visible whether the action button is visible

Action declaration

The above example shows implicit actions are included using the
the <defaults> action set and the <cancel> action, but with mutually exclusive conditions. Numerous Custom actions are declared as well as a report action.

For more details see Actions.

Declaring report actions

Report actions declared in a view must reference valid reports (*.jrxml files) and are a special case of actions.

Report actions declarations can include parameters passed to the report engine (see the above example).

Report parameter declarations can be in terms of bindings (within the currently viewed document) or static values. Report parameters are matched using the name attribute with parameters declared in the report.

<report reportName="PaySheet" moduleName="time" documentName="PaySheet" displayName="Print PaySheet" visible="saved">
	<parameter name="ID" binding="bizId" />
</report>

In addition to the generic action properties, Report actions must include a moduleName and documentName attributes to specify the location of the report template file relative to the module.document package.

Report actions are not declared within role definitions in the module.xml.

View components

Skyve allows for reuse of view sections via the component widget.

The view component must be declared according to the convention, with the file name matching the declared name. The component widget then refers to that name, with the addition of a module and document (if the referenced component declaration resides in another document package).

Naming view components

In the above example, a complex view declaration has been broken up into sections - with each section defined as a component - allowing flexible re-use of the view sections.

A view declaration edit.xml may include multiple components and mix these with specific widgets and layouts as appropriate.

<tabPane>
	<tab title="Details">
		<component name="_details" />
	</tab>
	<tab title="Interactions">
		<component name="_interactions" />
	</tab>
	<tab title="Processes">
		<component name="_processes" />
	</tab>
	<tab title="Seafood">
		<hbox>
			<vbox>
				<map modelName="HarvestAreaMapModel" />
			</vbox>
			<component name="_seafood" />
		</hbox>
	</tab>
</tabPane>

In the above example, the view declaration includes components on each of the tabs, with the final tab mixing a component and a map widgets.

The component has the following attributes:

Attribute Description
binding the binding name of the association attribute which corresponds to the driving document of the component - see the association example below for more details.
document the document package where the referenced component declaration resides - it is not necessary to specify the document attribute here if the component resides within the same document
invisible whether the component is invisible
module the module package where the referenced component declaration resides - it is not necessary to specify the module attribute here if the component resides within the same module
name the name of the component declaration being referenced
visible whether the component is visible
widgetId a specific id for the widget so that the widget can be directly referenced (e.g. xhtml)

Using a component for an associated document

Consider the example where the Contact document has more than one association to the Address document - for homeAddress and workAddress - the component concept provides an alternative to the default Skyve approach of the lookupDescription and Zoom navigation.

In this case, the view declaration for the Address document can be re-used within the Contact view.

<vbox border="true" borderTitle="Home Address">
	<component binding="homeAddress"/>
</vbox>
<vbox border="true" borderTitle="Work Address">
	<component binding="workAddress"/>
</vbox>

In the above declaration, the component binding specifies the association attribute to which the included component will be bound.

Note that in this case, it is not necessary to specify the module and document since these are inferred from the declaration of the association attributes.

The alternative approach is to use widgets with compound bindings similar to the following:

<form border="true" borderTitle="Home Address">
	<column/>
	<column/>
	<row>
		<item>
			<default binding="homeAddress.streetAddress"/>
		</item>
	</row>
	<row>
		<item>
			<default binding="homeAddress.suburb"/>
		</item>
	</row>
	<row>
		<item>
			<default binding="homeAddress.postCode"/>
		</item>
	</row>
</form>
<form border="true" borderTitle="Work Address">
	<column/>
	<column/>
	<row>
		<item>
			<default binding="workAddress.streetAddress"/>
		</item>
	</row>
	<row>
		<item>
			<default binding="workAddress.suburb"/>
		</item>
	</row>
	<row>
		<item>
			<default binding="workAddress.postCode"/>
		</item>
	</row>
</form>

Not only is the component approach more succinct, but it also means that if the Address document is alterered or refactored, view layout changes can be managed in a single authoritative location.

Component substitution

A view component can be used in another document even where the component refers to conditions or other aspects which are specific to one particular document.

The component widget may declare a number of name mappings. These specify the mapping of names from the original document to the document in which the component is used.

Name mappings can be used to substitute:

  • condition names
  • server action names
  • selectedIdBinding names

Consider an example where the Address document declares a condition called showCountry and this is used in the Address view to control visibility of a country attribute. In this case, the Contact document view using the Address view component may not have that condition declared, or may have a different condition to satisfy the same basic requirement.

To map conditions from the source document to the document using the component, specify the names as follows:

<component binding="homeAddress">
	<names>
		<name fromComponent="showCountry" mappedTo="foreignSupplier"/>
	</names>
</component>

In the above example, the value of the foreignSupplier condition from the Contact document will be mapped to where ever the name showCountry exists in the original view declaration (in the Address document package).

Similarly, the names substitution may be required where the view component declares an action - in this case, the action would be declared within the document package where the component is declared (i.e. with the path to the action class being inferred by the convention of being located in the same document package).

If the component is then used in the view of another document, it is necessary to map the action name to an action declared in the document package where the component is used.

View tags (see Routing)

JSF (xhtml) pages can take advantage of Skyve view declarations through view tags. The view tag can render whole views, or portions of views as identified by a widgetId.

For more information see Routing.

Create views

In some situations, the way a document instance is created requires a different view declaration to normal editing - for example, if there is a wizard or stepped approach to creating the instance.

This situation can be handled in a variety of ways, however Skyve also supports the declaration of a view specific to the creation stage.

Create view

In the above example, the User document has a create.xml view declared as well as a general edit.xml.

Whether the create.xml view is served depends on the existence of a condition named created being declared in the corresponding document.xml.

For the above example, the create view will not be served unless the User document includes the created condition similar to the following:

<condition name="created">
	<description>Created</description>
	<expression>
		<![CDATA[isPersisted()]]>
	</expression>
</condition>

In the simple case, the condition uses the isPersisted() method - as a bean is considered to have been created once it has been persisted , however the specific logic can be determined by the developer as required.

Skyve Renderer Comparison

Skyve features the ability to dynamically change the rendering engine based on criteria specified as part of its routing. By default, it switches renderer based on the user agent of the browser. If it detects the user is using a desktop browser, the SmartClient renderer will be used, otherwise the responsive PrimeFaces renderer will be used.

The table below shows the available renderers in Skyve and their level of completion.

Note: React and React Native are in early stages of development and not available for use in applications yet. This table is not a complete list.

High Level Features

Feature SmartClient PrimeFaces JQuery Mobile React React Native Description
Session management Y Y Y Y   Ability to create, associate, expire and propagate a user session and prompt for login
Conversation management Y Y Y Y   Ability to start, associate, propagate and reclaim conversation states in Skyve views
Zooming management Y Y Y Y   Ability to manage n level zooming across the domain’s aggregations, within and outside of view conversations
Security management Y Y Y Y Y Guarding against XSS, injection attacks and applying best practice network and application security through sanitisation, escaping etc
Permission management Y P       Ability for the view to react automatically to the user permissions by showing, hiding and altering different view mechanisms
Scope management Y Y       Ensuring that view elements issue correct data retrievals based on the current user scope settings
Request management Y Y       Ensure requests are issued asynchronously and synchronously as required, orchestrating multiple requests, and managing long running and unresponsive requests
UI Dirty management Y         Ability to detect data changes in the UI widgets through all request/responses in a conversation and warn when a user is about to perform a gesture that will discard their unsaved changes
Routing Management Y Y       Ability to inject front end markup/logic into existing Skyve views through ‘native’ mechanisms and remain integrated with the Skyve view plus the ability to hijack a view completely through the Skyve routing mechanism and generate pieces of the defined Skyve views as an assembly strategy if appropriate.
View Layout Y Y Y Y    
Data Grid Y Y Y Y    
File Upload Y Y        
Content Upload Y Y        
File Download Y Y        

View Controls

Feature SmartClient PrimeFaces JQuery Mobile React React Native
label Y Y Y    
blurb Y Y      
button Y Y Y    
checkBox Y Y Y    
colourPicker Y        
Content picker Y Y Y    
Date picker Y Y Y    
Date/time picker Y Y Y    
Drop-down list Y Y Y    
geolocator Y        
geometry Y        
inject Y        
spinner Y Y Y    
listMembership Y Y      
password Y Y      
richText Y        
radio Y Y      
spacer Y Y      
textArea Y Y Y    
textField Y Y Y    
Type-ahead Y Y Y    

List Grids

Feature SmartClient PrimeFaces JQuery Mobile React React Native
List Grid Y Y Y Y  
Image Thumbnails Y Y      
File Thumbnails Y Y      
Column filtering Y Y      
Column sorting Y Y      
Advanced filtering Y        
Export Y        

Desktop only features

The following features are only available for the SmartClient renderer, as they do not provide a good end user experience to try to implement on a touch device or low resolution screen.

  • Prompt on expired session
  • Global content search
  • List Grid features
    • Advanced filtering
    • Map based filtering
    • Tagging
    • Snapshots
    • Flags
    • Exporting

⬆ back to top


Next Routing and rendering
Previous Bizlets