Banners

Introduction

A banner is an interactive element of the web-interface that can be used to inform control panel's users.

Developers can add custom banners (notifications) using the Banner class, or special COREmanager mechanisms.

Message description

You should add a text for your banner into the message description section for a certain function

  <messages name="backup.run">
    ...
    <msg name="backup_success">Backup process completed successfully</msg>
  </messages>

or into the alert section

  <messages name="alert">
    ...
    <msg name="backup_success">Backup process completed successfully</msg>
  </messages>

If you want to add into the message any additional values or messages, a new sequence, something like this __name__, where name - is the name of the parameter, will be added.

  <msg name="backup_success">Backup process '__name__' completed successfully. Processed __count__ file(s).</msg>

Creating a banner

Create your banner in the source code of the function handler:

...
ses.NewBanner("backup_success", Session::Banner::blInfo).SetParam("__name__", elid).SetParam("__count__", str::Str(files.size()));
...

The following banner will be added into the XML-document

  <doc>
    ...
    <banner id="backup_success" status="3">
      <param name="name">example</param>
      <param name="count">1024</param>
      <msg>Backup process 'example' completed successfully. Processed 1024 file(s).</msg>
    </banner>
  </doc>

There are 3 types of banners:

• Warnings;
• Notifications;
• Information.

In the example given above, we have created an informational banner, which will display after the backup process has been completed.

Extra features

A banner can be created automatically after certain operations.

Successful action

If you want to inform a user about a successful operation on a regular basis, you need to describe additional messages for the corresponding function. This function can be used only for functions containing the "sok=ok" parameter, i.e. the functions that require users to fill out a form. The message name must be "msg_success" for an edit form, or "msg_success_new" for a creation form. In the messages of this banner, you can use any parameter from the form, enclosed with underscores.

Example:

  <messages name="db.edit">
    ...
    <msg name="msg_success_new">Database '__name__' created successfully</msg>
  </messages>

Group operations

When performing group operations, such as delete, suspend, resume, etc. banner can be shown both for successful and failed operations. This type of operations doesn't have a form, and all messages are described in the alert section with the following names:

 group*result*_*func*

where result - is the operation result. Possible values are success or fail in case of successful or failed operation correspondingly; func is a function name.

In the message text, you can use only one __count__ variable, which contains information about failed or successful operations from the group.

Example:

  <messages name="alert">
    ...
    <msg name="groupfail_restore">Failed to restore data from __count__ backup(s). For more information move your mouse cursor over the error name.</msg>
  </messages>