Portal#

Portals are the primary feature of CtrlPortals. With Portals, you can construct a new UI inside M-Files related to the object being viewed, in addition to the traditional metadata page.

Portals are set up in the M-Files Admin application, specifically inside the CtrlPortals configuration, for an example setup, see our sample vault example.

Note that while Portals and Dashboards are quite similar, Portals are always associated with a ‘subject object’ (or just object) that they display information from, while Dashboards are used to display more general information.

Configuration#

The portal configuration is composed of 9 fields:

  • OpenDefault - Determines if the Portal should open per default when you select a metadata object that is compatible with the portal.

  • Controls/Enabled - Determines if the Portal should show editing controls, making it capable of editing metadata and changing workflow states.

  • Classes - Determines which classes that the portal should be available for.

  • Title - The title of the Portal, used to organize the configuration and also the title displayed in the tabs in the M-Files Client.

  • Theme - The theme is composed of two sub-fields used to control the accent and background of the portal

    • Accent - Used to set the accent colour of every component in the Portal. Use this to match the theme of the object.

    • BackgroundCSS - Used to set a different background for the portal. The default is linear-gradient(315deg, #6a93cb 0%, #a4bfef 74%) fixed

  • Stackable - Whether the UI should automatically stack rows to a single columns on mobile devices. This is used to make the portal more responsive (See Fomantic-UI docs).

  • Doubling - A doubling grid will double column widths for each device jump. This is also used to make the portal more responsive (See Fomantic-UI docs).

  • PortalRules - See Portal Rules module.

  • Components - See Components subsection.

Components#

Components are the building blocks of Portals. They are used to display and interact with metadata from M-Files objects in a custom UI. Components are created in the M-Files Admin application through the configuration view for CtrlPortals by selecting them as fields in M-Files. There are several types of components, e.g. Header Segment, Form, List, etc. Each type of component has its own set of fields that can be customized to fit the needs of the Portal. For example, a Header Segment component might have fields for the header text, subheader text, and icon.

../../../../_images/CtrlPortals-ComponentHierarchy.png

The Portal Component Hierarchy#

GridComponents#

At the top level, we have GridComponents, these components are used to determine how UI elements will be arranged rather than the functionality of the UI.

Here’s a small overview of the available GridComponents:

  • Segment: The basic GridComponent. Segments are used to group related content together, and can contain various other UI components such as forms, menus, plots, etc.

  • ColumnSegment: Represents a column of Segments. Columns are used to arrange Segments in a columnar layout and can only contain Segments and HeaderSegments.

  • HeaderSegment: A special kind of named Segment, a HeaderSegment is used to display an M-Files property as a title or header, along with another property as a subheader. A HeaderSegment can only contain SegmentComponents.

SegmentComponents#

Inside Segments and HeaderSegments we have SegmentComponents, these are used to display specific types of content.

Here’s a small overview of the available SegmentComponents:

  • FormComponent: Represents a form UI component. Forms are used to collect information from users through input fields, checkboxes, etc. See the Form module for more details.

  • MenuComponent: Represents a menu UI component. Menus are used to provide users with a list of options or actions to choose from, often presented as a dropdown or a sidebar.

  • Html: An HTML-template component that can be used to display custom HTML content. This component can be expanded with M-Files properties, using the PropertiesToExpand-list. The expanded properties are then injected into the HTML mark-up using a subset of the syntax equivalent to that emitted by M-Files placeholders. In particular, you can reference properties in your HTML by using the syntax: %PROPERTY_<id number>% where <id number> must be replaced with the exact digits making up one of the expanded properties’ ID.

  • MarkdownEditor: This component is used to render a Markdown file. See the Markdown module for more details.

  • ListView: This component is used to arrange the contents of an M-Files view into a list / table. See the Sample Vault example for more details.

  • PlotView: This component is used to render 2D plots of M-Files data. See the Sample Vault example for more details.

  • Calendar: This component is a calendar that can be used to create Event objects in M-Files. See the Calendar module for more details.

  • Comments: This component is a comment feed. See the Comments module for more details.