Special Renderings

Define alternative ways of viewing data with deep customization capabilities to improve user experience.

Overview

The Special Renderings pattern provides mechanisms that simplify the process of developing new controls, while providing Genio users with more customization options over them. Special Renderings are available in the context of menu lists, form table lists, or, in some cases, simple form fields.

Special rendering variables

The most significant improvement of the Special Renderings pattern over Custom Controls is its capability to customize the controls. Previously, the Genio user lacked accessible customization methods through Custom Controls, which resulted in the need for manual coding, ultimately leading to impractical and undesirable outcomes.

Special Renderings introduce a solution to this issue through the implementation of special rendering variables. These variables can be defined in the XML specification file and are made available within Genio for customization purposes.

Mapping variables

Mapping variables facilitate the mapping of table columns to specific display templates within the rendering. For example, by using the variable $card.title with the value PERSO.NAME, the column containing a person's name can be mapped to the title of a card.

Configuration variables

Configuration variables serve the purpose of customizing the appearance and behavior of the generated control. These variables allow users to modify aspects such as text color, background color, and other relevant configuration settings to achieve the desired visual presentation.

Groups of variables

Groups of variables allow for the definition of a set of variables that are applied together. For each special rendering type, a set of predefined variable groups is provided, and each group comes with a predefined set of variables.

Users can create multiple instances of these predefined groups and associate them with their special rendering configurations. For example, a group with the name "external-layer" is composed of multiple variables that collectively define an "external layer."

variable-groups

Defining variable groups

To create an instance of a variable group in Genio, follow these steps:

  1. Identify the group that matches your desired configuration purpose.
  2. Create an instance of the group by specifying a unique name using an alphanumeric string.

variable-group

Associating variables with group instances

To associate variables with specific group instances in Genio, follow these steps:

  1. Identify the variables associated with the variable group.
  2. Create an instance of each desired variable and associate them with the variable group, by specifying the group ID.

group-variable

Note: The field "Group" is only visible for variables that are part of a variable group.

View modes

When working with Special Renderings, one noticeable advantage is the ability to specify multiple alternative view modes for the same table list or form field. Moreover, you have the flexibility to configure which view modes are displayed by default and the order in which they appear.

While Special Renderings provide the freedom to configure multiple renderings and their display settings, it may not always be desirable to grant the application user complete control over these options. In some cases, the Genio developer might intend to keep the original view mode hidden at all times or limit certain interaction modes. To address this, Genio provides an option that allows the developer to specify the desired interaction mode for that particular page:

  • No control: The user can neither change the visibility of view modes nor their order.
  • Control in exclusive mode: The user can toggle between view modes (the list and one alternative view), which means only one is visible at a time.
  • Total control: The user can set the visibility of each view mode and change the order in which each appears, allowing multiple controls per page.

Control in exclusive mode

The exclusive view mode is designed to facilitate the navigation between the list and an alternative view mode (e.g., Cards). In order to minimize the number of clicks required to navigate between view modes, while making explicit to the user which view mode is currently in use, the following mechanism was implemented (located at the top right corner of a page that uses Special Renderings):

Total control

It may be convenient to display, at once, more than one form of representing the same information. To address that need, the Special Renderer in total control mode keeps the list on the page and places the new rendering right next to it (Custom Controls replace the list on the page).

The order in which these elements are displayed initially follows the definition in Genio, and later answers to the user's preference. In addition to the order, the user may also toggle the visibility of each control of the page. These actions are achieved by clicking on the "View options" icon, located at the top right corner of the page (next to the "Change display of the list" icon).

Note: only logged in users are able to set the page layout according to their preference (this feature is not available to guests).

Definition in global lists

Special Renderings can also be definied in global lists, as well as the corresponding type of user interaction (no control, control in exclusive mode or total control). Once a menu has a global list associated with it, the definition of the special rendering of the global list is used, ignoring anything that was previously defined locally.

