.. _FormPanel:

Form Panel
^^^^^^^^^^

The Form Panel is one of the most frequently used components in TopBraid EDG.
It is used to display and edit the selected asset, property by property.

The list of properties that the form panel is showing depends on the properties that have been
declared for the classes/shapes of the currently selected asset.
In particular, the layout of properties is based on the (SHACL) property shapes, their ordering
and property groups, see :ref:`PropertyGroupsPanel`.

In some cases, multiple view shapes are available for the given asset.
In those scenarios, a drop down box appears in the upper right corner,
allowing users to change perspective.
If you are an ontology editor, you can define your own view shapes using the :ref:`NodeShapesPanel`
and assign them to applicable classes using `target classes` or `applicable to classes`.

.. hint::
   If you cannot see all properties of your asset, you can make more properties visibly using
   the settings in the upper right corner of the form panel.
   Details on these setting are below.
   If you are familiar with Turtle you may also find the :ref:`SourceCodePanel` useful to get a
   more detailed, technical view of an asset.

The Form Panel operates in two modes: *View mode* and *Edit mode*.
If you have edit permissions and the asset is editable in the current asset collection type,
you can click the *Edit* button to switch the whole form into edit mode.
Alternatively, you can click on any property label on the left of the form widgets to
turn just that property into edit mode.

.. note::
   Don't forget to press **Save Changes** to complete editing.
   Changes made on the form will otherwise not be applied to the data.
   If you are unsure about making an edit, either create a *workflow*, use **Preview**
   to check the impact of your change, or **Cancel** the edit.

To ensure data quality, assets should always fulfill the constraints defined by the classes, shapes and properties
from the underlying ontology (schema).
These constraints are always checked before you can assign the changes, with an option to either
continue editing or proceeding without further changes.
In addition, you may want to activate **Show problems and suggestions** in the settings of this panel,
to have the constraints also displayed when the form is in *view mode*.

.. note::
   Not all property values are editable.
   For example, unless you are in a workflow that is configured to edit multiple asset collections,
   none of the property values that are from included asset collections can be edited.
   Also, inferred values (that are computed automatically) cannot be edited.

**Toolbar Buttons**

* **Available actions for this**
  opens the :ref:`ContextMenu` for the current asset.

* **Explore**
  opens the :ref:`ExploreMenu` for the current asset.

The following buttons are only visible if you have edit permissions on the asset collection
or workflow, and the asset is editable for the given asset collection.

* **Modify**
  opens the :ref:`ModifyMenu` for the current asset.

* **Edit**
  switches the whole form to edit mode.

* **Cancel** is visible when editing is in progress, to return to view mode without saving changes.

* **Preview** is visible when editing is in progress and shows a :ref:`PreviewDialog` simulating the change before it's actually applied.
  This can give a useful perspective on the implications for technical details.

* **Save Changes** is visible when editing is in progress and applies the changes to the asset collection (or workflow).
  This will perform constraint validation to make sure the edits do not introduce obvious errors.
  If violations are reported, users may still elect to proceed.

.. hint:: In general, it is recommended to leave an asset collection in a state where there are no or very few
   constraint violations.  However, it is sometimes necessary to get into an intermediate state where certain
   violations are required until other parts of the data have been updated too.
   In an ideal set up, such inconsistent states should be limited to workflow only, so that
   they don't break the production copies - remember that other asset collections may include
   your asset collection, and errors may thus propagate.
   Breaking edits to production copies can be acceptable in scenarios where you have multiple
   EDG instances, such as a development instance, a staging instance and then the final production instance,
   as long as they are filtered out before they reach the production instance.

**Settings**

* **Also show properties that have no values**
  is useful in *view mode* when you want to understand which other properties exist beside those that
  are showing because they have values.
  If activated, you can more quickly click on individual properties that do not yet have values to start editing.

* **Merge properties from all suitable view shapes**
  will show all properties regardless of which view shape they have been defined in.
  This often gives a more complete picture, yet may show too many values for some users.

* **Also display undeclared property values**
  will also show any properties that are not mentioned in any of the applicable classes and shapes.
  These fields will not be editable, because the system doesn't "know" what value types such properties
  should have, and what other constraints they should fulfill.
  If you ever need to edit them, use the :ref:`SourceCodePanel`.

* **Display descriptions of the properties**
  will also show the descriptions, based on either ``sh:description`` of the property shape,
  or ``rdfs:comment`` on the property itself.

* **Enter log message when submitting edits**
  will open a dialog when **Save Changes** is clicked, allowing you to enter a custom explanatory message
  that will go into the log of the :ref:`ChangeHistoryPanel`.
  By default, only a standard log message will be used.

* **Display property groups as tabs**
  switches to a tab-based layout where each property group gets its own tab.

* **Show problems and suggestions**
  performs (SHACL) constraint checking and most other algorithms that also appear on the
  :ref:`ProblemsAndSuggestionsPanel`.
  In constrast to that panel, it will here only validate the currently selected asset.


**See Also**

* :ref:`ContextMenu_OpenOnNewForm`
* :ref:`Manage_DefaultLanguage`
* :ref:`PropertyGroupsPanel`
* :ref:`SourceCodePanel`

**Further Reading on Form Panel**

* `Form Generation using SHACL and DASH (External Link) <https://datashapes.org/forms.html>`_
* :ref:`ext_script_based_viewers`

**Further Reading on TopBraid**

* :ref:`introduction`