Bootstrap guidelines

Introduction

In version 15.5 of Instant Developer, a new theme has been introduced that can be used with Web applications. This theme uses the classes and components of the Bootstrap framework to render objects.

To achieve this result, the client-side framework for the web applications was rewritten so that it could interface with Bootstrap. That is why not all features in the RD3 application framework are found in a project with the Bootstrap theme enabled.

In addition, when creating applications with that theme, you need to follow specific guidelines in order to achieve correct behaviors, since some of the application framework behaviors are different when you use the Bootstrap theme. This means you need to get to know the characteristics in order to set up your application correctly.

Forms

Bootstrap is a framework created to easily and efficiently manage the responsiveness characteristics of the application, which is why the forms in this theme always adapt horizontally to the space available. Therefore, the horizontal resizing property for the forms is not considered, and they always adapt to the browser dimensions.
Vertical resizing occurs in two different ways depending on the configuration of the corresponding property of the form:

• None: In this case, the height of the frames at design time is maintained, so that if vertical space is insufficient, the form will display a scrollbar. If the frames have scrollbars at design time, these will be maintained at runtime as well.
• Extend/Fit: In this case the dimensions of the frames are calculated as a percentage depending on the dimensions at design time (for example, if at design time the form has two vertical frames of the same height, at runtime each frame will occupy 50% of the available space). In this case, the frame will have the scrollbar if its content is larger than the available space.

The form frames are converted into a Bootstrap grid, maintaining the design-time layout for desktop devices; at lower resolutions the grid will adapt based on the space available. Therefore, we recommend that you design the layout of the forms keeping in mind from the beginning all the form factors on which the application will need to be displayed.

Notes:

• The Fixed width frame flag and the Minimum width and Maximum width parameters are not supported.
• The Fixed height frame flag and the Minimum height and Maximum height parameters are only supported if the frame has vertical resize set to None.

Vertical column resizing

From version 16.5.6850, resizing and reordering functionalities have been enabled for list columns.
To maintain compatibility with responsive column management in lists, resizing is only enabled for fields that have a horizontal resizing mode in lists set to no action.

Vertical form resizing

From version 19.0.7400, Bootstrap forms have two types of vertical resize:

• NONE: The frames contained in the forms are drawn based on their heights at design time. If there is not enough vertical space, the form will display the scrollbars.
• FIT/EXTEND: The frames have a fixed percentage height based on the dimensions at design time. If the content doesn't have space, the frame will show the scrollbar.

The first type of resize is suitable for small devices, but if the form is shown on a desktop device, it's up to the programmer to size the objects at run-time to avoid wasting space.
On the other hand, the second resize type is convenient on desktops, but the result becomes inconvenient on small devices unless the programmer has explicitly managed the resizing via code.

To improve this behavior, in version 19.0 we have researched a third resize mode. This mode can be activated if the form has vertical resize FIT/EXTEND but is shown on a device with horizontal dimensions of less than 998px (10-inch tablet); in this case, the frames behave as if the resize were set to NONE, so it will be the form to show the scrollbars, and the frames will resize in height depending on their content.

This functionality is turned off. To activate it, you need to write the following in the custom.css file:
@media screen and (max-width: 998px) { .form-body:not(.form-body-fluid) > .frame-row { height: auto !important; } .form-body:not(.form-body-fluid) .panel-list-body-box { max-height: 300px; } }
This functionality should be considered experimental.
It was designed for forms with a simple layout, such as two vertical frames, and has not been tested in the presence of subforms or subpanels.
Feedback is welcome. We recommend that you do not use it in a production environment.
We do not anticipate providing immediate support for problems that may occur after having activated this mode. A workaround that can always be applied is to turn off the functionality and return to the default behavior.

Panels in list layout

The list layout for panels behaves differently than that for standard desktop themes (Seattle, Casual, Zen, and Simplicity), and in particular:

• In list layout, panel fields are not editable (although supported beginning in version 16.5, in-list entry is still not supported).
• There cannot be any off-list fields in list layout. (supported beginning in version 16.0)
• Regardless of the list display in the designer, it will always fill all the space available (horizontal resizing is always 'fit').
• Records are loaded paginated, in groups of 30 as for mobile themes. When the list is completely scrolled, the request for the next records to display is sent to the server.
• The list is not displayed; all rows that the server sends to the client are created in the DOM.
• If the panel has both layouts, the Auto manage layout flag must be enabled.

