A component is a collection of fields, field-on-pages, pages, business view and field mappings which can exist independently of a form. Components can be added to any form in any project and are constructed in exactly the same way as you would construct a form. Using components is an ideal way to promote reuse of form elements between forms projects.

Components are always created in the GLOBAL project which appears at the bottom of the Business Elements section of the hierarchy tree.

Component Types

When creating a component you can choose one of the following component types:

Part-page component

This is the default component type. It is made up of a set of field-on-pages with their associated fields and scripts which can be inserted onto a form’s page (from the design area menu or toolbar). This type of component does not have any pages. For example, you may have a standard set of field-on-pages used to represent a person’s address. These could be constructed as a part-page address component and inserted into forms wherever address information is required.

One-or-more-pages component

This component type is made up of a sequence of one or more pages which can be added to a form at page level (from the page control area menu). For example, you may want to have a standard sequence of user registration pages which are used in a number of forms. These could be constructed as a one-or-more-pages component and inserted into the forms in question in the appropriate position.

Fields-only component

This component type is made up of fields only. It has no visible elements. A fields-only component can be inserted onto the form itself (from the form menu or toolbar). For example, you may have a standard set of fields which are used in different ways in different forms but are always mapped in the same way to the same resources. Such a set of fields may be created as a fields-only component and then the Ebase users of the various forms have the flexibility of placing them on the form pages as required with the benefit of all mappings already being in place.

All types of components will also typically include any associated fields, business view and field mappings.

Linking vs. Embedding Components

A component may be added to a form in one of two ways:

Embedding

If a component is embedded into a form, a copy is made of all the constituent elements of the component and inserted into the form. From this point hence, the component becomes just part of the form and may be freely modified by the Ebase user. Any changes to the component will not be reflected in the forms into which it has previously been embedded.

Linking

If a component is linked into a form, the form simply acquires a reference to the component. In this case, the Ebase user may not change any aspect of the component in situ, however, any changes made to the original component via the component editor can be deployed to any form linking to it by clicking the deploy changes button on the component toolbar. When editing a component, the Ebase user may save the component without impacting linked forms. When the Ebase user is happy with the component, s/he may deploy that component. Deploying a component causes any changes to be propagated to all forms linked to it. When asked to deploy component changes, the component editor will warn you which forms are currently linked to the component and whether any of them are currently being edited. Changes cannot be deployed if any of the linked forms are currently open for editing.

Converting Linked to Embedded

An Ebase user may, at any time, convert a linked component to an embedded component at which point, the form acquires a local copy of the component, all change propagation benefits of linking are relinquished and the Ebase user is free to change the local copy of the component at will. Conversion from embedding to linking is not possible in the same way although the Ebase user is free to delete all elements of the component and recreate the link.

Component Name Prefix

When adding any component to a form, you are required to provide a name prefix. This is necessary to enable multiple instances of the same component to be inserted onto the same form and to retain naming uniqueness. The prefix may be anything meaningful to the user, for example, if linking two instances of an address component, one for billing address and one for delivery address, sensible prefixes may be “billing_” and “delivery_”. These are prefixed to all names in that instance of the component within the form (along with the component name itself) to aid recognition of where any individual field, field on page, page or group came from.

So, for example, if we have a component called “ADDRESS” which contains a field called “FIRST_LINE”, and we insert this component into a form supplying the prefix “DELIVERY_”, the full field name in that instance of the component in the form will be “DELIVERY_ADDRESS__FIRST_LINE”. The Ebase Designer will ensure uniqueness of these prefixes within a form and will warn you if a duplicate has been detected.

This mechanism also means that any scripts used in the component which refer to fields in the component will function correctly if inserted into a form multiple times since the script will know which instance of the field it is referring to even though the script is itself global. (See Working with FPL Scripts for more information)

Deleting Components

Components may only be deleted if they are not linked into any forms. If you chose to delete a component, Ebase will notify you of any forms which are currently linking to the component. If you are happy to proceed with the deletion, all existing links will be automatically converted to embeddings to remove any dependency on the component. The component may then be safely deleted.

Running Components

Components can be run in isolation just like running forms. This causes the component to be temporarily embedded into a dummy form and run in a browser to allow the Ebase user to test the component’s behaviour before adding it to forms or deploying any changes.

Note: Any scripts which refer to elements outside the component will not work in this context.

(See Working with Components for more information)

Global Scripts and Messages

Components may be associated with global scripts only. Scripts may be used in exactly the same way as for forms. Typically these scripts will only refer to entities (such as fields, pages and resources) within the component. When the component is inserted onto a form, any references in the script will be applied to the elements of that component instance only.

