Understanding fieldviews and view templates

In the previous section on data models, we saw how to create tables consisting of fields and rows.

In this section, we will see how to build user interfaces which take data from these models to display to the user.

For example, we might have a table of club members. Each row in the table will contain the information in the fields

  • member's name
  • user name
  • avatar (the image they upload for their account)
  • date of birth 
  • fees paid
  • attendance at meetings

Saltcorn uses two distinct concepts which work together to create the whole user interface:

  • Field views control how an individual field value is displayed to the user
  • View templates control how multiple field views are combined with interaction patterns to display on a page

View templates

Views are specific ways to display your the data from your table. 

On a member's account page you might want to let users see all the infomation you have about them, but only edit their username and avatar. 

On the meeting page you might want to display all the members that attended on that date. 

On an admin page you might want to edit the fees paid.

View templates include 

  • Show - display a single row
  • List - a table with multiple rows and specified columns
  • Edit - creates a form with inputs for the fields in the table

Create a view

Menu > Views > Create View 

  • View name, for example, User account settings
  • Template - Select from the options
  • Table - The table you want to create the View from. 
  • Different view templates will be configured in different ways.

See Creating Views for more details.

If this all seems a little abstract, here are some examples of what we mean by view templates capturing interaction patterns:

  • Forms: a form consists of a number of input entry boxes. The form can be displayed blank, for creating new data, such as adding a new member's details. Or it can be displayed with existing values in the input entry boxes. This can be to edit a member's address, for example. In Saltcorn, this is called the Edit Template. In the configuration for the Edit template, we specify the layout of the form with the drag-and-drop builder.
  • Display: Show a single row from the database using a specified layout. This shows the data from just one row of the database. This would be the View to use when you want to show which memebers were at the meeting, but not let them edit. In Saltcorn, this is called a Show Template. It is configured by specifying the layout with a drag and drop builder.

Plug-ins for View templates

View templates can also be provided by plug-ins. View templates are completely independent from field views, in that a view template should be able to incorporate a field shown as any field value, even if it comes from a different plug-in developed without any considerations for compatibility between different field views and different view templates.

Field views

Every field in a table is assigned a specific type. For instance, a name will be of type String, date of birth will be of type date, and age will be of type Integer. 

Field views control how individual values of particular types are shown to the user. This can be to either Show or Edit the value. The field view is the way the value of a particular type will be displayed. It is at the user level that we decide if the user can edit or just see the value of the field. 

When a field is a date, there are many possible field views. A date can be

  •  in a variety of formats according to location and culture (think about US and UK date formats)
  • in a relative format, for instance "2 days ago"
  • in the ISO 8601 format (which makes programmers happy and ordinary users miserable)
  • entered with a single text entry box, expecting any of the above formats
  • entered in a set of three input boxes for year, month and date
  • picked with a calendar pop-up

When you need to choose a field view, Saltcorn gives you only choices that are applicable.

Options

Some field views also have options, for example:

  • Placeholder text, that is text displayed in the input entry box as a hint, before anything is entered by the user.
  • Date fieldview "format" which allows you to enter your own date format using a small coding language where %d is the date, %m is the month %y is the year.

Field views can be provided by plugins. Plugins can also provide new field views for types that are defined in Saltcorn core or in other plug-ins.

Composite views

Some view templates are based on underlying views. This gives an enormous flexibility in how user interfaces can be constructed. A simple example is the Feed view template, which displays a number of rows from a database table, one after another or in columns. The feed view template handles how the numerous rows are joined together in the display, but delegates the display of the individuals rows to an underlying view, typically a view of the show view template. Therefore, to build a user interface based on feeds (such as you might see on a social network, with one post after another). You first build the view of each individual row using the Show view template, and then you build the Feed view, choosing the previously built Show view as the underlying view. When you finally have a working Feed view of multiple rows, you typically want to go back and adjust the Show view to get the overall user interface right.