ShowPage
Concepts

Relational model

Saltcorn is based on the relational data model that you may know from SQL databases like MySQL, PostgreSQL. If you already know this model, you can skip this section.

Saltcorn tries to maintain a well designed database as you construct your application and uses PostgreSQL. One of our aims is that if you outgrow Saltcorn, you can take the generated database with you and use it as the foundation for a developing your application.

In the rest of this section, I will attempt to describe the basic concepts of the relational model. Alternatively you may also refer to to Wikipedia pages for relational database and relational model.

Types

The type is the smallest unit of data storage. It describes a specific variety of data that you may use to build up your database. Some examples of types are strings (a list of characters that can make up a description, a word, or a sentence), the integers (the whole numbers), floating-point numbers, but also more complex data such as a date (a point in time including both the day and the time of the day).

When we talk about types, we are still at the abstract level of talking aboutall strings or integers etc. Concrete objects such as a concrete string (such as "Hello World!") or a particular number (e.g. 17) are not types but are values. Every value has a type.

Types are defined in Saltcorn in plug-ins. Even the most elementary types such as strings or integers are defined in the base plug-in.

Fields

A field gives a type more context. First of all, it gives to type a label so you can perhaps understand a little bit more about what it represents. For example, we can say that a particular field is string with the label "Full name". We might show it on a computer screen like this: Full name: Ron Weasley. Sometimes, the field might also restrict values that it can take. For instance, you might specify that a field Age is an integer (a whole number) which is never negative.

Row

A row is a collection of fields describing an object, perhaps a physical object. If we are interested in people, we might decide that a person described by their name, age and height. In this case we would use those three fields (name, of type string, age of type integer and height of type integer or floatingpoint number) to describe a single person.

Tables

A table is a collection of rows that all have the same fields. You can think of the table as a grid or as a spreadsheet where the columns, going down, denote the fields and the rows, going across, described particular a particular object, event or person, with the fields organising everything that is known about that object so the full information can be displayed in a neat table.

Some of the rows in the table may have some missing values. For instance, for a particular person we may not know their age. When designing a table you need decide which fields can be missing and which are required.

In addition, you may decide that across the table, some fields must have unique value. For instance, this wiki is stored in a relational database with a table that has to fields: title and contents, both string. The title of every page is unique so you cannot have two pages that have the same title.

Fields and tables are created in Saltcorn by users with administrative privileges through the Saltcorn user interface. First you create a table and then create the fields in that table by choosing their type and giving them an name.

Keys

Sometimes, when we have two different tables, a special field in one of the tables can be used to relate the two tables.

Fieldviews

A field view is a particular way of showing to the user the contents of a single field. For instance, for the Date type, which represents a point in time including both day and time of the day, this can be shown to the user as an absolute time (27 August 2018 14:46), as a relative time (one year and nine months ago) and if edited can be picked with a calendar date picking widget or entered manually.

Views

View is a particular way for users to see or edit data in a table, from one or more rows. You can think of this as a screen or as a user interface. A view might be a form that can edit or create a new row, or it might be a grid of data showing multiple rows, or multiple rows displayed on a map or cross a board, or particular way of seeing a single row.

Relational databases also have a concept of views, but this is not related to the view in Saltcorn.

New views in Saltcorn are defined by the admin user, through the user interface by applying a view templates (see below) to a table and filling in the options for that view template.

View templates

A view template, as the name suggests is a template for creating a new view by applying it to a table. The view template will also define what further information is needed in order to create the full view.

View = View templates applied to table with specified options

View templates are defined in plug-ins. Some basic view templates are defined in the base plug-in, and further view templates can be added by activating new plug-ins

There are two different kinds of view templates, basic and composed. Views created from basic view templates do not rely on other other views. They are specified in their own right by applying a view template to a table and specifying the options. Composed views, on the other hand, need other views to be created first and then are specified in terms of other views. Composed views still follow the equation of being a view template applied to a table with specified options, but the options to be specified include selecting other views (which may or may not be of the same underlying table). Plug-ins may provide both composed and basic view templates.

Basic view templates

The base plug-in provides three different basic view templates named edit, list and show.

The edit view template creates forms for creating new or editing existing rows in a table. It has somewhat limited customisability consisting only of choosing the fields in the form, and if fields have been left out of the form, a default value may be specified.

The list view template creates a grid-like view of the table. You may add fields from joins with related tables, links to other views or aggregations (calculations over related tables).

The show view template will show one row from the table. It has a more flexible customisation in its layout and you can also add fields from joins with related tables, links to other views or aggregations (calculations over related tables).

Composed view templates

  • feed: a feed view is a view of multiple rows shown one after another. The display of each row in the feed is determined by the chosen underlying view.
  • list-show-list: the list-show-list view is composed of multiple related views. In the full version, on the left hand side of the screen is shown a list from which a single row can be chosen. On the right hand side of the screen is shown at the top a view of that row and below that views of rows that are related to the chosen row, of the same or of different tables. However the list on the left hand side is optional in which case only the view of the primary row and the related tables below are shown.
  • kanban board: a kanban board is provided by the kanban plug-in. What is shown in each card is determined by selecting an underlying view.

Pages

Pages can be built with a drag-and-drop page builder. Pages are not tied to specific tables, but they can include views that display content from the database. You can use tables to decorate views with static content, and to combine multiple views. These views can share a state, for instance a subset of the data, and this can be used to build clickable dashboards.

Plugins

Plug-ins extend Saltcorn with new functionality that you cannot create yourself through the user interface. They are written in the JavaScript programming language and when activated can add to a Saltcorn application:

  • Types
  • Fieldviews
  • View templates

Packs

Packs are collections of defined tables and views, along with the plug-ins needed to support them. You can use them to quickly get started with an application by adding bundles of functionality and then modifying it.

Whereas plugins extend Saltcorn with functionality that you cannot define to the user interface, packs only replicate functionality that you could define yourself. They are only there to save you time and not to extend with new functionality.