The following diagram shows a part-page component inserted onto a page twice, once with prefix PERSON1_ and once with prefix PERSON2_. The script attached to the PERSON_1_TAX_CALC__EARNINGS field will only update the PERSON_1_TAX_CALC__TAX_TO_PAY field. The script attached to the PERSON_2_TAX_CALC__EARNINGS field will only update the PERSON_2_TAX_CALC__TAX_TO_PAY field. This will happen automatically since the script knows which component instance it belongs to and will only work within that component’s context.

Global scripts may also be overridden in the local project by creating a local script with exactly the same name as the GLOBAL script. Additionally, a global script can call a local script using the callscript FPL command. Ebase will always look for a script in the local project first and, if not found, it will look in the GLOBAL project. This should be done with care since, in a local script, all references to field names must be as they appear in the form itself… not as they appear in the component. So, for example, if the script in the above example were to be overridden in the MYFORM’s local project, the action for the first component instance would be:

set PERSON_1_TAX_CALC__TAX_TO_PAY = PERSON_1_TAX_CALC__EARNINGS * PERSON_1_TAX_CALC__TAX_RATE;

The rules for how references to fields/pages/groups/tables etc are resolved during script processing are as follows:

If the script is global and is part of an action originating from a component, the system first applies the component prefix to the referenced object and checks for its existence. If it exists, it is used. If it does not exist, the system checks for the existence of an object with the unprefixed name. If this exists, it will be used under the assumption that the intention is to act on a field outside the component (see below).
If the script is global and is part of an action which has not originated from a component, all object name references will be resolved exactly as named in the script. No prefixes will be applied.
If the script is local to the form, it is irrelevant whether or not it has been called as part of an action originating from a component. All object name references will be resolved exactly as named in the script. Note that as a result of this rule, it is possible to change from the “component context” to the ‘’form context” by using the callscript FPL command to call a local script defined in the form’s project.
If a global script refers to fields outside the component, it will not be testable in the context of the component, but will work as expected once inserted into a form provided that all elements referred to in the script already exist in the form. Exceptions to this rule may arise if the same field name appears both in a component and in a form into which it is inserted. So again, the general rule is, if a script is called as part of a component, the fields it refers to will be prefixed with that component instance’s prefix. IF they are not found, it will look for them on the form without the prefix. If the script is called from a non-component-sourced field or page, it will not apply any prefix.

Scripts may also refer to global messages. Messages in the GLOBAL project automatically start from 100000 (as opposed to 1000 in any other user-defined project). This is to avoid conflict with project local messages.

Note:When navigating to a script editor from a linked or embedded component, this will automatically show the GLOBAL script (unless the script has been overridden in the local project). Changing this script will impact all forms currently referencing that script (via inserted components) with immediate effect. This is the same as changing any other shared resource and should be treated as such when considering making changes.

(See Working with FPL Scripts for more information)

Static and Dynamic Lists

Components can include both static and dynamic lists in exactly the same way as for forms.

(See Working with Lists for more information).

Business Views and Field Mappings

A component can have a business view associated with it. Fields in a component may be mapped to resources in this business view in exactly the same way as they would be in a form. This is referred to as component-level mapping. When a component is inserted into a form, the fields may also be mapped to resources in the form’s business view. These are referred to as form-level mappings.

(See Working with Business Views and Field Mappings for more information)

Component-level mappings

Component-level mappings act within the context of an instance of a component only. When a component is inserted onto a form, the component’s business view is added to the form but is only available to that instance of the component and can not be edited from within the form. Any actions set on elements in the component will act only on field mappings as set up in that component.

For example: A component contains a table whose columns are mapped to a database resource within the business view set on that component. The table also has a FETCHTABLE command as a before table action. When executed in the context of the form, this fetchtable will act based on the mappings set up in the component and will fetch data from the resource in the component’s business view. Only the table in this instance of the component will be updated. Any other instances of this component will be unchanged.

Form-level mappings

Once a component has been inserted into a form, its fields may additionally be mapped to resources in the form’s own business view. The result is identical to that for regular form fields. This means that if an action, such as a FETCH <resource>, is performed from an element in the form which is not part of the component, the event will update all fields mapped to this resource, including those inserted from the component.

The diagram below shows a component called ADDRESS which has a business view, BV_A. The business view contains a single database resource, DB_A which has 2 fields, POSTCODE and FIRST_LINE. The ADDRESS component’s POSTCODE and FIRST_LINE fields are mapped to the DB_A resource’s POSTCODE and FIRST_LINE fields respectively. The POSTCODE field has the immediate validation option and fires an on change event which performs a fetch on the DB_A resource. This means that when someone enters a postcode, the FIRST_LINE value will be fetched from the DB_A resource.

