apostrophe-pages/README.md

# apostrophe-pages

`apostrophe-pages` adds page rendering to the [Apostrophe](http://github.com/punkave/apostrophe) content management system. The `apostrophe-pages` module makes it easy to serve pages, fetching the requested page and making its content areas available to your Nunjucks template along with any other attributes of interest.

`apostrophe-pages` also provides a UI for adding pages, deleting pages and changing page settings such as the title. As part of that, `apostrophe-pages` provides functions to fetch ancestor and descendant pages to any desired depth.

## Serving Pages

By default `apostrophe-pages` renders page templates found in its `views` folder depending on the `template` property of the page. You can override the location where one or all of these are found in order to provide custom templates for your project's needs.

Setting up `apostrophe-pages` is easy once you have the main `apos` object. See the [apostrophe-wiki](http://github.com/punkave/apostrophe-wiki) project for a more complete sample app. In this example we want to render any URL that matches a page slug as a page:

    var apos = require('apostrophe')({ ..., partialPaths: [ '/views/global' ]});
    var pages = require('apostrophe-pages')({ apos: apos, templatePath: __dirname + '/views/pages' });

    // Your app specific routes should come first.
    app.get('/mything', function(req, res) { ... my non-Apostrophe-related stuff ... });

    // Now try to serve anything else as a page.
    app.get('*', pages.serve());

Notice that we set partialPaths to provide global layout templates that can be `extend`ed by our page templates, and set `templatePath` to specify where our page templates area.

## Page Types

The constructor for the pages module accepts a `types` option. In its simplest form, a "page type" is just a template name and a label. If you do not specify a `types` parameter, you get a single type with the name `default` and the label `Default`. this causes `views/default.html` to be loaded to render pages with that type.

However page types can also be extended with custom behavior. See the `apostrophe-blog` module for an example with all the trimmings.

To facilitate code reuse, page types can have a single "superclass" from which they inherit behavior in both the server- and browser-side JavaScript code.

Here is a simple example of specifying the `types` option:

    types: [ { name: 'default', label: 'Default (Two Column)' }, { name: 'onecolumn', label: 'One Column' }]

You can also add types later, for instance when initializing other modules such as our blog module. See `pages.addType`.

`pages.serve` has options that can be used to override its behavior in many ways. Complete documentation for the `pages.serve` function is provided at the top of the function in `index.js` (TODO: work on publishing this as jsdoc).

Your page templates will want to render areas. Just use the page objects passed to you to access them and call the aposArea helper available in anything rendered via apos.partial, which includes page templates:

    {{ aposArea(page, 'main') }}
    {{ aposArea(global, 'footer') }}

## Building Navigation: Ancestors and Descendants

Pages may have a path, separate from their slug, which expresses
their relationship to other pages. Paths look like this:
this:

    home
    home/about
    home/about/staff

The path always reflects the relationship between the pages no
matter what the slug may be changed to by the user. (Clients routinely
shorten slugs to make URLs easier to publish in print, but don't want to
lose the relationships between pages.)

Note that paths do not have a leading /. Multiple roots are permitted,
but typically there is one root page with the path `home`.

Pages also have a rank, which determines their ordering among
the children of a particular page.

### Fetching Ancestors and Descendants Manually ###

`pages.getAncestors` and `pages.getDescendants` can be used to fetch
the ancestors and descendants of a page. `pages.getAncestors(req, page, callback)` delivers
ancestor pages to its callback, in order beginning with the root page.
`pages.getDescendants(req, page, callback)` delivers the children of the page, in order by rank. `req` must be passed to provide a context for permissions (`req.user`) and, potentially, for caching during the lifetime of a single request. It must be either a real Express request object or some other object acceptable to your `apos.permissions` function.

You can optionally specify a depth:

`pages.getDescendants(req, page, { depth: 2 }, callback)`

In this case your callback still receives an array of the immediate children of `page`. However, each of those pages has a `children` property containing an array of its children.

For performance reasons, `pages.getAncestors` and `pages.getDescendants` do not return the `items` property. Typically only the `slug` and `title` properties are necessary to build navigation. If necessary you may use the slug property of a page to fetch the entire page with its items, via `apos.getPage`.

### Fetching Ancestors, Peers and Descendants Automatically ###

`pages.serve` automatically fetches the ancestors of the page into the `ancestors` property of the `page` object given to the page template. In addition, the children of the page are available in the `children` property. And the children of the home page (whether the current page is the home page or not) are available in the `tabs` property. Also, the peers of the current page (children of the same parent) are available in the `peers` property.

If you need to see the descendants of the current page to a greater depth, set the `descendantOptions` option when calling `pages.serve`:

    {
      descendantOptions: {
        depth: 2
      }
    }

You can then look at the `children` property of each entry in `page.children`, and so on.

To do the same thing for descendants of the home page, set:

    {
      tabOptions: {
        depth: 2
      }
    }

You can add a `.children` array to each ancestor in order to implement accordion navigation, in which each ancestor's children are also displayed:

    {
      ancestorOptions: {
        children: true
      }
    }


You can also shut off ancestors, descendants or tabs entirely if you're not interested:

    {
      ancestors: false
      tabs: false,
      descendants: false,
    }

### Fetching Pages by Tag ###

Typically "tree pages" (pages that are part of the tree, i.e. the home page and its descendants) are displayed and browsed like nested folders. But from time to time it is useful to fetch pages based on taxonomy instead.

The `pages.getByTag` method returns *all tree pages on the site* that have a specified tag:

    pages.getByTag(req, 'green', function(err, results) { ... });

And `pages.getByTags` returns all pages with at least one of the tags in an array:

    pages.getByTags(req, ['green', 'blue'], function(err, results) { ... });

When pages are fetched by tag, they are sorted alphabetically by title.

### Filtering Pages by Tag ###

If you already have an array of pages, for instance the children or peers of the current page, it can be useful to filter them by tag. You can do that with `pages.filterByTag`:

    pages.filterByTag(children, 'tag')
    pages.filterByTags(children, ['green', 'blue'])

Again, `filterByTags` returns pages with *at least one* of the specified tags.

*Note that these functions do not take a callback.* They return the pages directly, since they are just filtering an existing array of pages based on their metadata.

## Loading Additional Data

Most sites require that some extra data be loaded along with pages. The data to be loaded is often dependent on the site structure and the unique needs of the project. The pages.serve function supports this via the load option.

The load option accepts an array made up of page slugs and functions. Any strings found in this array are assumed to be the slugs of pages, usually "virtual pages" whose slugs do not start with a leading / and are not directly reachable by navigating the site. Such pages are loaded and added to the `req.extras` property. All properties of `req.extras` are then made available to your page templates. So if you use the virtual page `global` to hold a shared global footer area, you can access it as `global.footer` in your page templates.

In addition, loaders can be asynchronous functions that modify the `req` object in their own ways. Loaders receive the `req` object as their first parameter and a callback to be invoked on completion as their second parameter. The `req` object will have a `page` property containing the page that matched the slug, if any, and a `remainder` property matching additional content in the URL after the slug if the page is greedy, as explained below.

## Second Chances and "Greedy Pages"

Many sites need to go beyond a simple tree of pages, implementing experiences like blogs and catalogs that require "subpages" to exist for every product or blog post, and URLs that contain elements other than page slugs, such as the date and slug of a blog post. This is easily implemented using greedy pages.

While the `req.page` page property is set only if the slug exactly matches a page, the `req.bestPage` property is set to the page whose slug comes closest to matching the page. To be the "best page," a page must meet the following conditions:

Either (1) it matches the requested URL exactly (in which case req.page and req.bestPage will be the same page), or (2) it matches the longest portion of the URL ending in a `/`.

Examples:

Assume there are pages with the slugs `/blog` and `/blog/credits` in the databsae.

1. If the user requests `/blog` and there is a page with the slug `/blog`, both `req.page` and `req.bestPage` will be set to the `/blog` page object. `req.remainder` will be the empty string.
2. If the user requests `/blog/2013/01/01/i-like-kittens`, `req.page` will be undefined, and `req.bestPage` will be set to the `/blog` page object. `req.remainder` will be set to `/2013/01/01/i-like-kittens`.
3. If the user requests `/blog/credits`, `req.page` and `req.bestPage` will both be set to the `/blog/credits` page object. `req.remainder` will be the empty string.
4. If the user requests `/blog/credits/paul`, `req.page` will be undefined, and `req.bestPage` will be set to the `/blog/credits` page object. `req.remainder` will be set to `/paul`.
5. For consistency, if the URL ends with a trailing /, this is not included in `req.remainder`.

This approach allows a mix of "ordinary" subpages and subpages implemented by custom logic in a `load` function that examines `req.remainder` and `req.bestPage` to decide what to do.

### Converting req.bestPage to req.page ###

A loader that decides a page should be rendered after all based on a partial match should set `req.page` to `req.bestPage`. Otherwise the page is considered to be a 404.

### Switching Templates In A Load Function ###

You could implement a blog with custom behavior for different values of `remainder` entirely by setting properties of `req.extras` and examining them in your template.

But it is often easier to use an entirely different template, for instance to render a blog post's permalink page differently from the main index of a blog.

To achieve that in your `load` function, just set `req.type` to the template you want to render:

`req.type = 'blogPost';`

Note that you can set `req.type` to `notfound` to display the standard "404 not found" template for the project.

## User Interface: Adding, Modifying and Removing Pages ##

`apostrophe-pages` provides a full user interface for creating, modifying and removing pages. To enable it, just insert the appropriate markup into your page layout:

    {{ aposEditPage({ page: page, edit: edit, root: '/' }) }}

This helper function inserts the page-related buttons at that point and also the necessary browser-side JavaScript to power them.

## Automatic Redirects ##

If you change the slug (URL) of a page via the Page Settings button, that doesn't tell Google and other search engines that the page has moved. So as a convenience, `apostrophe-pages` automatically tracks the old URLs and provides redirects to the new URLs. Of course, if a new page is created at the old URL, that page wins and the old redirect is not used.

## Search

The `apostrophe-search` module also provides a sitewide search facility. This is implemented by a page loader function that kicks in for pages (usually just one) with the `search` type.

Simple filters are provided to include or exclude results. There is a checkbox for each searchable instance type (such as `blogPost` or `event`) and for regular pages. You can override these with the `searchLoader` option to the pages module. For instance, in `app.js` in a project using `apostrophe-site` for configuration:

```javascript
pages: {
  searchLoader: [
    {
      name: 'page',
      label: 'Pages'
    },
    {
      name: 'blogPost',
      label: 'Blog Posts'
    }
  ]
}
```

Any searchable document whose page type does not have a specific filter is toggled by the `page` filter. *If you do not include a filter with the name `page` then such documents will not be visible in search results.* However this is frontend filtering and should not be relied upon to secure information by keeping it out of search. For that, if you are subclassing snippets, you may use the `searchable` option when configuring the module.

## Context Menu

Apostrophe's "page menu" in the lower left corner is designed to be context-sensitive. Its contents can be overridden for the current page by setting `req.contextMenu` in a page loader function.

Here's an example:

```javascript
req.contextMenu = [
  {
    name: 'new-monkey',
    label: 'New Monkey'
  },
  {
    name: 'edit-page',
    label: 'Page Settings'
  },
  {
    name: 'versions-page',
    label: 'Page Versions'
  },
  {
    name: 'delete-page',
    label: 'Move to Trash'
  }
  {
    name: 'reorganize-page',
    label: 'Reorganize'
  }
]
```

Note that if we set this property, any options we don't spell out will NOT appear. So you can use this option to hide standard choices like "Reorganize."

The standard choices are as shown above beginning with `edit-page`.

"How do I implement my `new-monkey` option?"

The context menu outputs links with `data` attributes based on the `name` property. The links also get classes based on this property as you can see via "inspect element" in your browser.

Consider this browser-side JavaScript, which invites the user to create a new page of type `monkey` when the above link is clicked:

```javascript
  $('body').on('click', '[data-new-monkey]', function() {
    // Get metadata about the current page we're looking at
    var page = apos.data.aposPages.page;

    // Grab the title of the link for use at the top of the modal dialog
    var title = $(this).text();
    // Pop open the "new page" dialog with the page type set to
    // "monkey"
    var $el = aposPages.newPage(page.slug, { type: 'monkey', title: title });
    return false;
  });
```