Pages and Layout Components

This section outlines the layout of the Instance page produced by the trellispark FormBuilder service.

The subheadings in this document correspond to the subfolders/components inside the UX-WASM-Components project.

Pages/Instance

The Instance page uses the AuthenicatedLayout to setup the TelerikNotification cascading component and initialize the TelerikRootComponent within which the page will be rendered.

If the user attempts to open the Instance page without being authenticated, they are immediately re-directed to the index page of the UX-WASM-xxx authentication websites so that the user can be authenticated.

The Instance page determines the overall structure of a dynamically rendered page by controlling the placement of the following top-level Blazor components located in the Layout folder:

  • Header
  • CommandBar
  • Navigation
  • TabBar
  • Footer

IMPORTANT NOTE: Navigation isn’t its own component and is instead built directly into the Instance page to provide a rich and flexible left-hand navigation.

The Instance page uses the CurrentUser service to determine whether to display the Navigation and the CurrentInstance service to determine which data instance should be displayed.

The Instance page also uses the FormBuilder service to construct a user experience which combines the required version of the instance data (latest by default) and the FormDefinition required to display it. The MyInstance parameter passed to Header and InstanceBuilder components on this page is the net result of the FormBuilder service defining a user experience to be rendered.

The Navigation portion contains the left-hand navigation and list all applications the logged in user has access to along with their bookmarks (if they have any). The navigation can also be expanded/collapsed by selecting the hamburger menu icon in the top left. Next to the hamburger menu icon will be the Form Name that’s currently loaded along with a Learn More icon which when selected will display a popup window that contains all help related to the page/tab that’s currently open.

Layout/Header

The Header component controls the placement of the following UX components:

  • Logo
  • Layout\Breadcrumbs
  • UserManager

Header layout; logo is to the left, breadcrumbs are in the middle, and user manager is to the right

The Header component is passed a parameter MyInstance that determines which instance data is being displayed on the page.

The Logo region is just an image that displays the branding logo. To change the displayed logo image, replace the logo.png file in the wwwroot folder of the WASM Client project.

Graphical user interface, text, application  Description automatically generated

The Breadcrumbs component is used to render the Instance Hierarchy and provide clickable links to ancestors of the current Instance. The MyInstance parameter is passed into the Breadcrumbs during initialization. The Breadcrumbs also displays the status of the Instance record currently loaded to the right of the clickable links.

The UserManager region displays a user icon with notification icons if the user has any pending alerts and the name of the user that’s currently signed in. The UserManager region is also a dropdown list that includes the following options:

  • My Profile – Opens a popup window to edit user specific settings.
  • Alerts – Opens the Layout/Alerts component. Icon will glow red if there are pending alerts.
  • History – Opens the Layout/History component.
  • Sign Out – Signs out the user and returns them to the Index page.

Layout/Breadcrumbs

The Breadcrumbs component controls the placement of the following UX regions:

Breadcrumbs layout; ancestor links are to the left and take up most of the bar, status is the right sixth of the bar

The Breadcrumbs component is passed a parameter MyInstance that determines which instance data is being displayed on the page and contains a list of all the instance’s ancestors and its current state.

The Ancestor Links are implemented using a Telerik Tab Strip control and show all the ancestors of the currently selected instance data. The last tab in the tab strip is used to display the current status of the instance data.

If the user experience is being rendered through MAUI on a phone in portrait mode the breadcrumbs will be collapsed and use a Telerik Menu control to save space. If available, hovering over the ancestor link will display a dropdown listing all the ancestors of the current instance in an order where the last instance in the list is the root.

Layout/Help

The Help component is used when the Learn More button next to the form name is selected. This will open a popup window that will contain any help information about the current form and the tab that’s currently selected.

It requires a MyInstance parameter and is used within the Pages/Instance component.

Layout/CommandBar

The CommandBar component controls the format of the command bar displayed above the currently selected instance data using the following components:

  • Layout/DeleteConfirm
  • Layout/DeletePrompt
  • Layout/GenericActions
  • Layout/CBModalWindow

The CommandBar component is passed a parameter MyInstance that determines which Instance is being displayed on the page. The MyInstance FormBuilder parameter completely defines the states of all buttons and controls being displayed on this page. The MyInstance data will be refreshed when a new version of the instance is loaded or when control transfers to a different instance.

