CS

Portlets

Home / Documentation / Administrator guide /

Portlets

CS

1. General information

  • Portlets are simplified visual controls displayed on the main page of the portal (dashboard). They are intended for quick and clear presentation of selected information on a single screen.
  • Portlets do not represent independent data objects, but rather simplified visualizations of data and functions that are available in the application through other building blocks.
  • Portlets display simplified variants of selected controls used on view pages, such as formatted text, view tables, or charts.
  • Portlets are primarily intended for orientation and quick information. They do not replace full-featured work with data on view pages or detailed record editing in edit forms.
  • Portlets are displayed only on the main page of the first application group the logged-in user is authorized to access. The main page of other application groups displays only the background image set in the application group properties; if the application group has no image or the user has the “Background image” option turned off, the first view page opens directly in user mode.
  • Portlets can be displayed in one, two, or three columns. Each logged-in NET Genium user can customize the portlet layout according to their own preferences.
  • View tables or charts displayed in portlets should respect the limited screen width, especially with regard to the option to arrange portlets into up to three columns.
  • The default portlet layout for logged-in users is defined by the user “Administrator” with database ID 1 – this layout is copied to users without their own settings, including users with administrator rights. The layout of the anonymous user is not copied from it; it is a separate layout of the anonymous user.
  • A regular user who logs in to NET Genium and does not have a personal portlet configuration automatically inherits the default portlet configuration defined by the user “Administrator”, limited to the portlets the user is authorized to access. The user can further customize the portlet layout independently.
  • Anonymous users are not allowed to customize the portlet layout. The portlet layout of the anonymous user is set by users with administrator rights in admin mode.
  • Users belonging to the “External Users” group customize their portlet layout in the same way as regular users.

2. List of tabs in the settings dialog portlets

  • Column 1 – Setting controls in the first column
  • Column 2 – Setting controls in the second column
  • Column 3 – Setting controls in the third column
  • Options – Set the update interval and background image
  • Save to more users – Setting up portlets for multiple users; the tab is displayed only to users with administrator rights

2.1. “Column 1” tab

  • Select the controls that will appear on the main page below each other in the first column.
  • The list offers only controls the user is authorized to access together with their view page, category and application group, and only the types of controls that can be placed in portlets. Controls with the “For portlets only” option checked and view pages intended for portlets only are highlighted in bold.
  • When the portlets of the anonymous user are being set and when the “Save to more users” button is used, the list follows the rights of the logged-in administrator. Portlets the target user is not authorized to access are removed from that user after saving.
  • The same control can be placed in more columns; within a single column it is displayed only once.
  • The “Rename” button changes the portlet name displayed on the main page. The button is not displayed on mobile devices.

2.1.1. Statistics

  • The “Statistics” button displays a detailed report with all the selected controls that are selected in the portlets in all three columns, including the ability to open the settings for such a control.
  • The button is displayed only to users with administrator rights.

2.2. “Column 2” tab

  • Select the controls to be displayed on the main page below each other in the second column.
  • On a small screen mobile device, the controls on the main page appear in only one column – first the controls of the first column, below them those of the second column and finally those of the third column.

2.2.1. Statistics

  • The “Statistics” button displays a detailed report with all the selected controls that are selected in the portlets in all three columns, including the ability to open the settings for such a control.

2.3. “Column 3” tab

  • Select the controls that will be displayed on the main page below each other in the third column.
  • On a small screen mobile device, the controls on the main page appear in only one column – first the controls of the first column, below them those of the second column and finally those of the third column.

2.3.1. Statistics

  • The “Statistics” button displays a detailed report with all the selected controls that are selected in the portlets in all three columns, including the ability to open the settings for such a control.

2.4. “Options” tab

2.4.1. Refresh interval

  • The interval after which the whole main page is automatically refreshed. Available values: no refresh, 60 seconds, 2 minutes, 5 minutes, 10 minutes.
  • The interval applies both on a personal computer and on mobile devices.
  • For users with administrator rights, the main page of the first application group is not refreshed automatically, because it contains the cards for creating applications and switching modes, and in admin mode neither is the main page of the other application groups.
  • The refresh interval set on a view page does not apply to portlets.

2.4.2. Options

  • Background image
    • Checking this box determines whether the image set in the application group properties should be displayed on the main page. The option applies to the main page of all application groups, not only the first one.

