;

Configuring Forms in Open Source

7 min

To alter the layout and the content of the forms in Essential is a relatively easy task, enabling you to customise things like re-order how form fields are presented and change the field labels and tooltips as required. However, we recommend that you read the potential issues section below before proceeding.

How are the Form Layouts Controlled

The layout of the forms in Protege is controlled by the .PPRJ file which forms part of the configuration. Even if you are using a database backend to store your model, you will need a .PPRJ file in which to store the configuration of the project. This configuration controls not only the actual graphical positioning of all the controls on the form but also any particular configuration of widgets such as the Graph Widget and the AutoText Widget.

When running in client-server mode, users cannot make changes to the forms – the Forms tab just isn't available. Also, any attempts to use the API, e.g. via the Protege Script tab, to change the forms (which is possible) will not work in client-server mode.

Updating an Existing Project File – Forms Tab

For small changes to the layout, the easiest way to update the layout of a form is to use the Forms tab, make your changes and save the project. If you need to update a project that is running as a server, you will need to stop the server and open the project in stand-alone mode. This is also the case where you need to run a script that will update Forms elements (e.g. AutoText configuration).

Updating the Forms Offline

To make any change to how the user interface controls are laid out on the forms, the Forms Tab is the only practical solution. In theory, the API could be used – e.g. via scripting – but accurate positioning would be difficult and the script would be very fiddly to write. Indeed, the Forms Tab has several useful things to help speed things up, such as the "Layout Like…" button, which lets you use a form that you're happy with as a template for laying (or re-laying) out a form that you're working with.

The only problem with this approach is that as mentioned above, you need to take any server-based projects offline while you make your changes. Not serious for minor updates but this could be a long time if a large number of changes need to be made – and also means that the work has to be re-done for each project that you visit. However, there is a work-around which enables you to apply a complete project of form layouts to another project that has exactly the same meta-model. With this, an existing project can be edited to re-layout the forms offline and the resulting configuration put back into a server-based project with minimal downtime. The workaround is to swap an updated .PPRJ file into a repository configuration without touching the model or meta model.

The method:

  • Copy the .PPRJ and its meta model and instances (either the database or the PINS and PONT files)

  • Open the above .PPRJ file offline from the server in Protege.

  • Do a File->Save As and save a new version.

  • Make all required changes and save the project.

  • Stop the server

  • Take a backup copy of the .PPRJ file.

  • Copy the updated version (from step 4) onto the original .PPRJ file so that it has its original name (from Step 1)

  • Restart the server and all the Forms should have received the correct layout updates.

Potential Issues

  • Any changes to instances that are using the Graph Widget will lose the details of the layout of that form.

    • In practice, this is not a problem as in client-server mode, these details cannot be saved anyway.

  • Changing the meta-model while the Forms are being edited off-line will get the project files out of synchronisation

    • Apply some governance to dissuade/stop others from editing the meta-model until the re-layout has been applied

    • In such cases, the updated project file will have to be re-copied and the layout changes re-started.

Updated 31 October 2023

Contact Us