Getting Started (Sample Application Tutorial)

Search
Feedback

About

This tutorial will guide you through the process of creating a sample web application with Structr, featuring two entities, four pages, and a fully functional (graph) editing setup. It is intended as a step-by-step guide to the more complex features of the Structr backend UI.

It is based on the new Structr 2.0 release and is a replacement for the outdated article at Data Binding and Editing Tutorial.

Content

Assumptions

We assume that you’ve successfully installed and started Structr 2.0 and have access to Structr’s admin UI under the base URL http://localhost:8082/structr/#.

Schema

Step 1

In this first step, we create the neccessary schema elements defining the data model:

  • Project
  • ProjectMember

Login with admin/admin (or the admin user of your choice) and go to http://localhost:8082/structr/#schema. You should see the following picture:

fig

You can move a single schema node with the mouse, or multiple schema nodes by holding the left mouse button and drag a rectangle around a group of nodes:

fig

Step 2

Now enter “Project” into the “New type” input field in the header bar and click “Add” (or hit enter). Repeat with “ProjectMember”.

fig

Step 3

Connect the nodes by a relationship.

fig

Step 4

Click on the white empty relationship label and enter the relationship type, e.g. MEMBER.

fig

Step 5

Click on the pencil icon on the Project node to open the edit dialog.

fig
fig

Step 6

Scroll down to the bottom of the dialog content and click on the green plus icon:

fig

Step 7

Add the new local attributes description of type String and date of type Date.

fig

Step 8

Click on the “Remote Attributes” tab to see the list of remote attributes. A remote attribute is automatically added by Structr for each incoming or outgoing relationship between schema nodes.

fig

Step 9

Click on the attribute’s name memberProjectMembers and rename the attribute to projectMembers. You can rename remote attributes at any time but be aware that you have to change any references to the attribute manually.

fig

Step 11

Repeat the above with “ProjectMember”: Create a new String property role and rename the remote attribute to projects.

Pages

Next, we need to create four pages which will act as the four main views of our web application:

Name of the page Description
projects This is the index page of our web application, will show a list of all projects
project The details page for an individual project, will show project details and members
persons The overview page for project members, will show a list of all persons
person The details page for a person, will show all projects this person is involved in
Step 12

Click on the Pages link in the main menu bar to get to the page editor.

fig

Step 13

To have nice looking pages, we import a static page as a template. Click on the left-most icon above the preview area:

fig

Step 14

Use http://getbootstrap.com/examples/jumbotron.

Enter the template page’s address into the URL input field, hit “Tab” to let Structr automatically set the page name. You can overwrite the page name. Check the “Visible to public” selectbox to make the page visible to everyone. Then click on “Start Import”.

fig

Structr will download the page and all connected resources in the background and create the page named “jumbotron”:

fig

Step 15

Click on the page name in the active tab above the preview area and rename the page to ‘projects’.

fig

Step 16

Before we create the other pages, let’s create some so-called “Shared Components”. Shared Components are (mostly identical) page elements which are shared between multiple pages. To avoid redundancy, SCs are stored in a central place and only linked into the page tree.

To create a Shared Component, just drag the element you’d like to transform into the “Shared Component” drawer on the right. In our example, we start with the “head” element of the first page.

Pro tip: Collapse the nested page elements and open the Shared Components drawer before dragging the “head” element.

fig
fig

Step 17

Now let’s remove any page elements from the page we don’t need. In this example, we remove the jumbotron element (div.jumbotron) and the row below the main container div by clicking on the Remove icon which becomes visible when you hover over a page element.

fig

Step 18

Before we clone the page, we let the page’s name be displayed in the header by clicking on the text “Project page” in the preview window and enter the template expression ${page.name}:

fig

Step 19

Now collapse the page tree and click on the “Clone page” icon, the first icon right to the page name when you hover over the page element.

fig

A new page will appear, containing the same elements as the original one, including the Shared Components.

Step 20

Repeat cloning the page and rename the pages accordingly.

fig

Create Form

Step 21

Click on the “projects” page tab above the preview to display the page preview. Open the body and the div.container elements in the “projects” page. Then open the “Widgets” drawer on the right-hand side and drag the Widget “Bootstrap > Forms > Panel with Create Form” onto the div.container element in the page tree.

fig

Step 22

In the dialog “Configure Widget”, enter “Project” into the “Type” field and click on “Append Widget”.

fig

Step 23

After the widget has been added, you might drag the new element div.panel.panel-default above the footer element.

fig

List Page

Step 24

Now we insert a table into the page to display the project list. In order to demonstrate how repeaters and data binding work in Structr, we select the “Bordered Striped Table” widget and drop it onto the container div, then move it above the hr element:

fig

After inserting and moving the div.table-responsive element, it should look like this:

fig