2.5. “Save to more users” tab

2.5.1. Save to more users

  • The user groups and users whose portlets the “Save to more users” button overwrites, extends or reduces according to the option below. The source is the settings shown in the dialog – the portlets selected in all three columns, including changes not saved yet. In a dialog opened for the anonymous user, the source is the layout of the anonymous user.
  • In all three modes, the refresh interval and the background image option are overwritten for the selected users as well.

2.5.2. Options

  • Replace portlets to all selected users – Selected portlets will be overwritten by all selected users
  • Add portlets to all selected users – Selected portlets will be added to the end of all selected users
  • Remove portlets to all selected users – Selected portlets will be removed for all selected users; a portlet is removed only if the user has it in the same column

2.6. “Save” button

  • “Save” button – Save changes and portlet settings.

3. Controls that can be placed in portlets

  • The following view page controls can be placed in portlets:
    • View table – both a row listing and an aggregate (statistical) query
    • Chart
    • E-mail – inbox
    • News
    • Formatted text – only with the “For portlets only” option checked
    • HTML – only with the “For portlets only” option checked
  • Other controls (calendar, planner, tree, map, button and others) cannot be placed in portlets.
  • Formatted text and HTML with the “For portlets only” option checked are not displayed on the view page in user mode; in admin mode they are displayed on the view page with the “Portlets” mark after the control name.
  • A view page with the “For portlets only” option checked serves as a source of controls for portlets and is displayed neither in the navigation area nor in favorites. A detailed description is provided in the separate guide View page.

4. View table in a portlet

  • A view table in a portlet is a simplified variant of the view table on a view page:
    • It displays neither search, column filters, the grid nor the details panel.
    • It does not use the time span set in the database query (“Time span by”) nor the filters of an aggregate query – it displays all records that meet the query conditions.
    • The default number of records per page is 10.
    • From the control settings, it takes over allowing new records, denying opening records and bulk changes; for an aggregate query, the pivot table, column totals and filling time gaps.
    • The title displays only the icons for a new record, refresh, portlet settings, default sorting and hiding the portlet. Export, import and printing are not available in a portlet.
  • Clicking a column header sorts the records.
  • A record is opened by double-clicking the row or by the icon in the first column; on mobile devices by clicking the row. The “Back” button in the edit form returns the user to the main page.
  • The portlet loads all records from the database up to the number set in the database query (“Load only first”) and pages them only afterwards. For large tables, it is therefore advisable to limit the number of loaded records in the query.
  • The tooltip of rows is computed in the portlet on display for every row of the page; it is not displayed on mobile devices.
  • If the query contains an error, the error message is displayed only in that portlet and the other portlets are displayed normally.

4.1. View table settings in a portlet

  • The settings icon in the portlet title opens a dialog in which the user sets sorting, the number of records per page, the displayed columns and the tooltip columns. For an aggregate query, only the number of records per page can be set.
  • The column settings of a portlet are separate – they do not depend on the column settings of the same view table on the view page.
  • When a portlet is displayed for the first time, the default columns of the database query are saved for the user. A later change of the default query columns therefore does not show up for a user who has already displayed the portlet, until the user's settings are reset to default.
  • The settings are stored for the database query. If a user displays the same view table in more portlets, these portlets share paging, sorting and hiding.
  • The offered columns are limited by the server functions GRIDCOLUMNS() and DETAILCOLUMNS() in the notes of the database query. If user customization is denied for the view table, the columns can be changed only by users with administrator rights.
  • For users with administrator rights, the dialog additionally offers the “Save to more users” tab. The “Save to more users” button overwrites the portlet settings from the dialog for the selected user groups and users – sorting, the number of records per page, the displayed columns and the “Show tooltip” option. For an aggregate query, only the number of records per page is overwritten.

4.2. Hiding an empty portlet

  • The “Hide portlets if empty” option of a view page hides, in user mode, a view table that contains no records, as well as an empty inbox (the E-mail control). Charts, formatted text, HTML and news are not hidden.