The Delete button is only enabled if the user has permission to delete the currently selected instance data. If enabled, the Delete button will prompt the user with a popup dialog before attempting to delete the currently selected instance and go to its parent or containing Application page. If the instance cannot be deleted, an error will be displayed to the user.

The Cancel button is enabled when the Save button is enabled. Selecting the cancel button will discard any pending unsaved changes on the current instance and return the user to their last visited instance.

The Save button is only enabled if the user has permission to save the currently selected instance data and the user has made changes to the latest version of the data in the user experience.

If enabled, the Save button will attempt to save all changes made in the user experience to a new version of the instance data in the database. If the user is not currently editing the latest version of the instance data, then the latest version will be loaded, and the user will have the option of re-applying their changes. After the save is completed, the user will see the latest version of the currently selected instance data.

The Reload/Undo button has two distinct modes:

  • If no changes have been made to the record, then the button will display Reload and selecting the button will simply reload the latest version of the record from the database.
  • If changes have been made to the record, then the button will display Undo and selecting the button will discard all unsaved changes and reload the latest version of the record from the database.

The Done button acts the same as the Save button, except that after a successful save the user is sent back to the users last visited instance.

Whether the Delete, Save, Undo/Reload or Done buttons are enabled is determined by the FormBuilder service which will consider the current version and state of the selected instance, the roles assigned to the user and any other custom conditions required by the business.

The GenericActions component displays a dropdown list that will contain a list of different actions available on the current instance.

Layout/DeleteConfirm

The DeleteConfirm component is a popup window that is opened when a user requests deletion of instance data that requires the user to enter the name of the instance to confirm that they are sure they wish to delete it.

Layout/DeletePrompt

The DeletePrompt component is a popup window that is opened when a user requests deletion of instance data and is not required to enter the instance name to confirm that they are sure they wish to delete it.

Layout/GenericActions

The GenericActions component uses a Telerik Menu to display a list of Commands, Events, Wizards, and Actions that are available to the user based on the user’s Roles, the current status of the instance and any other custom rules defined by the business. These are defined by the FormDefinition associated with the display instance data returned by the FormBuilder service.

When a command/event is selected from the list, any changes to the instance data are saved, the REST-WebAPI-Core is called to execute the command/event and then the latest version of the instance is displayed.

Any command/event/wizard that is available on the drop-down list can also be included directly on the page as a button control in a field. This enables a smoother user experience.

Layout/Wizard

The Wizard component is used to guide a user through a series of steps in a specific order. The wizard is displayed in a popup window.

The parameters passed to this component are:

  • MyInstance (type FormBuilder)
  • WizardGUID (type Guid)
  • WizardName (type string)
  • DisposeComponent (type EventCallback<DotNetObjectReference<Wizard>>)

Wizards can be closed at any time and resumed later using the Generic Actions dropdown.

When resuming a wizard you will always start on the first step but all previously entered information will persist.

Once a wizard has been completed it cannot be resumed, a new wizard must be started from scratch.

Layout/CBModalWindow

The CBModalWindow component is used to display a popup window and render another component in the window. The component receives a copy oy the MyInstance parameter which it passes on the component being loaded within the window.

Components can configured to be used by the CBModalWindow component regardless of where they’re being called from in only three steps!

  1. Add the component to the switch statement within the CBModalWindow component.
  2. Where ever the component is being called from, ensure you update the following two properties on the current instance (MyInstance.Instance)
    • CBModalName – This should match the name of the case you added to the switch statement in the CBModalWindow component.
    • CBModalVisible – This should be set to true so the popup window will become visible.
  3. Call the notify state changed event on the current instance (MyInstance.NotifyStateChanged())

The following modal popup windows are available in the Layout folder:

  • Access Control
  • Copy
  • Export
  • Import Child
  • Milestones
  • Move
  • Previous Versions
  • Recover Instance
  • Incomplete Wizards
  • Alerts
  • History
  • Feedback

Layout/TabBar

The TabBar component controls the user experience of the currently selected instance data.

The TabBar component is passed a parameter MyInstance that determines which Instance is being displayed on the page. The MyInstance FormBuilder parameter completely defines the states of all components being displayed on this page and completely defines the user experience. The MyInstance data will be refreshed when a new version of the instance is loaded or when control transfers to a different instance.