The table is still static. To make it display a list of projects, we need to define a query on one of the tr elements in the table body. The other table rows can safely be removed.

Step 25

Click on the properties icon and in the dialog, click on the “Query and Data Binding” tab, then enter the query projects?sort=name, click on “Save”. Then enter “project” into the “Data Key” field and save. The type part of the query is case-insensitive and can be written in singular or plural form, so Project?sort=name and project?sort=name would be equivalent.

fig

Step 26

After closing the dialog, the tr element should have a colored icon. Expand the element and change the text of the frist three content elements to ${project.id}, ${project.name}, ${project.projectMembers} and remove the fourth content element.

fig

Step 27

To finalize the table, we need to change the column headings. Collapse the body tr and expand the thead tr element. Enter the texts “Id”, “Name”, “Members” and “Actions” into the content nodes. Alternatively, you can directly click on the column headings in the preview area to edit the text fields.

fig

Now it’s time to open the project page in a new tab. Just click on the eye icon in the preview tab.

fig

A new browser tab (or window) will open, requesting the page’s external URL http://localhost:8082/projects:

fig

We can already create projects using the form.

fig

Step 28

In the next step, we create a link from the project’s id and name to the “project” page. Go back to Structr’s page editor and open the tbody tr td element. On the right-hand side, open the “HTML Palette” drawer and drag an “a” element onto the content node in the td element in the page tree.

fig

Step 29

The new a element will automatically wrap the content node. Repeat the action with for the name column.

If drag and drop doesn't work in the Structr UI, try again after reloading the page.

This is how it should look like after adding the two a elements:

fig

Step 30

Now open the properties dialog of the inserted a element, select the “HTML Attributes” tab and enter the template expression /project/${project.id} into the “href” field.

fig

Step 31

Repeat this with the second a element, but use the alternative template expression /project/${project.name}.

In Structr, you can create links to object names or UUIDs. A link to /project/49ae1efa34da4578b722d2b35b013305 adresses the page "project" and the object with the UUID 49ae1efa34da4578b722d2b35b013305 while /project/Testproject%201 links also to the page "project" but to the object with the name "Testproject 1".

Details Page

Step 32

Activate the “project” page preview and open the body element in the Pages Tree View drawer. Drag a “content” element from the HTML Palette onto the container div. Move the new content node above the hr element.

fig

Step 33

Open the text editor to edit the content node by clicking on the pencil icon and replace the “#text” placeholder by the following template expression which is wrapped in HTML: <h1>${current.name}</h1>. You can add more text and template expressions. For a comprehensive list of template expresesions, go to the Scripting section.

The keyword ``current`` references the current details object which is looked up by UUID or name, taken from the last part of the URL path.

After this, the page preview looks like this:

fig

Step 34

The reason is that the preview page is requested without details object, so there’s no project to display a name for, and we forgot to set the content type of the content node to text/html. To fix it, open the editor again and set the content type accordingly. You can also enter the content type through the properties dialog.

Your project details page should look like this:

fig

Step 35

Repeat the above steps for the “ProjectMember” class, using the pages “persons” and “person” as list and details page. We recommend to use ProjectMember?sort=name as REST Query and member as Data key. The columns should be id, name and projects. Make sure to create some example data for the “ProjectMember” entity class.

Edit Actions

Step 36

As a final step, we’ll add some editing functions to the project list table. Go back to the “projects” page and open the td element which renders the last table column by simply clicking on the table cell in the preview area.

fig

Step 37

Drag a “button” element from the HTML Palette into the td element and change the placeholder text to “Edit”.

fig

Step 38

Open the button’s properties dialog and go to the “Edit Mode Binding” tab. Enter ${project.id} in the “Element ID” field, “edit:Project” in the “Action” field and “name,projectMembers” in the “Attributes” field. This configures the button to trigger the “edit” action for the “Project” class on the instance with project.id and take the attributes name and projectMembers into account.

fig

Step 39

In order to work correctly, we need to define which columns should render input fields in the automatic edit mode. For name, simply set the “Attribute Key” field to “name” in the properties dialog, tab “Edit Mode Binding” of the a element wrapping the content node with the template expression ${project.id} and ${project.name}.

fig

Step 40

Finally, we have to define a page element which should act as a container for the edit parameters which is typically the repeater element, here the table body’s tr by entering ${project.id} into the “Element ID” field.

fig

Step 41

After that, you should be able to edit a project’s name. To enable editing the project members, enter “projectMembers” into the “Attribute Key” field of the “Edit Mode Binding” settings of the td element rendering the project members column. As “Data type”, enter “ProjectMember[]” to tell Structr that to render a select field for a collection of “ProjectMember” objects.

fig

As a result, you should be able to edit a project’s members on the projects page http://localhost:8082/projects:

fig

Graph-Browser

About this article
Last change 2017-05-04
Topics FrontendStructr 2.0