5. Formatted text and HTML in a portlet

  • Formatted text and HTML are evaluated in a portlet in the same way as on a view page – variables are replaced and server functions are evaluated. The “#viewpage#” variable returns the ID of the view page on which the control is placed.
  • Formatted text with the “From query” text definition displays the value of the first column of the first record of the database query.
  • Formatted text with the “Language” property filled in is displayed in user mode only to users with that language; in admin mode it is displayed regardless of the language.
  • Content starting with the string “OK” and a line break (for example a return value of an external function in the form OK\r\nhtml) is written out without the portlet frame, without the title and without icons. If the rest of the content is empty, the portlet is not displayed at all.
  • Content consisting only of the “#usersonline#” variable displays the list of currently logged-in users.
  • The main page with portlets of a logged-in user contains no form, so pressing the Enter key in a text field inside a portlet submits nothing. Text fields inserted into an HTML portlet must handle any submission with their own JavaScript. The main page of the anonymous user with the login window does contain a form, so the Enter key in a text field of an HTML portlet can submit it.

6. Chart, e-mail and news in a portlet

  • Chart – the portlet title is evaluated as an expression with server functions; an empty title is replaced with the text “Chart”.
  • E-mail – the portlet always has the title “Inbox” regardless of the portlet name and allows writing a new message as well as opening a received message. The settings icon in the portlet title opens a dialog in which the user sets sorting (by sender, subject, date or size), the number of records per page and the “Show tooltip” option. For users with administrator rights, the dialog also offers the “Save to more users” tab, whose button overwrites these settings for the selected user groups and users.
  • News – the portlet displays scrolling text from an RSS source given by an address or a path to a file on the server. The source is loaded with a time limit of 1 second and kept in the cache for one hour; on error, the text “The page cannot be displayed.” is displayed and the source is loaded again after five minutes at the earliest.

7. Column layout

  • The ratio of column widths is set in the application group properties on the “Portlets” tab; the tab is offered only for the application group with database ID 1. A detailed description is provided in the separate guide Application group.
  • If the third column contains no displayed portlet, the third column is not rendered and the first two columns take the whole width of the main page.
  • The anonymous user sees the login window in the third column. If the “DenyLogin.txt” file exists in the “Config” directory, the login window is displayed only for access from the IP address “127.0.0.1”. A detailed description is provided in the separate guide NET Genium settings.
  • The “Hide” icon in the portlet title collapses the portlet into the “Show...” link and its content stops loading until the user shows it again. The anonymous user does not have this icon.
  • If the user has no portlet in the first application group and the application group has no background image or the user has the “Background image” option turned off, the first view page opens in user mode instead of the main page; view pages intended for portlets only are skipped. This redirection does not apply to the anonymous user.

8. Mobile devices

  • On a small screen, portlets are displayed in a single column below each other – first the portlets of the first column, below them those of the second column and finally those of the third column. A control placed in more than one column is displayed only once.
  • On a small screen, portlets from view pages with the resolution set to “Big screen” are not displayed. The anonymous user does not choose the screen size, because it is chosen only when logging in; on mobile devices, the main page is displayed to the anonymous user as on a big screen, but portlets from pages with the “Big screen” resolution are not displayed. On a personal computer, the resolution of the view page is not used for portlets – portlets from pages intended only for a small screen are displayed as well.
  • A view table on a small screen joins the column values into a single column separated by commas.
  • The refresh icon in the portlet title reloads the whole main page on mobile devices.
  • On a big screen, portlets are displayed identically to a personal computer.
  • On mobile devices in user mode, the portlet settings cannot be changed.

9. Rights

  • Whether a portlet is displayed is decided only by the rights to the control the portlet displays. The rights to the view page, application or application group are not checked for a portlet – removing them does not hide the portlet.
  • Users with administrator rights see all portlets of their layout without any rights check.
  • When the rights of a control change, the portlet is automatically removed from all users who lost the rights to the control. In the same way, the columns of a view table in a portlet to which the user lost the rights are removed.

10. Default settings and their restoration

  • The default portlet layout is copied to a user from the user “Administrator” at login, if the user has no portlet. Neither the refresh interval nor the background image option are copied.
  • If a user removes all of their portlets, they get the default layout again at the next login.
  • Deleting a view page control removes the corresponding portlet from all users.
  • Renaming a control in its settings overwrites the portlet name for all users who have this control in portlets.

11. Automatic actions when opening the main page

  • Every time the main page of the first application group is loaded or refreshed, the external function NETGenium.OpenPortlets runs. A detailed description is provided in the separate guide External functions.
  • The server function SCHEDULEPORTLETS() redirects the user to the main page after the script finishes. A detailed description is provided in the separate guide Server functions.