Developing a special rendering

When developing new Special Renderings, it's important to note that the process is entirely separate from the development of Genio. To initiate the development of a new Special Rendering, the first step involves specifying its structure. The structure should include the following elements:

  • Identifier (mandatory): This serves as a unique identifier for the Special Rendering and is used to identify it across different languages in use.
  • Name (mandatory): The Name element is necessary for translating the title of the Special Rendering into the language being used. This allows for localization and language-specific rendering titles.
  • Variables (optional): The Variables element provides an option for customizing the control. It allows for the inclusion of variables that can be adjusted to tailor the behavior or appearance of the Special Rendering.
  • Subtypes (optional): Subtypes are useful for organizing slight variations of the same control that may share some variables. This allows for better categorization and management of related Special Renderings.

To define the structure, an XML file specifically created for this purpose is required. This XML file acts as a protocol that Genio uses to interpret and handle the new control without requiring any code updates. It offers a flexible means of expanding and introducing new Special Renderings. However, it's important to note that to extend the protocol, code updates are necessary.

Below are some examples and a template for the XML file structure:

<CustomControl>
    <Identifier>YourIdentifier</Identifier>
    <Name BASE="por">
        <por>Cartões</por>
        <fre>Cartes</fre>
        <eng>Cards</eng>
    </Name>
    <Variables>
        <!-- Define your variables here -->
    </Variables>
    <Subtypes>
        <!-- Define your subtypes here -->
    </Subtypes>
</CustomControl>

1. Basic information

The identification of a Special Rendering is performed using:

  • Identifier: A unique identifier used to identify the special rendering under any language in use
  • Name: The name of the rendering, translated to multiple languages

Note: the identifier is for internal use only. In order to fully enable translation of the Special Rendering name, it is required to add the translation of the name to StringsHardcoded.xml.

2. Variable definition

Variables provided by the Special Rendering can be specified as follows:

Common Attributes:

  • Name: The name of the variable.
  • Type: Specifies the type of the variable (MAP for mapping variables, STYLE for style variables).
  • Mandatory: Specifies whether the variable must be defined for this Special Rendering (true or false).
  • AllowMultiple: Specifies if multiple columns can be mapped to this variable (true or false).
  • Description: A short description of the variable, which will be displayed in Genio as the variable is selected.

These attributes are applicable to both mapping variables and style variables. They define fundamental characteristics of the variables that can be customized within the Special Rendering.

Attributes for Style Variables Only:

  • CanBeMapped: Specifies if the variable can be mapped to a database field (true or false).
  • Default: Specifies the default value of the variable.
  • Values: A list of predefined values for the variable.

These attributes are specific to style variables. They provide additional customization options for controlling the appearance and style of the Special Rendering.

Please note that the "CanBeMapped" attribute is only relevant for style variables, as mapping variables are inherently associated with database fields.

3. Subtype definition

Finally, the subtypes provided by the Special Rendering can be specified as follows:

  • Name: the name of the subtype
  • Variables: the pool of variables available for this subtype (a subset of the pool defined for the special rendering), each identified by its name

Note: it is not mandatory to specificy subtypes. If no subtype is specified, Genio will consider the special rendering as a single control without variations, and present all the variables specified for it.

A complete template to start developing a new special rendering can be downloaded here.

Changelog

The complete changelog of all notable changes made to Special Renderings. Descriptions are written as New: or Fixed: for changes that are not considered a maintenance release.

Genio 325.86
  • (VUE) Fixed: Fixed error message saying the value was empty appearing when trying to save a dynamic style variable in the special renderings pattern.
Genio 325.79
  • (VUE) Fixed: Fixed special rendering fields being hidden or crashing the application when the user was coming back from a popup form.
Genio 321.71
  • (VUE) New: Style variables of special renderings can now be dynamic.
Genio 321.46
  • (VUE) Fixed: Fixed newly created special rendering variables not working in menus.