The in-list panel fields can have only two resize types:

• None: In this case the dimension of the in-list field is fixed at its design-time dimension.
• Fit: In this case the dimension of the field is fluid and adapts to the space available.

Given that the list always occupies all the available space, if there is no field with Fit resizing, the browser will still enlarge the fields, distributing the available space into equal parts. In this case, the Row Selectors should not be displayed; otherwise the space will be assigned to their column as well. As the size resulting from browser resizing decreases, the text of the fields and their headers could overlap. To avoid this we recommend using a responsive list layout, initially showing only the fields with necessary data and showing ancillary data as space increases. To achieve this result, we recommend:

• Setting Fit resizing for the field or fields with the most important descriptive content and no resizing rules for the others.
• Use Bootstrap's responsive classes or media queries to hide the unnecessary fields at the various size breakpoints. Instant Developer provides the following classes:
  • md-visible: field visible only on horizontal tablets or desktops.
  • lg-visible: field visible only on large desktops (>1300px).
• We recommend always having a field on screen with Fit resizing rules.

To get good results, we recommend you take the following steps after having created the panel:

• Select the most important descriptive fields and assign the Fit resizing rule to at least one of them.
• Assign to all the other fields the lg-visible css class or an equivalent class that hides the field until the maximum breakpoint.
• Display the list on the browser at minimum size (we recommend using development tools that allow you to test the device in smartphone mode).
• Move to the next breakpoint (>769px) and decide the visible fields at that size, replacing the class with md-visible.

Instant Developer only integrates two specific visibility classes for two breakpoints (768px and 1300px). If necessary, other breakpoints can be added by adding the specific media queries in the custom.css file; for the sake of simplicity we'll list the definition of the classes that are already integrated.

@media screen and (max-width: 768px) { .panel-field-value-list.md-visible, .panel-field-header-list.md-visible { display: none !important; } .panel-field-value-list.lg-visible, .panel-field-header-list.lg-visible { display: none !important; } } @media (min-width: 769px) and (max-width: 1300px) { .panel-field-value-list.lg-visible, .panel-field-header-list.lg-visible { display: none !important; } }

Notes:

• If there isn't enough space to show all the list columns, a horizontal scrollbar will be shown. To correctly enable this behavior, you need to hide the row selectors and disable multiple selection (not necessary beginning with version 18.5). In any case we recommend creating responsive lists that adapt to the space available.
• The value of dynamic rows is set to 30 by default. This value is nearly always sufficient to allow the vertical scrollbar to appear and enable pagination. If it does not appear, the value can be increased.
• Performance depends on the rows in the DOM, so we recommend limiting the records returned by the panels.

Panels in detail layout

In terms of the detail layout, you also have to keep in mind a few specific behaviors of the framework when creating the panel. The structure of the fields is converted from an algorithm into a series of nested Bootstrap grids, in the following steps:

• First, the fields are divided into vertical rows. If one or more fields are next to each other, they will be drawn on the same row.
• Each row created is divided into columns. Fields that overlap vertically on the same row are inserted into the same column. The size of the columns is determined as a percentage based on the dimensions of the fields involved (two fields with the same width will have two columns at 50%, and fields with different widths will have differently sized columns).
• The algorithm proceeds recursively until obtaining rows that contain columns with just one field.

For the purposes of running the algorithm, the detail layout is maintained, but the result might not faithfully reflect the settings of the IDE, and the result will also be full-responsive, so fields that are shown side by side on a desktop may be displayed one below the other on a tablet. To achieve correct alignment, we recommend that you:

• Draw the fields in detail with the same width, especially if they are side by side horizontally. Otherwise the result will be less pleasant to look at if displayed one below the other due to lack of space.
• Draw the input fields with a height of 32 px.
• apply a gap of 16 px between vertical fields.
• Never overlap the fields; always leave a gap between them (both horizontally and vertically).

Instant Developer automatically applies these rules when the detail layout is created or when Align Vertically is selected. Horizontal resizing of panel fields follows these rules:

• None: the panel field is drawn in the same dimensions as design time. This setting concerns the field itself, but not the column that contains it, which, as a Bootstrap column always has percentage dimensions. That is why two fields side by side that do not have resizing rules could be shown separately on larger monitors.
• Fit: the field occupies all available space in its column.
• Move: the field occupies all available space in its column, but its maximum width is that set at design time, which is helpful in managing the responsive layout as well as possible.

