Dynamic Catalogue - Form Elements

Modified on Tue, 20 Aug at 10:01 AM

The plugin offers the ability to load field descriptions from a client catalog or a URL and provide them as pre-configured elements in the designer. This is useful, for example, when you want to flexibly save form templates to use them in any client of the system. Sometimes, it's also useful for reusing specifically configured fields that are frequently needed.

Inhalt

Configuration of the Plugin-Bundle-Properties

key

mandatory field

meaning

com.xima.custom.catalogue.name*

yes

after a "catalogue" has been stored in "Files & Templates" -> "Files"
The name of the catalogue needs to be put in here.

com.xima.custom.catalogue.url

If a URL is provided, catalog information will no longer be retrieved from the client's resources but from the specified URL.

When loading the catalog, the URL is then constructed from the values of the parameters: com.xima.custom.catalogue.url + com.xima.custom.catalogue.name.

Missing slashes are automatically added.

If catalog needs to be loaded via Files and Templates, the plug-in can only be used as a client plugin. This means the plug-in must be installed on the client.

For using catalogs that are linked via URL, the plug-in can be used as either a system plugin or a client plugin.

Using the catalog as a client resource

First, the "dynamic catalog" is installed in the desired client.

Here are two files that are provided with the plug-in by default. The files named catalogue.json and form4676.json will be installed in Files & Templates > Files in client, where the plug-in was previously installed.

Any new catalog that you wish to add must also be inserted there, and the catalog description is provided in JSON format.

While the name of the file must be entered in the plugin settings under Client > Plugins at com.xima.custom.catalogue.name*.

one the right side next to "catalogue.json" the file name can be entered.

The description of the catalog is provided within the file and in the form of a JSON array. The metadata for the desired catalog is entered here. It is possible to reference multiple JSON files within a single catalog file. Catalog file must contain at least the metadata "name" and "id."

For the provided sample files, this would look as follows:

catalogue.json is the file, which contains the description of a catalog. catalogue.json now contains the metadata for the JSON file form4676.json.

Metadata for form4676.json must be stored in catalogue.json as follows:

[
 {
 "name":"basic elements", /* name, as it appears in the form designer under external catalog */
"id":"form4676.json", /*the reference to the catalog-data*/
"parse":"form" /*translation into a form */
 },

/*in the following, an own created catalog by user: */
 {
 "name":"I am catalog II",
 "id":"elements_2.json"
 }
]

For "name" the name of the element list needs to be entered, as it is shown in the designer under "external catalog."

The "id" must be unique and is the name of the file where the element descriptions for the form fields must be stored.

For using this example in your catalogue.json, it's necessary removing the comments that contain this /* ... */ .

The element description of the JSON file

To offer an element of the form as a catalog field, it must have a label and be of one of the following types: Text field, Text area, Selection, Checkbox, or Upload.

Regarding the example of the two JSON files that belong to the plugin, the content of form4676.json will be discussed here. This is because the element description refers to form elements. Specifically to the types text field, textarea, selection, checkbox or upload. Other JSON contents cannot be recognized and processed by the plugin. Therefore, the following points will relate to descriptions of the elements of a form.

Parameters within the catalog description:

key	required field	meaning
name	yes	shown name in the designer
id	yes	unique identifier of the catalog/ data name the mandantresource
type	no	"form" - Using a form created in FORMCYCLE as an element list "url" - loading an element description via URL
form	if "type" is a form	ID of the form to be used as an element list
url	if "type" is a url	address from which the element description should be loaded
parse	no	"form" - must be specified if the element description is a form description from the FORMCYCLE Designer (using the ‘Save Form Locally’ option)

Use existing form as an element description

If an existing form is to be used as the basis for the catalog, the catalog description can also include the information 'type' set to 'form' and the 'id' of the form.

[ 
  { 
    "type":"form", 
    "name":"Formular", 
    "id":"formular_1008", 
    "form":"1008" 
  }
]

In order for the metadata and the form to be parsed and translated, it is necessary to upload the JSON file under Client > Files & Templates > Files.

This can be easily generated from a form. Below is a step-by-step guide for creating a JSON file from a form.

Guide to creating a JSON file from a form

To create a JSON file from a form, you must either switch to an existing form in the form designer or create a new form. In this new form, you need to drag and arrange the desired fields in the designer according to how they should be saved and downloaded later.

The form must now be exported from the form designer.

Under Export, the option 'Free Form Designer' is available

At this point, a pop-up window will appear, providing the option to choose between downloading only the form or the workflow.

Here, it is possible to save a form separately from its workflow. The file is output in JSON format. 'Web Form Only' is used for the dynamic catalog.

The web form that is to be exported will be saved as a JSON file, which is the format needed for the dynamic catalog. This JSON file can now be uploaded to the Client > Files & Templates section.

You now need to enter the metadata of your form in JSON format into a file, such as catalogue.json, so that the external catalog can display the form fields used in the form.

In the end, it should look like this:

To view the element list in the form designer, you need to click on the 'External Catalog' tab. The elements of the form will then be displayed, provided that the metadata has been previously written to the catalogue.json file.

Note
A required field shown by an external catalog will be displayed in red. All other fields will be shown in black

Load element description via URL

To load an element description via a URL, you first need a file in JSON format that contains the metadata of form descriptions. Formcycle does not accept other JSON files.

As an example, this URL contains JSON with metadata for other catalogs.

https://customer.formcycle.eu/index.php/s/CDOc2axLSJwXU5O/download

The URL must be split into two components: the base URL and the catalog name. As shown in the following example, the catalog name is: CDOc2axLSJwXU5O/download.

The base URL refers to the URL up to the name of the JSON file, while the name of the stored JSON file should be placed in com.xima.custom.catalogue.name*

The base URL, which is entered in the com.xima.custom.catalogue.url property, is combined of the value from the com.xima.custom.catalogue.name parameter. This results in the complete URL under which the catalog description is loaded.

Using an external catalog via a URL

If the catalog description is to be loaded via a URL instead of through client resources, a valid base URL for the catalog files must be specified for the com.xima.custom.catalogue.url property. The description is provided according to the schema shown in point 3.