Genio 319.89
  • (VUE) Fixed: Fixed special renderings over DB fields not loading their data.
Genio 319.39
  • (VUE) Fixed: Fixed special renderings not working over fields that were dependent and fixed.
Genio 317.60
  • (VUE) Fixed: Fixed special rendering lists not loading.
Genio 314.89
  • (VUE) Fixed: Fixed the generation of special rendering's style variables not taking into account if they were available on the selected subtype.
Genio 314.80
  • (GEN) Fixed: Fixed special renderings not validating, in some cases, if all the required variables were being mapped to.
Genio 314.79
  • (VUE) New: Added new style variables to Map's special rendering, to allow greater customization of the marker's info window.
Genio 314.64
  • (GEN) Fixed: Fixed mapping variables having an empty value in special renderings over DB fields.
Genio 314.31
  • (GEN) New: Support for the definition of special rendering variables with text resources.
Genio 313.08
  • (GEN) New: Special renderings can now be used in form fields from the DB, instead of just table lists.
Genio 310.25
  • (GEN) Remove special renderings dependency of fixed menu identifiers
Genio 306.99
  • (MVC) Refactor SpecialRenderer to improve the structure it outputs
Genio 305.90
  • (MVC) Bugfix: Fix broken reset of view modes button
Genio 305.65
  • (MVC) New: SpecialRenderer performance improvements
Genio 305.39
  • (GEN) New: Remove special renderings dependency of fixed menu identifiers. Optimizations in the generation of special renderings
Genio 305.37
  • (MVC) New: Add support for specifying special renderings in form fields (table lists)
Genio 305.11
  • (MVC) Fixed: Generation of the control mode of special renderings when using global lists
Genio 304.46
  • (MVC) Implement different special rendering subtypes using different templates
Genio 304.38
  • (Reindex) Fixed: Prevent error when computing the dominant color of SVG images
Genio 304.19
  • (Reindex) Fixed: Creation of LSTREN records (view mode preferences of the user) with integer primary keys
Genio 302.68
  • (GEN) Fixed: Opening special rendering forms when new style variables are not supported by the current subtype
Genio 302.46
  • (MVC) Fixed: Prevent page from automatically scrolling down when clicking menu options
Genio 302.38
  • (GEN) Separate the definition of mapping variables from style variables
Genio 302.37
  • (MVC) Fixed: Remove limitation in identifying special renderings: they are now identified by their full name (eg, GQT_Menu_Teste), instead of the menu ID (eg, Test), enabling special renderings in menus with the same ID, but in different modules
Genio 302.16
  • (MVC) New: Add dominant color placeholder for loading images (e.g., card image)
  • (MVC) New: Display the insert button on the page header when the bottom is not visible
Genio 301.54
  • (GEN) New: Automatically generate available variables using GenioAPI
  • (MVC) Fixed: Generation of followups
Genio 301.36
  • (GEN) New: Prevent saving special renderings until all mandatory variables are defined
  • (MVC) Fixed: Generation of CRUD actions
Genio 301.32
  • (GEN) New: Add the ability to quickly import/export and share special renderings settings
Genio 301.26
  • (GEN) New: Add support for setting default values for special rendering variables
  • (GEN) New: Automatically load variables with a default value
Genio 301.17
  • (MVC) Fixed: the conditional render of the 'Advanced search' button
Genio 301.14
  • (GEN) New: Add the ability to configure Special Renderings on global lists
  • (MVC) New: Add 'Exclusive mode' option to toggle between view modes
  • (MVC) Fixed: Popup followups on pages with Special Renderings
  • (MVC) Fixed: Sticky header when scrolling on pages with Special Renderings
Genio 301.03
  • (GEN) Fixed: Deletion of menus with special renderings
Genio 301.02
  • (MVC) Fixed: Generation of menu followups and permissions
Genio 301.01
  • Initial Build