In Verne – Catalyst Cloud a Component is a reusable piece of XML configuration that provides a standardised piece of functionality. It becomes a building block to create succinct forms without needing to provide additional complex rules as the component abstracts the functionality.
When a new project is created a number of standard components will be added to the project. These can be left as is or customised to suit the projects needs.
The standard components will exist in the projects common module under the /components/ directory.
Component Example
The following Accordion component demonstrates the features of a component.
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<catcfg:Configuration xmlns="http://www.fostermoore.com/schema/cat-ng" xmlns:catcfg="http://www.fostermoore.com/schema/catcfg-ng">
<components>
<component name="Accordion">
<parameter name="shortCode"/>
<parameter name="boxIfSingle" default="false"/>
<parameter name="handler" default="/components/tabcontainer/TabSupport.groovy"/>
<box shortCode="${shortCode}" widget="accordion">
<value name="boxIfSingle" value="${boxIfSingle}"/>
<eventListener event="*" resourceName="${handler}" methodName="onEvent"/>
<rule scope="*" resourceName="${handler}" methodName="onRule"></rule>
<slot name=""></slot>
</box>
</component>
</components>
</catcfg:Configuration>Component Name
Each component needs to have a unique name. This is used to reference the component when building up a form or another component.
Parameters
Components can define parameters that will alter their effect. Parameters can have defaults or are otherwise required to be provided when the component is used.
The above example has three parameters as follows:
- shortCode: No default is provided so this is required. In this instance it will map to the shortCode of the box that displays its content as an Accordion:
- boxIfSingle. Defaulted to “false”. Disables the Accordion behaviour if there is only a single child element within it.
- handler: Points to a resource that will handle events and rules for the component.
Argument Resolution
The above example also shows the how the passed in parameters are used in the Component. The parameters passed in can be used as variables within any XML attribute by using the ${PARAMETER} syntax.
e.g.,
<box shortCode="${shortCode}" widget="accordion">
<eventListener event="*" resourceName="${handler}" methodName="onEvent"/>Event Listeners and Rule Handlers
Components encapsulate their functionality with groovy handler objects that live within the VFS. Typically the handler will sit beside the XML component.
Events and rules are the components opportunity to react to changes in the Service Transaction and user input. Both allow the ability to define business logic.
Event Listeners and Rule definitions can be configured to either react to specific rule scopes/event types or react to any using the "*" wildcard.
The above example shows both a rule and an event listener that will route all rule executions and events through specialised methods. In this example all events will enter the handler through the ‘onEvent’ method and all rules will enter the handler via the ‘onRule’ handler.
Each method on the handler needs to have a single argument of type ExecutionVariables. The ExecutionVariables object allows access to the event, current view node, service transaction and more. See the full documentation SOMEWHERE.
Slots
Components can have any number of slots. The Accordion example has only a single unnamed slot. The unnamed slot is the default.
Slots can have default content. Default content can be overridden by specifying slot content when using the Component.
For a detailed discussion on the Slot see the Service Form Item Slot documentation.
Component Usage
To use a component within a form, fragment or component it is first required to map additonal namespaces to the configuration file.
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<catcfg:Configuration xmlns="http://www.fostermoore.com/schema/cat-ng"
xmlns:catcfg="http://www.fostermoore.com/schema catcfg-ng"
xmlns:component="http://www.fostermoore.com/schema catcfg-ng" xmlns:slot="http://www.fostermoore.com/schema/catcfg-ng">The component namespace is required to include a component. The slot namespace is only required if adding content to a named slot.
To use the component within the configuration use the component namespace followed by a colon and the name of the component. The following example shows the usage of the Accordion component.
<component:Accordion shortCode="addressAccordion">
<component:Tab textKeyPrefix="professionals.address.residential" shortCode="residential">
<component:Address arrayName="residentialAddress" careOf="false" domainName="ResidentialAddress" textKeyPrefix="residential.address"/>
</component:Tab>
<component:Tab textKeyPrefix="professionals.address.postal" shortCode="postal">
<component:Address arrayName="postalAddress" careOf="true" domainName="PostalAddress" textKeyPrefix="postal.address"/>
</component:Tab>
<component:Tab textKeyPrefix="professionals.contact.details" shortCode="contactDetails">
<component:Telephone textKeyPrefix="professional.telephone"/>
<component:Mobile textKeyPrefix="professional.mobile"/>
<component:Email textKeyPrefix="professional.email"/>
</component:Tab>
</component:Accordion>This shows three Tab components being added inside the Accordion. These three components will all be put into the default (unnamed) slot of the Accordion component.
The result of this is that an Accordion is displayed with 3 child items. The Accordion component handles the display of the showing only one child at a time as the user progresses through the Accordion.
The values for component parameters are specified by adding them as attributes when including the Component.
If multiple slots are defined within a template then it is necessary to be more explicit about where the content should go. In this case use the slot namespace prefix to specify the name of the slot.
<component:SidePanel shortCode="detail">
<slot:default>
<!--Main panel content would go here -->
</slot:default>
<slot:buttons>
<!-- replace the buttons slot here -->
</slot:buttons>
</component>
