UI — Ringo 0.11.0 documentation

### Navigation

- index
- modules |
- Ringo 0.11.0 documentation »

# UI

This section will explain the User Interface of Ringo. This will introduce some Ringo specific terminology which is used later in the documentation.

Below you can see an example of a view in the Ringo application.

The Ringo UI is divided into three areas. In the top there is a header. At the bottom the footer and in the middle there is the content.

# Modules

Ringo uses the term “Modul” to describe different data (data types) in your application. Ringo comes with some predefined modules for users, usergroups, roles and the modules itself. Each of those moduls provide an interface with basic CRUD functionality of work witch items of a modul.

Moduls also define some meta data on the data like which actions (Create, Read, Update, Delete...) are available, labels, visibility etc. Further the authorisation is bound to the moduls too and defines and which users are allowed to use the configured actions.

If there is any data in the application which needs to be created by the user and stored permanently in the database it is very likely done within a modul.

Example:: Think of an application to organise your orders in a shopping application e.g. So you will have to store customers, articles, orders, prices, addresses etc. Each of those will be its own modul.

See Commands for more information on how to add new moduls to your application.

## User

The user modul is used to administrate the users within Ringo. It is only available for user with the role “admin”.

The screenshot shows the Edit-Dialog for a user.

> - Login: This is the login name for the user. It is a required field and must be unique in the system.
> - Roles: Each user can have different roles assigned. You can select one or more roles for a listing of available items of the Role.
> - Groups: Each user can be member of different groups. The user will inherit all roles assigned to the group. You can select one or more groups for a listing of available items of the Usergroup.
> - Activated: The user can be activated and deactivated which means that the the user can login to the application.
> - Activation Token: In case the the user is deactived you can define an activation token (usually a UUID) which can be used to activate the user. This field is used while registering a new user. The user needs to confirm the registration by calling an URL with the defined activation token.

## Profile

The profile modul is used to administrate the users profiles in Ringo. It is only available for user with the role “admin” and the owner of the profile (user with belongs to the profile).

The profile is used to attach some additional common informations to the users in the system.

Profiles can not be deleted or created. The creation and deletion is done automatically when creating and deleting the user.

The screenshot shows the Edit-Dialog for a profile.

> - Firstname: The first name of the user
> - Lastname: The last name of the user.
> - Birthday: The birthday of the user.
> - Address: A free text field to give the address of the user.
> - Phone: The telephone number.
> - Email: The users email. Is used to send notification mails in the system.
> - Web: A URL to the users web presence.

## Usergroup

The usergroups modul is used to administrate the usergroups within Ringo. It is only available for user with the role “admin”.

Groups can be used to assign a defined set of roles to multiple users. Further the membership of groups can be a criteria on the permission checks.

The screenshot shows the Edit-Dialog for a usergroup.

> - Name: This is the name for the usergroups. It is a required field and must be unique in the system.
> - Roles: Each usergroup can have different roles assigned. You can select one or more groups from a listing of available items of the Role. A user will have all the roles of the groups he is member of.
> - Members: Define the members of the usergroup. You can select one or more groups from a listing of available items of the User

## Role

The roles modul is used to administrate the usergroups within Ringo. It is only available for user with the role “admin”.

Roles are generally used to bind certain permissions in the application to different users. Users who have a certain role will gain the defined permissions. For more information on the authorisation please consult the Authorisation section.

The screenshot shows the Edit-Dialog for a role.

> - Name: This is the name for the role. It is a required field and must be unique in the system.
> - Permissions: Each role can be assigned the permissions to different actions of the moduls in the system. You can select one or more actions from a listing of available and configured actions from the Modul. Users with this role will be allowed to call the action.
> - Administrational role: This flag indicates that this role is an administrational role which means that the user will have permission to call the configured actions without checking the ownership of the item.

## Modul

The modul modul is used to administrate the moduls within Ringo. It is only available for user with the role “admin”.

The screenshot shows the Edit-Dialog for a role.

> - Name: This is the internal name of the modul. It is a required field and must be unique in the system.
> - Label singular: This is the label used for single items of the modul.
> - Label plural: This is the label used for multiple items of the modul (Overviews).
> - Description: A textual description of the modul.
> - String representation: The string representation defines how items of the modul are displayed as a single string like in selection lists.
> - Actions: A list of actions which are available for the Modul. This way you can disable an action complete. Not enabled action will not be listed anywhere.
> - Display: Select the menu where the modul will be listed. Select hide to hide the modul completely

# Permission System

## Authentification

## Authorisation

# Commands

Ringo implements some additional commands which can be used on the shell.

## add_modul

The “add_modul” command is used to add Modules to your application. The command will do needed database modifications and create some skeleton files within your projects as boilerplate for further development.

Usage:

    add_ringo_modul --config /path/to/your/application-config.ini NameOfModul

The name of the modul should be the singular form of a noun.

The actual name of the command may vary if you want to add a modul your a Ringo based application. Please call the command with “–help” option to get a full list of available options.

# API

## lib

