Homepage Routing - Atavist/developer GitHub Wiki
On November 7, we deployed Homepage Routing (originally called Collection Routing), a feature that enables the creation of more than one homesite page with unique URLs. The feature is in its early stages, and will likely change over time, so we are doing a controlled, limited rollout. Atavist’s Homepage Routing makes it possible to create multiple URLs (e.g. my-organization.atavist.com/my-page, my-organization.atavist.com/another-page), map each to a specific Homepage Template, and optionally to pass a set of data to it when it is rendered. A route is essentially a map from a URL to a controller. This feature can be used to create category pages that list projects by tag and even secondary pages like About Us and Terms of Service.
###Requesting Access
To use this feature, you must first request access from Atavist Support. After access has been granted, go to your Settings > About page. Here you’ll see an area titled Homepage Routing.
###Creating Routes: The Basics
In the Homepage Routing area, click the blue + Add button to create a new route. There are four fields for every route: path, label, template and data.
Path defines the url of the route, similar to a story slug. If you were to set this field to “my-page” and the handle of our organization is “my-organization”, the full URL for this route would be http://my-organization.atavist.com/my-page. (Note that the domain would be different if you were using a CNAME). Paths should be lowercase and cannot contain forward slashes.
Label is a human readable description of the page. This field is available in an experimental navigation rendering feature, but is also useful as a way to keep track of homepage routes.
Template allows you to select which Homepage Template will be used for the route. A single template could be used for all routes (including Atavist’s default Homepage Template), but separate templates can be created as needed. For example, it may make sense to have different templates for the homepage, tag-based category pages, and an About Us page.
Data allows unique data to be passed to the page at render time, allowing differentiation between multiple routes all using the same Homepage Template. See below for more details.
###Using The Data Object: Arbitrary Data
The Data object can be used to pass in arbitrary data which is accessible in the Homepage Template through Mustache tags. Here is an example in which a single Homepage Template is used for multiple routes, each with a different title to display.
- Pick a custom key. Here we will use “custom_title.”
- In the template HTML area, reference the key in a Mustache tag:
- On Settings->About, create a new route and define the custom key in the data object:
- Repeat step three for any routes needed, and each one will display a the value of custom_title when rendered.
###Using The Data Object: Request Parameters
The Data object can be used to allow Request variables to be passed through to the Homepage Template. Add an array to your Data object named request_params. This should be an array of parameter names. For example:
{
"request_params": ["search"]
}
This will allow URL query string parameters to be accessed and used in the template. In this example, if the URL were https://myorg.atavist.com/my-search-route?search=My+Search+Term, you could display it in the template with this:
<h1>{{search}}</h1>
And, display a loop of matching projects with this:
<ul>
{{#library search="{{= search =}}"}}
<li><a href="{{url}}">{{{title}}}</a></li>
{{/library}}
</ul>
###Using The Data Object: Library Parameters
If you aren’t familiar with the basics of Homepage Templates, including the library loop, please read this document first: http://help.atavist.com/developers:collections.
The Data object can also be used to pass in parameters to a Homepage Template’s library loops. This presents a problem, since library Mustache tags contain these parameters, and nested Mustache tagging in this case will fail. To get around this, library parameters should be added to a special object in the Data object named library_params. In the template, these parameters are referenced using {{= =}} syntax, instead of the usual {{ }} Mustache syntax. Here is an example in which a single Homepage Template is used by multiple routes, each of which displays only projects that have a particular tag assigned to them.
- In the template HTML area, define a library loop. Note the syntax of the tag variable:
- In the Data object for a route, define library_params, and add the tag parameter to it:
The loop in this homepage should now display only projects with the “sports” tag assigned.
###Homepage Routes And Story Slugs
Every URL must be unique, so it stands to reason that homepage routes can’t ever be the same as existing project URLs. Project URLs are settable on the main Publish page. If a project had the URL “my-project” assigned, you would not be able to create a homepage route with a route of “my-project,” and vice versa.
###Special Case: The Root
A homepage route can be created for your root homepage: https://your-domain.atavist.com. To do this, create a normal route using this PATH: {root}. Note that if a root route exists, the template specified takes precedence over the HOMEPAGE TEMPLATE field defined outside of Homepage Routing.
###Navigation Object
A navigation array is made available to homepages containing all defined homepage routes, including the home. This can be used to render navigation. Here is an example of an implementation of this feature:
