Simple datatable

In this tutorial we continue with the page "Hello World". You should at least have finished the tutorial: save form data. We use the code you made there. After adding the datatable, your page will look like the image below:


finished page
Add a datatable to your page

There are a lot of ways to show data, but one of the most common ways is to present it in the form of a table, where each field is shown in a column, with headers consisting of the field name, and all the data is listen in rows. Since this format is used so often, we made a special advanced table: datatable block in Rual studio that returns a datatable with several options to select, search, filter, edit and delete the data. These options can be switched on or off, as you will see in the last paragraph of this tutorial.

Of course it is also possible to make your own table in Rual. You can use the table: basic table block and style it to your own liking with table: row and table: column blocks.

Let's start with the datatable. The page section in the blueprint you made so far, should look like this:


blueprint start

We will fill the body of our card with the datatable. First we need some space. Select the blocks in the footer (hold right mouse button and drag) and move these a bit further down. In the cards: basic card block, pull out the body pin and select the advanced table: datatable block.

The advanced table: datatable has a lot of pins, so a lot of finetuning can be done. The pins that have a solid color (storage and columns) are required. The opaque pins are optional. - TIP - If you click on the text of the pin, a label with a short description will open. You can read these now for all pins of the advanced table: datatable to get an impression of the possibilities.

To fill the datatable, start with the storage pin, and use the right mouse button to pull it out. Using the right mouse button will skip the menu, selecting the "most used" option immediately. In this case it opens the storage: selector, and you will see the available storages. Choose registrants.


storage selector

Select fields

The columns pin is where you select the fields that you want to show in the table. Pull out the pin and select fields: get multiple. - NOTE - You will see a list with all fields that are defined in your cluster. Your storage probably does not have all those fields! But there are some special fields that are noteworthy here: _meta.created and _meta.guid


field selector

Every document that is saved in the Rual platform, has metadata that tell you when the document is created, which user and blueprint created it, when it was updated and in which storage it is stored. Also every document has it's own GUID, a unique identifier. The _meta.guid field makes it easy to retrieve documents within your program.

For the datatable, select the _meta.created field by clicking on it. After clicking on a field, you will see a little checkbox indicating that this field has been selected. Made a mistake? Just click on the field again and it will be deselected.
- TIP - The colored dots behind the field names indicate the field type, similar to the colors of the pins. A green dot indicates a value type (string), a blue dot indicates a date type. Clicking on the trash bin will remove the field definition. We will come back to that later. It is not used often.

Continue selecting the fields that we used in the form: firstname, lastname, phonenumber and birthdate. Change the order of the fields with the up and down arrows on the right, this sets the order in which the columns are shown.

metadata
column fields

If you click on the view button in the page block, you see the standard datatable in your frontend web page, like in the picture below. If you do not see any data, just fill out the form a few times to create some extra registrants. Just press the register button you created in the previous tutorial.


first datatable
Field format

In Rual all dates are stored as timestamps. For example, in the screenshot of the metadata above, you see "created": 1580163827. In the datatable this date is changed to a human readable format. But still it looks a bit awkward with the time in seconds. And for the date of birth you do not want to show a time at all.

To set the format of fields in the datatable, use the row render pin. Drag this out and choose inpin function: select. Type renderDatatable to create a new function. Hit enter and you see four new blocks:

  • the inpin function: select block, connected to the datatable
  • the private function block, where the function's flow starts
  • the ui: return row render block, with all selected fields in the same order as the columns
  • the get: get fields block, again with all selected fields in alphabetic order
new function
function blocks

Move the function a bit to the side, to create some room to work. You can remove the fields where you want to use the standard format. Use manage fields to do this.
From the _meta.created pin pull out a line and select format: date. Connect the date pin to the _meta.created outpin from the get: get fields block. Pull out the format pin with the right mouse button to get a custom: value block. Type the format you like to use in this block. Go to momentjs.com to see the formats Rual supports. Type YYYY-MM-DD (HH:mm) in the text field. Do the same for the birthdate field, use MMMM Do YYYY.

Your blueprint code now looks like the picture below. If you go to the frontend page again, you will see the datatable with the selected formats.


updated datatable
Inline edit

In this tutorial we add one more gadget to our datatable: inline editing. As you will understand, you cannot just allow anyone to change the data you present on your website or in your in company application. That's why you can select a scope for the inline edit. This way you can organise who can do / see what.

Rual advises to set the basic scope set to [storagename]_view, _create, _update and _remove. You can set any scope you like, and these will be remembered and can be used throughout your cluster in Rual. Pull out the inline edit scope pin, and select the scope registrants_update. You can create it right here if it does not exist yet.

Pull out the inline edit pin, select fields: get multiple and select lastname and course. Please note, we have not used the field course before, so you can create it here. Choose "string" as field type.

If you check out your frontend page, you will see a pencil next to lastname, but you will not see the column with the new course field. Can you figure out why?

Go back to the columns pin and use the manage fields button in the fields: get multiple block to add the field course> there. Now you will see this column too in the datatable.

inline edit blocks
inline edit frontend

Inline edit is one of the built-in options that make it very easy to change your data, while the scopes make it possible to control access to it.

Options

The checkboxes allow you to do something with multiple selected rows at the same time, for example to export them, or to change the contents of a field for more records at once. For this, you have to define a button and a function that handles this in the backend. It is not something you can select in the advanced table: datatable block.

In the frontend page, you see a little trashbin at the end of every row. The trashbin deletes the document. Go ahead and try it. You will get a warning first. You can add a scope to the remove button, so only some users will have access to it. Or you can decide to hide the remove button for everyone. For these options you can use the remove scope and hide remove pins in the advanced table: datatable.

Further important pins in the advanced table: datatable block are:

The detail button edit button pins connect to a function to either open a modal with a form or a new page for zooming in on the data or editing it. Of course, you can set a scope on these actions too.

The query pin and the filters pin make it possible to select data from the storage. Either by preselecting (the query) or by offering predefined filters that will be visible in the datatable as buttons in the filter section.

Check out how to use these advanced options in the tutorial: advanced datatable.

This ends the datatable tutorial. There are several ways to continue the tutorials now, an easy one with a lot of impact is to go to tutorial: simple styling. If you have not done the tutorial: form validation yet, this is also a good point to go there.