For illustrating how an app powered by the Interface Builder works, we’ll take a closer look at the Example Application, a simple yet feature-rich JS web application for easily getting started with the Interface Builder.
Please refer to Getting Started with the Interface Builder or the Readme at GitHub for details on how to install and run the Example App locally.
The JustRelate Web Interface Builder consists of two main components interacting with each other: a backend that transparently manages your content, and a JavaScript library (the SDK) that acts as a content management layer in a web application based on React. React is Facebook’s solution to building interactive web interfaces using self-contained components written in JavaScript. The Interface Builder SDK utilizes React to access and render the content in your Interface Builder instance. Editors can create and edit this content in place via the Interface Builder’s user interface that can be found at edit.scrivito.com.
After setting up and launching the Example App, it is served from the “src” directory of your local repository, initially via the “catch_all_index.html” file. Let’s take a look at this file first:
The <head> doesn’t contain anything special, except for the included “js_snippets_head.js” file. If, for example, your site makes use of one or several third-party services, provide the code that needs to be run in this file. Analogously, “js_snippets_before_body_end.js” is included in the <body>. It is for letting those services render additional markup, in case they need to.
Obviously, by default, the only visible part in the <body> of “catch_all_index.html” is a <div> element whose ID is “application”. Into this element everything a page consists of will be rendered by the “index.js” JavaScript file which is then loaded (from the “src” folder):
The call to “ReactDOM.render” does exactly that. It renders a component named App into the “application” DOM element mentioned above.
As you might have guessed, App is a function contained in “App.js”. It displays a page by generating a navigation and rendering the contents of the current page. In case the latter cannot be determined, an error message is displayed.
Let’s take a closer look at the App function.
App renders the current page by calling the Scrivito.CurrentPage React component built into the SDK.
Initially, the current page is the homepage contained in your Interface Builder instance. As the visitor navigates the website, the current page changes, of course.
Now, at startup, how does Scrivito.CurrentPage know which object in your Interface Builder is the homepage?
To find the homepage at startup time and render it, <Scrivito.CurrentPage /> determines the content object whose path is “/”. As the visitor browses the website, the page to become the current page is identified by the content object’s id contained in the linked URL.
All content in your Interface Builder is stored in attributes of content objects. To be able to have different types of objects (e.g. homepages, landing pages, blog posts), you can define object classes (models) and provide them with a set of attributes of your choice.
To get an overview of the object classes the Example Application is equipped with, let’s take another look at the project directory, this time at the “src/Objs” folder.
The individual page types defined for an Interface Builder app are represented as folders named after them. Each folder contains up to four JavaScript files, one for the model class (e.g. “HomepageObjClass.js”), one for the component that renders its instances, one for the CSS, and one for configuring how attributes are presented to editors when they edit the properties of an object. This analogously applies to the widget types in the “Widgets” directory.
Next to various page types, there is one for images, too. If you open the “ImageObjClass.js” file in the Image folder, you can see that image objects are regular content objects, meaning that they can be given attributes.
Now, back to pages and how they are rendered. First, all content is rendered by the React component that has been provided for the instances of an object class, i.e. the pages of a specific type. Second, all pages whose content is meant to be editable usually have an attribute of the widgetlist type. In the Example App, it’s named body, but you can name it whatever suits best. It is this widgetlist attribute into which the main content of a page goes: the widgets an editor chooses to place on the page.
So, displaying a page breaks down to rendering the parts common to all pages of that type (header, navigation, footer) plus the widgets contained in the body attribute. All the React component of the page type needs to do is render this attribute:
This causes the contents of the body widgetlist to be rendered by the widgets’ corresponding React components. Let’s look into the “src/Widgets” folder of the Example App directory.
The Example App comes with a considerable amount of widget types you are free to customize and extend. As with object classes, widget classes define the attributes of their instances, and for rendering them, a React component is required.
Many if not most widgets have properties that cannot be edited in place. The image widget, for example, lets you specify its alignment via the equally named attribute. For making it editable on its properties dialog, the model class can be combined with a configuration using Scrivito.provideEditingConfig:
Some components of the example application have been placed into directories underneath “src”, either to keep the app structure clear, or because they are used in several places, or both. The “Components” directory, for example, contains the React components for the navigation, the footer, things related to blogposts and other fragments needed on the pages. The “utils” directory is for little helpers, and the “assets” and “config” directories contain just that.
Do you find the Example App useful? Contact us if you need help or advice or would like to give us some feedback!