The component uses a Telerik TabStrip control to render the various tabs for the current instance that the user has access to and for each tab a FieldGridLayout component is used to render all the fields in a grid layout.

When a user selects a tab, all the fields that the user can see within that tab are selected from the current tab definition as a set of field elements. Each Field Element is then used to render a new field on the page using the Field component. There may be zero or more Field components on each tab. Each Field component (which is inside the FieldGridLayout component) is passed a copy of the MyInstance parameter and its defining Field Element.

For more information about how to assign fields to Tabs see here.

Layout/FieldGridLayout

The FieldGridLayout component uses a Telerik GridLayout control to layout all the fields in the current tab in a grid format. For each GridLayoutItem the Field component is called to render the correct field (String, Numeric, etc.).

It requires a MyInstance parameter and is used within the CBModalWindow component.

Layout/Field

The Field component controls the user experience of the currently selected field of instance data using the following components:

  • Fields/GI_Field
  • Any custom fields created by your development team

Field layout; the label is at the top, followed by any top description text you inputted, then any custom fields, then the field, with a bottom description text on the bottom

The Field component uses the Field Element (FieldUX) and FieldName to determine which FieldDefinition is required and this in turn indicates what type of field is being rendered. The FieldDefinition is used to determine whether there is any text to display in the Label, DescriptionTop and Description regions of the field user experience.

By default, the Field component will route all field rendering through a switch statement to the GI_Field component provided by trellispark. You can create and add your own CustomField to the UX-WASM-Component project. By adding extra case statements to the Field component switch statement, you can integrate your CustomField component into the overall FormBuilder.

The GI_Field or your CustomField component will take the MyInstance parameter, FieldDefinition and FieldUX as parameters to render the final field in the user experience.

To add a new CustomField into the FormBuilder, you will need to add a new subform definition to the Server Owner functionality data model. If you need to pass custom field configuration data into the CustomField component to control the rendering process, then you will need to add extra fields to the subform definition.

The Footer component simply displays a Copyright statement at the bottom of the page. This value can be configured by a workspace owner in the workspace application.

Footer layout; the copyright statement is the full width of the screen

Layout/AccessControl

The AccessControl component is used to control access to the current instance.

It requires a MyInstance parameter and is used within the CBModalWindow component. The window contains three tables.

  1. A list of users
  2. A list of groups
  3. A list of users and groups that have access to the current instance

Selecting an item from the first two tables will grant that user or group access to the instance. Selecting an item from the third table will remove access for the selected group or user.

This component can be opened from the GenericActions dropdown menu on the CommandBar.

Layout/Copy

The Copy component is used to make a new copy of the current instance (including any child instances – unless explicitly blocked).

It requires a MyInstance parameter and is used within the CBModalWindow component.

Selecting the copy button in the window will copy the current instance and navigate to the copied instance right away.

This component can be opened from the GenericActions dropdown menu on the CommandBar.

Layout/Export

The Export component is used to export a copy of the deep XML for the current instance and is only available to users with the XML Import/Export role.

It requires a MyInstance parameter and is used within the CBModalWindow component.

Selecting the export button in the window will generate and XML file and begin downloading it.

This component can be opened from the GenericActions dropdown menu on the CommandBar.

Layout/ImportChild

The ImportChild component is used to import a deep XML data file as a peer to the current instance and is only available to users with the XML Import/Export role.

It requires a MyInstance parameter and is used within the CBModalWindow component.

Within the popup window you must upload an XML file then select the import button to import the XML.

This component can be opened from the GenericActions dropdown menu on the CommandBar.

Layout/Milestones

The Milestones component is used to display a list of historic milestones reached for the current instance. This is a read-only list.

It requires a MyInstance parameter and is used within the CBModalWindow component.

This component can be opened from the GenericActions dropdown menu on the CommandBar.

Layout/Move

The Move component is used to move the current instance from its current parent to a new parent that supports this child type.

It requires a MyInstance parameter and is used within the CBModalWindow component.

Within the window there are three options for moving the instance:

  1. Move to workspace
  2. Move to peer functionality
  3. Move anywhere functionality

Moving to the workspace will move the instance up to the workspace level. Moving to peer functionality allows you to move the instance to another functionality within the same application. Move anywhere allows you to move the instance to another functionality anywhere in the solution (including another application).

This component can be opened from the GenericActions dropdown menu on the CommandBar.