Vertical resizing is not applied to the fields and overlapped fields cannot be obtained.

Notes:

• In the case of paged panels, the fields present in the detail must all belong to one page. Detail fields outside the page are not supported.

For convenience you can choose a base dimension for the space occupied by the panel and take its dimensions to be assigned to the fields in order to obtain a specific column width.

Space	col-1	col-2	col-3	col-4	col-5	col-6	col-7	col-8	col-9	col-10	col-11	col-12
1032	86	172	258	344	430	516	602	688	774	860	946	1032
960	80	160	240	320	400	480	560	640	720	800	880	960
840	70	140	210	280	350	420	490	560	630	700	770	840
720	60	120	180	240	300	360	420	480	540	600	660	720
480	40	80	120	160	200	240	280	320	360	400	440	480

Font type icons

Applications developed with the Bootstrap theme don't use images. Instead, they use font type icons; in particular they use Font Awesome. Font Awesome icons can be used in all strings displayed on screen using the {{icon-IconName}} format.

For example, to use the 'fa-star' icon, simply write {{icon-fa-star}} in the text.

Objects that support this characteristic are:

• Captions for panel fields in list and detail layout.
• Value of the panel fields (disabled).
• Content of static fields and buttons.
• Value lists for combos.
• CommandSet captions.
• Command captions.
• Frame captions.
• Spans not enabled.
• Captions for panel groups in detail layout.
• Captions for panel pages.
• Tab captions.
• Text contained in tree nodes.

Theme customization

To customize the theme, you can duplicate the Bootstrap or Ionic folder in the C:\\Program Files\\INDE\\CURRENT\\Theme folder and specify the name of your own theme in the application THEME property. Instant Developer will use that folder to generate the web application, but will not use the RD3 folder located in the copy, but rather the RD3 folder located in the "standard" Bootstrap/Ionic theme.

In previous versions, if you customized the Bootstrap theme, even the RES folder (which contains the JS/CSS files for Bootstrap and the fonts) was taken from the standard theme. Starting with version 19.5, the RES folder will be used if found in the customized theme.

Notes

• Improvement related to this forum thread and support request 001385-2019.
• N.B:The name of the customized theme must begin with:
  • "bootstrap" if it is a theme derived from the Bootstrap theme;
  • "ionic" if it is a theme derived from the Ionic theme.

Applied icons customization

The creation of icons in applications that use the Bootstrap and BootstrapZen themes was improved.
In particular, the definition of the icons to be used was centralized, making it easier to be able to customize them.

The icons are defined in the ClientParams.js file and can be customized by implementing the RD3_CustomInit function in the custom3.js file.