class `ringo.lib.renderer.` `TableConfig`(clazz, name)

  The TableConfig clazz provides an interface for configuring the overview of the the given clazz. The configuration includes

  - Enabled features of the overview
  - Which fields should be enabled in the overview
  - Labeling of the fields
  - Rendering of the fields
  - Layout of the table (column width etc.)

  The configuration of the overview is loaded from a an JSON configuration file which is located under view/overviews relative to the application root.

  The configuration has the following form and options:

      {
          "overview": {
              "columns": [
                  {
                      "name": "fieldname",
                      "label": "Label",
                      "width": "width",
                      "screen": "xlarge",
                      "expand": true
                  }
              ]
              "settings": {
                  "default-sort-field": "name"
                  "default-sort-order": "desc"
                  "auto-responsive": true
              }
          }
      }

  The configuration can have configurations for more than one table configuration. The default name of a configuration is overview. The next sections defines the columns of the table. The columns are rendered in the order they are defined. Each column can have the following options:

  - name: The name of the attribute within clazz which should be listed here.
  - label: The label of the field.
  - width: The width of the field. If not units are given the pixel are assumed.
  - screen: Define from which size on this field will be displayed. Defaults to “small” which means rendering on all sizes. Available media sizes: (xlarge, large, medium, small).
  - expand: The expand option is used to expand the referneces values in selections into the literal value of the corrispondig option. Note that this option is only usefull for selection fields in formbar which do not have a real relation attached. In all other cases the reference values are expanded automatically.

  Further the table has some table wide configuration options:

  - default-sort-field: Name of the column which should be used as default sorting on the table. Defaults to the first column in the table.
  - default-sort-order: Sort order (desc, asc) Defaults to desc.
  - auto-responsive: If True than only the first column of a table will be displayed on small devices. Else you need to configure the “screen” attribute for the fields.

  If no configuration file can be found, then add all fields configured in the form configuration to the overview.

  `__init__`(clazz, name)

    Will initialize the configuration of the overview for the clazz.

    Clazz: | The clazz for which the overview configuration should be

    loaded. :name: name of the configuration. Defaults to the “overview” configuration.

  `get_settings`()

    Returns the settings for the table as dictionary :returns: Settings dictionary

  `get_columns`()

    Return a list of configured columns within the configuration. Each colum is a dictionary containing the one or more available conifguration attributes.

  `get_default_sort_column`()

    Returns the name of the attribute of the clazz which is marked as field for default sorting in the settings section of the configuration. If no default sorting is configured then return the name of the attribute in the first column which is configured in the table

  `get_default_sort_order`()

    Returns the ordering of the sort in the table

class `ringo.lib.renderer.` `Renderer`

  Baseclass for all renderers

  `__init__`()

    Initialize renderer

  `render`()

    Initialize renderer

class `ringo.lib.renderer.` `ListRenderer`(listing)

  Docstring for ListRenderer

  `__init__`(listing)

    @todo: to be defined

  `render`(request)

    Initialize renderer

class `ringo.lib.renderer.` `DTListRenderer`(listing)

  Docstring for a ListRenderer using the DataTables Jquery Plugin

  `__init__`(listing)
  `render`(request)

    Initialize renderer

class `ringo.lib.renderer.` `DialogRenderer`(request, item, action, title=None, body=None)

  Renderer for Dialogs

  `__init__`(request, item, action, title=None, body=None)

    Renders a renderered dialog for the requested action on the given item. If not header or body is provided the dialog will have a default message.

    Request: | The current request
    Item: | The item for which the item should be confirmed.
    Action: | The actions which must be confirmend.
    Header: | Custom text for the header of the dialog
    Body: | Custom text for the body of the dialog.

  `render`()

    Initialize renderer

class `ringo.lib.renderer.` `ConfirmDialogRenderer`(request, item, action, title=None, body=None)

  Docstring for ConfirmDialogRenderer

  `__init__`(request, item, action, title=None, body=None)

    @todo: to be defined

class `ringo.lib.renderer.` `ErrorDialogRenderer`(request, title, body)

  Docstring for ErrorDialogRenderer

  `__init__`(request, title, body)

    @todo: to be defined

class `ringo.lib.renderer.` `ExportDialogRenderer`(request, item)

  Docstring for ExportDialogRenderer

  `__init__`(request, item)

    @todo: to be defined

class `ringo.lib.renderer.` `ImportDialogRenderer`(request, clazz)

  Docstring for ImportDialogRenderer

  `__init__`(request, clazz)

    @todo: to be defined

class `ringo.lib.renderer.` `PrintDialogRenderer`(request, clazz)

  Docstring for ImportDialogRenderer

  `__init__`(request, clazz)

    @todo: to be defined

`ringo.lib.renderer.` `add_renderers`(renderers)

  Helper function to add ringo ringo specific renderers for form rendering.

class `ringo.lib.renderer.` `DropdownFieldRenderer`(field, translate)

  Ringo specific DropdownFieldRenderer. This renderer add a small link next to the label to make it possible to jump to the selected item in the dropdown list.

  `__init__`(field, translate)

    @todo: to be defined

class `ringo.lib.renderer.` `StateFieldRenderer`(field, translate)

  Ringo specific DropdownFieldRenderer to change the current state of an item. This renderer will render a combined widget containing a textfield showing the current state of the item and a dropdown with available actions which can be done from this state.

  `__init__`(field, translate)

    @todo: to be defined

  `render`()

    Initialize renderer

class `ringo.lib.renderer.` `ListingFieldRenderer`(field, translate)

  Renderer to render a listing of linked items. Used attributes:

  - foreignkey: name of the foreignkey in the database
  - form: Name of the form which is used to add new items
  - table: Name of the table configuration which is used to list items
  - hideadd: Flag “true” or “false” to configure hiding the add button.
  - nolinks: Flag “true” or “false” to configure completly disable linking.
  - showsearch: Flag “true” or “false” to configure rendering a search field.
  - onlylinked: “true” or “false”. If true only linked items will be rendered
  `__init__`(field, translate)
  `render`()

    Initialize renderer

class `ringo.lib.renderer.` `LogRenderer`(field, translate)

  Custom Renderer for the logbook listing

  `__init__`(field, translate)

class `ringo.lib.renderer.` `CommentRenderer`(field, translate)

  Custom Renderer for the comment listing

  `__init__`(field, translate)

# Scaffolds

## Basic Scaffold

### Navigation

- index
- modules |
- Ringo 0.11.0 documentation »