Layout/PreviousVersions

The PreviousVersions component is used to display a read-only list of pervious versions of this instance. A user can select a previous version of the instance and open it in read-only mode. Only users with the PreviousVersion role can open this window.

It requires a MyInstance parameter and is used within the CBModalWindow component.

This component can be opened from the GenericActions dropdown menu on the CommandBar.

Layout/RecoverInstance

The RecoverInstance component is used to display a list of child instances that have been deleted in the current instance. A user can select a deleted instance and restore it back to the state it had when it was deleted. This is only available to users with the RestoreRecords role.

It requires a MyInstance parameter and is used within the CBModalWindow component.

This component can be opened from the GenericActions dropdown menu on the CommandBar.

Layout/IncompleteWizards

The IncompleteWizards component is used to display a list of wizards that were closed early and not completed. A user can select one of the wizards from the list to resume the wizard where they left off. Please note that when resuming wizards, you’ll always start at step one of the wizard however, all the data previously entered will still be there.

It requires a MyInstance parameter and is used within the CBModalWindow component.

This component can be opened from the GenericActions dropdown menu on the CommandBar.

Layout/Alerts

The Alerts component is used to display a list of alerts in any state. Alerts are only generated programmatically to notify the user of something (e.g., License is expiring soon, a command that was running in the background finished, etc.).

When the user has an alert that is in the ToDo state a red notification will be displayed next to the user icon in the UserManager region. When the user has an alert that is in the Doing state a grey notification will be displayed next to the user icon in the UserManager region.

In addition to a notification next to the user icon, in the UserManager dropdown the alerts icon will have a subtle red glow that’s strobing.

It requires a MyInstance parameter and is used within the CBModalWindow component.

This component can be opened from the UserManager dropdown menu.

Layout/History

The History component is used to display a list of instances the user has previously visited in their current session. Selecting an instance will navigate the user to the instance, you can also right click the instance to execute command/events.

It requires a MyInstance parameter and is used within the CBModalWindow component.

This component can be opened from the UserManager dropdown menu.

Layout/Feedback

The Feedback component is used to display a window with various fields to submit feedback regarding the current instance.

It requires a MyInstance parameter and is used within the CBModalWindow component.

This component can be opened from the GenericActions dropdown menu on the CommandBar.

Layout/ValidateField

The ValidateField component is used to validate the current contents of a user experience field component.

It is passed a reference to the Field, the MyInstance parameter, the FieldDefinition for the field and the current FieldUX. There are also three optional parameters that can be passed to the component, ElementName, subtype, and rangeValue.

ElementName is used specifically for the GI_NumericRange component to indicate which field is being validated or has validation errors (Start/End).

subType is used specifically for the GI_GUID component with regards to validation Multi-Select lists.

rangeValue is used specifically for the GI_Period and GI_NumericRange components to validate either numeric or date ranges to ensure that the start value isn’t greater than/after the end value.

It uses this information to determine the type of field, what validations are required and whether the current field value meets the validation rules.

If the field value fails to meet the validation rules, then a “Validation Message” is returned to the validate field component to be displayed on the screen.

This component is used within the Field components themselves (e.g., GI_String).

Layout/InstanceWindow

The InstanceWindow component is used to display an instance in a popup window for easy editing, so you don’t need to leave the page you’re currently on to make an edit to another instance.

The parameters passed to this component are:

  • MyInstance (type FormBuilder)
  • InstanceGUID (type Guid)
  • DisposeComponent (type EventCallback<DotNetObjectReference<InstanceWindow>>)

While using the InstanceWindow you can navigate to additional instances that are in the same hierarchy. Actions to navigate to another instance (e.g., Selecting an item in a childlist) will be blocked if the instance is not part of the current hierarchy. Common actions on the command bar such as Done, Delete, etc., will perform their expected actions then navigate to their parent instance unless the current instance is the initial instance that was loaded when the window was first opened, in that case the popup window will be closed.

This component is used within various components that use a Telerik Grid control (most notably GI_ChildList). When an item in a grid is right-clicked some options will appear, one of which possibly being Open Instance. Selecting that option will open that instance in the popup window.

Updated on October 28, 2022

Was this article helpful?

Related Articles

Need Support?
Can’t find the answer you’re looking for? Don’t worry we’re here to help!
Contact Support

Leave a Comment