The ADDRESS component has then been inserted twice onto PAGE_1 of the MYFORM form. Once with a prefix of DELIVERY_ and once with a prefix of BILLING_. With this form, if someone were to enter a delivery address postcode, only the delivery address first line will be populated. If someone enters a billing address postcode, only the billing address first line will be populated. This is because the mappings have been made at component level.

On top of this, the BILLING_ADDRESS__POSTCODE and BILLING_ADDRESS__FIRST_LINE fields have also been mapped, within the context of the form, to the form’s business view, BV_B. The form’s PAGE_1 has a before page action which pre-populates the billing address based on some prior information by performing a fetch on the DB_B resource. This fetch command will only act on the mappings made in the form and so will only update the billing address’s form level field mappings.

(See Working with Components for more information)

Form Level Actions On Component Business Views

For scripts at form level, it is also possible to act on resources in component business views by qualifying the resource name with the full component prefix. For example, form MYFORM (in the figure above) could invoke a FETCH action on the DELIVERY_ instance of the ADDRESS component’s resource DB_A as follows:

fetch DB_A ( DELIVERY_ADDRESS );

This script command qualified the resource name with the component’s prefix with which it was inserted into the form. This will have the same effect as invoking the FETCH from within the component. The explicit nature of this qualifier implies that this syntax is only relevant in scripts local to the form and will be meaningless in a component since we don’t know what the prefixes are going to be!

Component prefixes can be displayed in a form by clicking the mappings icon then clicking Component form field mappings.

Component Level Actions On the Form Business View

When executing a command against a business view from a component (e.g. fetch, sendmail etc) the system checks whether the script containing the command is local or global. For local scripts, the form’s business view is used, for global scripts the component’s business view is used.

Editing Forms Containing Components

When editing a form which contains linked component instances, each linked component instance will be treated atomically (i.e. as a whole, not as individual fields/pages). Any action requested on a subset of a linked component instance will result in Ebase asking whether the action may be applied to the entire component. If this is not appropriate, the action may be aborted. So, for example, an attempt to move a subset of a linked component instance on the page will result in the entire component being moved, or, an attempt to group a subset of a linked component instance on a page will result in the entire component being grouped (provided that the component does not already incorporate some grouping) and so on.

This atomicity also applies to deleting a component instance. If a subset of a linked component is selected for deletion, Ebase will show you a list of all entities involved in that component instance and prompt you whether you wish to delete the entire component.

The majority of editable properties of elements of a linked component will appear read-only in the form since these are only configurable in the component itself.

Page-type components linked into a form will appear completely read-only within the form and will again be treated atomically. Exceptions to this rule are the following attributes which can be changed locally in a deployed component:

Template sheet id on group or table
Table backing resource

Note: A form containing embedded components will look and behave no different to a standard form.

Forms Only Features

There are some features which are only relevant in the context of a runnable form and are therefore not available for configuration on a component. These are:

Templates
JSPs
Print layout

Other features may be configured in a component but may be overridden in a form. These are:

Business Views
Field Mappings
Column layout
Grouping
Group alignment

Field mappings, templates, column layout (left right or full width) group alignment and additional field grouping may be applied to components once they have been inserted onto a form. Wherever possible these settings will be preserved across component change deployments with the following exceptions:

New fields, field on pages, pages and groups will adopt sensible defaults where possible but these are not guaranteed and may need reconfiguration.
Fields, field on pages, pages and groups which have changed their unique identifier are not guaranteed to preserve these settings and may have to be reset.
Settings such as column layout and field grouping which are set explicitly on the component itself will override anything set in the form.

See Working with Forms for more information)

Import and Export

Components themselves may be exported and imported in exactly the same way as you would export and import a form.

When exporting a form which contains links to components, the export window offers the option to include all linked components. If selected, all referenced components will be included in the export. If not selected, forms will still run on the destination system and the linkage definitions will be maintained however the ability to modify and update the components will be lost until the components themselves are reinstated.

(See Using Import and Export for more information)

Copying component fields into tables

When column fields are added to a table, it is possible to specify that existing form fields should be copied. When non-component fields are specified, the fields are simply copied and all field attributes can be changed on the new column field. However, when a component field is selected, a linkage between the component field and the newly created table column field is maintained, and most attributes of the new column field cannot be changed. If the component is then re-deployed, any changes made to the copied fields are deployed to both the instance of the component fields in the form and also any copies that have been included in tables.

This feature makes it possible to create fields-only components that represent data structures, deploy these to forms, then copy the component fields into tables. When changes are made to the underlying component, these changes are propagated to the copied table column fields when the component is deployed.