Example: function RD3_CustomInit() { RD3_ClientParams.FA_ICON_TOP = "fa-angle-double-left"; // Icon used by the toolbar of books in preview - first page }

Customizing the grid classes

Beginning in version 16.0, you can enter special tokens in the CSSClass property of the panel fields and groups to overwrite the CSS classes of the grid cell calculated by the framework.
The tokens must be formed like this: "{{css class}}".

ES: Orders.CustomerID.CSSClass = "{{col-sm-2 col-md-4}}"

These classes only have effect in detail or for off-list fields, since the list is created with an HTML table and not with the Bootstrap grid.

Beginning in version 18.0r4, the same functionality is available for CSS classes for frames. The classes defined inside the token are only used in the case of frames in a horizontal division, and make it possible to customize the classes the system applies to the columns in the form grid.

As of version 21.0.8100 it's possible to modify the grid classes of panel fields at run-time as well, adapting them as needed, whereas before they could only be modified when opening the form.

Bootstrap Zen theme

In version 18.0.7000, a new graphical theme called Bootstrap Zen was created. Click here to see the new graphical theme.

Notes

• The new theme can also be applied to existing applications that use the Bootstrap theme.
• The features supported are the same as the Bootstrap theme.
• The BootstrapZen theme does not support configuration of the background color of an in-list field, the alternate row, or the active row from Visual Style. These colors can be configured through the CSS.
• The BootstrapZen theme does not support configuration of the background color of a field in detail from Visual Style. This color can be configured through the CSS.
• The theme does not support configuration of the background color for panel fields using the BackgroundColor property. The color can be configured through the CSS using the CSSClass property.
• From version 19.0.7400 the option to set the text color of list headings from VisualStyle in the BootstrapZen theme has been enabled.

Modal form sizes

From version 19.0.7400 Bootstrap provides three possible sizes for modal forms (small, medium, and large).
In previous versions, applications always used the largest size.
It is now possible to indicate which size to use by setting in the ClassName property for the form:

• modal-sm: small size.
• modal-md: medium size.

If nothing is indicated the system will use the default size (large).

Tooltips

The tooltips are positioned:

• To the right for the first list column.
• To the left for the last list column.
• Above for the last list row (unless it's the first/last column).
• Below in all other cases.

Up until version 19.0.7400, tooltips in lists were always positioned to the right of the cell, even it if was the last field in the list.

Containers

Bootstrap supports two different types of global containers:

• container: fixed-width responsive container.
• container-fluid: container that fills all available horizontal space.

Up until version 16.0.6700 the framework automatically created a global container for the application with the "container-fluid" class, the current default value. Now you can choose which class to use, both for the body of the application and for the header.

Notes

• The parameters are managed client-side. To edit them, simply create the custom3.js file in the custom folder and enter the following javascript code:
  function RD3_CustomInit() { RD3_ClientParams.BodyContainerType = "container"; // or "container-fluid" RD3_ClientParams.HeaderContainerType = "container"; // or "container-fluid" }

Optional gutter

The guidelines contain a table that allows you to link the width to assign to the various fields to the number of columns that the system will assign at run-time.
Before version 16.0.6700, these widths did not take into account the gutter between the various Bootstrap columns (the default value is 30px).

You can now set the width of the gutter to be used in calculations as one of the client parameters so that the fields can be drawn using the same width they will have on screen and with the same gaps as Bootstrap.
The default value of the parameters is 0. This way the system won't change behavior compared to the previous version.

This change makes it possible to better align the designer with the end result.
function RD3_CustomInit() { RD3_ClientParams.GridGutterLeft = 15; RD3_ClientParams.GridGutterRight = 15; }

Grid in the form editor

If you use the Bootstrap theme, you need to know the grid system used to make the form responsive. To facilitate this operation, you can now activate the display of the Bootstrap grid in the form editor as well:

Functioning of the grid

As shown in the image, when the command is activated a grid is shown that indicates which and how many cells the Bootstrap graphic engine will use to create the form at run time. In the example, the first " contains the Employee ID, Last Name and FirstName fields. These fields occupy 2, 4, and 6 cells respectively. Therefore, the first field will be widened automatically and its length will be 2/12 the full length of the form, the second 4/12, and the third 6/12. These ratios are achieved as follows:

• The fields are respectively 160px, 260px and 276px wide
• The system calculates the total "effective" width of the fields: 160px + 260px + 276px = 696px and calculates the width of a Bootstrap cell (1/12 of the total width): 696px/12 = 58px for each cell
• At this point, the system calculates how many cells need to be assigned to the various fields: 160/58 = 2.76 rounded to 2 cells, 272/58 = 4.48 rounded to 4 cells. The rest (12 - 2 - 4 = 6) is automatically assigned to the last field of the "row".

CommandSets

Beginning in version 19.0.7400, it is possible to use second-level CommandSets in applications that use the Bootstrap and BootstrapZen themes.

Beginning in version 20.0.7800 it is possible to use HTML text in command/commandset headers.

Notes

• Second-level menus are not supported in popup menus.

HTML and application header

Beginning in version 20.0.7800, HTML text can be used in the application header.

Label and checkbox position

Beginning in version 20.0.7800, the position of labels and checkboxes in detail layout can be inverted by setting the field alignment to the right.

Notes

• Right alignment also affects the list.

Assigning Bootstrap classes to buttons

It is now possible to use specific Bootstrap classes (btn-danger, btn-primary, etc...) in CommandButton type panel fields.

Management of MouseClick and MouseDoubleClick panel events

It is now possible to use the OnMouseClick and OnMouseDoubleClick panel events in applications made with the Bootstrap theme.

Off-page fields in paged panels

As of version 18.5, these fields are drawn in their own grid before the page fields and will be visible on all pages.
In previous versions, the off-page fields (in detail or off-list) were drawn in the first page and not carried to the other pages.

Notes

• This change in behavior is specific to the Bootstrap and BootstrapZen themes, and aligns them with the behavior of RD3 Web themes.