Basics of building a page

The framework we use now is superb, which was built by Dak around superviews.

The general development approach is to write an HTML template file that incorporates variables from a model to handle any items that may change. Within the JavaScript file, you will set the variables and call this.update() to cause the changes to be reflected in the view. This is a fairly common design in modern frameworks. See the superviews page for particulars of writing templates.

Two shortcomings of this particular framework are that

1. HTML content cannot be inserted via template
2. sub-components cannot be inserted via template

To regularize HTML insertion, I created a helper (in the file ~/helpers/$). It scans the HTML for tags with data-html attributes and uses the value of those attributes as the index into the model. For example, the tags below:

        <h3 class="title" data-html="title"></h3>
        <p class="blurb" data-html="blurb"></p>

would have model.title and model.blurb set as their respective innerHTML when the helper is called like so: $.insertHtml(this.el, this.model);

Components are handled in a Backbone-like way, with regions being specified, and components placed in them using attach or append. This means that any places where a component may be inserted should not be inside a portion of the template controlled by a superviews if directive, as the region element has to exist and remain constant throughout the life of the parent component.

Component regions should usually include a skip="true" attribute, so that superviews will not clear their contents upon update, though it may make sense sometimes to have the sub-components re-render on every update.

As of the refactor, we no longer use Backbone, and data fetching is built in to the CMSPageController. In the init function, setting a this.slug value will automatically trigger a fetch of data from the CMS.

In the onDataLoaded method, the fetched data will be available in this.pageData. Use that data to set up the model and then call this.update(). In many cases, that is all there is to a page or component.

fetch is available and preferred over xhr requesting. This has, so far, raised one issue: fetch does not automatically include credentials (like cookies). In the case of the user API, credentials are needed: fetch(this.url, {credentials: 'include'})