diff --git a/.gitbook.yaml b/.gitbook.yaml deleted file mode 100644 index 3ab43e5d..00000000 --- a/.gitbook.yaml +++ /dev/null @@ -1,5 +0,0 @@ -root: ./docs/ - -structure: - readme: ../README.md - summary: ./SUMMARY.md \ No newline at end of file diff --git a/.gitignore b/.gitignore index dd29da8d..c0fe1eae 100644 --- a/.gitignore +++ b/.gitignore @@ -15,7 +15,6 @@ npm-debug.log node_modules coverage.html coverage -_book # config config/*.yaml diff --git a/docs/.gitbook/assets/upgrade_flow.png b/docs/.gitbook/assets/upgrade_flow.png deleted file mode 100644 index 310b1f5e..00000000 Binary files a/docs/.gitbook/assets/upgrade_flow.png and /dev/null differ diff --git a/docs/INTRO.md b/docs/INTRO.md deleted file mode 120000 index 32d46ee8..00000000 --- a/docs/INTRO.md +++ /dev/null @@ -1 +0,0 @@ -../README.md \ No newline at end of file diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md deleted file mode 100644 index 954c114a..00000000 --- a/docs/SUMMARY.md +++ /dev/null @@ -1,21 +0,0 @@ -# Table of contents - -* [Introduction](../README.md) -* [On Startup](startup/README.md) - * [Instantiation Arguments](startup/instantiation.md) - * [Bootstrapping](startup/bootstrap.md) -* [Basics](basics/README.md) - * [Routing](basics/routes.md) - * [Publishing](basics/publishing.md) - * [Renderers](basics/renderers/README.md) - * [Building Custom Renderers](basics/renderers/custom-renderers.md) - * [Event Bus](basics/event-bus.md) -* [Advanced](advanced/README.md) - * [Storage API](advanced/storage.md) - * [Data Versioning \(Upgrades\)](advanced/upgrade.md) - * [Renderer Models](advanced/renderer-models.md) -* [Plugins](plugins/README.md) - * [Hooks](plugins/hooks.md) - * [Writing A Plugin](plugins/writing-a-plugin.md) - * [Plugin vs. Renderer](plugins/plugin-vs-renderer.md) -* [Glossary](glossary.md) diff --git a/docs/advanced.md b/docs/advanced.md index 53f3c3c7..50bae5f5 100644 --- a/docs/advanced.md +++ b/docs/advanced.md @@ -6,4 +6,4 @@ sidebar_label: Advanced This section covers more "advanced" topics around how to iterate on your components/component data and how to publish your content to a wider audience leveraging outside networks by turning manipulating component data into different formats beyond JSON & HTML. -* [Data Versioning (Upgrades)](data_versioning) \ No newline at end of file +* [Data Versioning (Upgrades)](upgrade.md) \ No newline at end of file diff --git a/docs/advanced/README.md b/docs/advanced/README.md deleted file mode 100644 index 28b01d75..00000000 --- a/docs/advanced/README.md +++ /dev/null @@ -1,8 +0,0 @@ -# Advanced - -This section covers more "advanced" topics around how to iterate on your components/component data and how to publish your content to a wider audience leveraging outside networks by turning manipulating component data into different formats beyond JSON & HTML. - -{% page-ref page="upgrade.md" %} - - - diff --git a/docs/advanced/renderer-models.md b/docs/advanced/renderer-models.md deleted file mode 100644 index e1b98356..00000000 --- a/docs/advanced/renderer-models.md +++ /dev/null @@ -1,18 +0,0 @@ -# Renderer Models - -## Problem - -A common issue that anyone publishing content to the web faces is how to get their data into different formats than how the data is already stored in their system. For example, Clay stores JSON data but needs to be able to serve RSS feeds, publish content in a format compatible with Apple News or Google Newstand, all while not duplicating and mutating the data for rendering HTML. - -## Solution - -It's important to remember that Clay is a "webpage first" platform. The supported edit interface \([Kiln](https://claycms.gitbook.io/kiln)\) allows Clay data component editing through an HTML page, so generally components are always built with HTML rendering in mind. For that reason, the `model.js` file for a component can modify component/layout data for either a JSON or HTML formats. But what if you request an component with a `.xml` extension? [You'll need a renderer](https://claycms.gitbook.io/amphora/~/drafts/-LJUeZikGqO4SPbtu-9G/primary/basics/renderers) to handle the request, but what if that renderer expects a different input than the component's data? - -That's where a renderer specific model comes in. It's exactly like a regular `model.js` file except that it's run _after_ the default regular `model.js` file and gives you a chance to modify data for a component to meet your renderers needs. The format for a renderer model is a filename in the following format:`.model.js` - -If you're request is to `domain.com/_components/foo/instances/bar.rss` , then your model file will need to be named `rss.model.js`. - -### Renderer Model Caveat - -This does not work for requests to `.html` extensions, i.e. there is no support for `html.model.js` files. Your regular `model.js` file should do everything necessary to support displaying the component in HTML pages. - diff --git a/docs/advanced/storage.md b/docs/advanced/storage.md deleted file mode 100644 index b1273edf..00000000 --- a/docs/advanced/storage.md +++ /dev/null @@ -1,152 +0,0 @@ -# Storage - -The Storage API for Amphora is meant to provide a bridge between Amphora's composition layer and how data for sites in Clay is persisted. At its core, Amphora maintains six top-level data structures (Components, Layouts, Pages, Users, Uris, Lists) and it's the responsibility of the storage module to store and compose the data. - -Currently it is possible to write any storage midule that best fits the needs of your Clay instance, but the platform officially supports a Postgres storage module that [can be found here](https://github.com/clay/amphora-storage-postgres). - -For more information in writing your own storage module you can refer to this module as an example. - ---- - -## Setup - -The function in which the storage module should connect to a database as well as perform any other instantiation operations, such as setting up required tables/collections. - -**Returns:** `Promise` - ---- - -## Put - -This function is a simple write to the DB for any of the Clay data structures. It should be able to handle writing one individual component/layout/page/list/uri/user. The return value should - -**Arguments:** `key` (String), `value` (Object) - -**Returns:** `Promise` - ---- - -## Get - -This function should return one individual instance of a any of the data types. - -**Arguments:** `key` (String) - -**Returns:** `Promise` - ---- - -## Del - -This function should delete one individual instance of any of the data types. The value of the item that was just deleted should be returned. - -**Arguments:** `key` (String) - -**Returns:** `Promise` - ---- - -## Batch - -A function which accepts an array of objects (operations), with each object representing one "save" action for any of the supported data structures. An operation is an object with the following structure: - -- `key` (String): the id of the individual component/layout/page/uri/list/user instance -- `value` (Object): the value to be saved for the key - -```javascript -// Example operations array -[{ - key: 'domain.com/_components/foo/instances/bar', - value: { - foobar: 'baz' - } -}, { - key: 'domain.com/_pages/foobarbaz', - value: { - layout: 'domain.com/_layouts/layout/instances/default', - main: [ - 'domain.com/_components/foo/instances/bar' - ] - } -}] -``` - -**Arguments:** `ops` (Array) - -**Returns:** `Promise` - ---- - -## Get Meta - -Retrieves the metadata for a page/layout. The function will always be called with the raw page/layout uri, not a uri ending in `/meta`. - -For example, Amphora will respond to a request for `domain.com/_pages/foo/meta` by making the following invoking the `getMeta` function of the storage module with a key of `domain.com/_pages/foo` and then returning the data to client. If no data is returned, Amphora will return an empty object. - -**Arguments:** `key` (String) - -**Returns:** `Promise` - ---- - -## Put Meta - -Saves the metadata for a page/layout. The function will always be called with the raw page/layout uri, not a uri ending in `/meta`. - -**Arguments:** `key` (String), `value` (Object) - -**Returns:** `Promise` - ---- - -## Patch Meta - -Updates properties on the metadata object with the values passed into the request. This method should _never_ update the entire metadata object with what's passed to the function or metadata will be destroyed when users edit data. - -If the storage solution does not support partial updates to the data then the function will need to request the full object from the database, merge the old data with the new data and then save the merged object. - -**Arguments:** `key` (String), `value` (Object) - -**Returns:** `Promise` - ---- - -## Create Read Stream - -Amphora responds to certain requests with a Stream of data, such as a request to `domain.com/_components/foo/instances`. In this case, Amphora will read all the instances of the `foo` component from the database and send back an array of component uris. To handle this in the most memory efficient way, Amphora processes the data from the DB as a Stream, and the `createReadStream` function should return a Read Stream for Amphora to act on. - -The function will receive an object of options with three properties: - -- `prefix` (String): the string which should prefix all of the keys that Amphora needs to display data for -- `keys` (Boolean): if `true`, the stream should return the uri of all data matcing the prefix -- `values` (Boolean): if `true`, the stream should return the values of all uris matcing the prefix - -Using the example from earlier, if a request comes in for `domain.com/_components/foo/instances`, Amphora will pass an `options` object to the `createReadStream` function like so: - -```javascript -// Example `options` object for the createReadStream function -{ - prefix: 'domain.com/_components/foo/instances', - keys: true, - values: false -} -``` - -Amphora would expect a Read Stream (in object mode) where each item in the stream is an object with the following signature: - -- `key` (String)[Optional]: the uri of the component/layout/page/uri/user/list -- `value` (Object)[Optional]: the object/string value of the uri - -Amphora will then take this data and make sure it's a properly formatted response to the client that initiated the request. - ---- - -## Raw - -The `raw` function is the most ambiguous function of the API, but is the crux of plugins. To ensure that plugins can add in their own data to the database that your Clay instance is using, the db client is passed to each plugin included in your instance. - -This puts a lot of responsibility on plugins to manage their own data properly, but allows developers to write their own plugins to accomplish anything with Clay. - -This function should simply be a passthrough to the client that connects to the data store being used and should return a Promise for any executed action. - -**Returns:** `Promise` \ No newline at end of file diff --git a/docs/advanced/upgrade.md b/docs/advanced/upgrade.md deleted file mode 100644 index 0d1814e9..00000000 --- a/docs/advanced/upgrade.md +++ /dev/null @@ -1,58 +0,0 @@ -# Data Versioning \(Upgrades\) - -Data versioning is a feature of Amphora that aims to address the problem of iterating on component data. As properties are added or removed from a component's data it's easy to reach a point where data that is already in the database does not meet the requirements/expectations of a template or `model.js`. Data versioning allows you to track which "version" of data your component is on and then bring old data up to that current version, increasing the rate at which new features can be developed around a component. - -## "Upgrading" Component Data - -Components follow a very defined path when they're requested. First the data is retrieved from the database and then it's passed to a `model.js` `render` function for the component \(if one exists\). After that the component data proceeds to the final output destination, whether that's to be templated into HTML or to be consumed as JSON. Upgrades take place immediately after a component's data is retrieved from the database, making the modified data accessible the `model.js`. - -![Upgrade data flow](../.gitbook/assets/upgrade_flow.png) - -## How To Upgrade - -Upgrading is easy! You only need two things: - -* A `_version` property set to a number in your component's `schema.yaml` -* An `upgrade.js` file in your component's directory - -### `\_version` Property - -The `_version` property is how upgrades are tracked by Amphora. Whenever a component's data is requested the `_version` property in your component's data is checked against the `_version` property in your component's `schema` file. If the two are not the same value, the component's data will be run through whatever upgrades are specified in your `upgrade.js` file. Things to note about this property: - -* You should never modify the `_version` property in your component, Amphora will manage this for you -* The property format `.` \(i.e. `1.6`\). This allows you to specify "breaking" changes in your component data \(usually removing a property\) - -### Upgrade.js file - -If the schema specifies _what_ version a component's data should be at, an `upgrade.js` file describes _how_ to get to that version. An `upgrade.js` should export a function for each version number that of schema that you have. For example, if you're writing your first upgrade for a component and want to write an upgrade to `1.0`, your `upgrade.js` would have the following: - -```javascript -module.exports['1.0'] = function () { - //...upgrade goes here -}; -``` - -For every version that you increment, just add a corresponding function and they'll be run! But what about the structure of the function? The function signature for an `upgrade.js` file is the exact same as a `model.js` file. The functions will receive the same arguments and should return a Javascript Object or a `Promise` that resolves an Object. - -```javascript -module.exports['1.0'] = function (uri, data, locals) { - // Modify your `data` here and return a Promise or JS Object -}; -``` - -## FAQ - -### So all the upgrades for a component run every time a component is requested? - -An upgrade is only run **once** per component instance. The `_version` property is used to track the version of the data and then upgrades are reduced through, make sure that a upgrades are run in ascending order. - -For example, if your component data is on version `1.0` and your schema version is at `1.6`, Amphora will run your data through each upgrade \(from `1.1` to `1.6`\) and return the data expected for `1.6`. In this way, even the oldest data in your system is up-to-date with `model.js` and template expectations. - -### Why not just use an external script or render function? - -Transforming data in a `model.js` `render` function will lead to bloat of the file which will require more development time as devs must keep all of the possible permutations of the data in mind when making changes. - -Using an external script will require careful coordination when releasing new features and updating data. - -Data versioning allows you iterate and release without fear that your data needs to undergo its own migration. - diff --git a/docs/basics/README.md b/docs/basics/README.md deleted file mode 100644 index 2f3dac35..00000000 --- a/docs/basics/README.md +++ /dev/null @@ -1,2 +0,0 @@ -# Basics - diff --git a/docs/basics/plugins.md b/docs/basics/plugins.md deleted file mode 100644 index 01b9dfc4..00000000 --- a/docs/basics/plugins.md +++ /dev/null @@ -1,42 +0,0 @@ -# Plugins - -Plugins allow for you to extend the functionality of your site by allowing you to attach routes to each site's router in your instance. While this may not seem any different than [defining routes for your site](/docs/basics/routes.md), the basic site router will assign routes that only respond to `GET` requests and will run through Amphora's composition/rendering functionality. Plugins allow you to assign routes that respond to any [Express supported request method](https://expressjs.com/en/4x/api.html#app.METHOD) with your own custom handlers. - -## Anatomy of a Plugin - -A plugin should be a function and will receive the following arguments: - -- `router`: the router for the site. Attach listeners and handlers as you would to any Express router. -- `db`: an instance of Amphora's internal database connector. -- `bus`: a passthrough of Amphora's internal event bus publish method so that a plugin can publish to the event bus on its own. -- `sites`: the internal `sites` service, used for discovering which site in your instance a uri belongs to. - -An example plugin might look like the following: - -```javascript -module.exports = (router, db, bus, sites) => { - // Attach a route that responds to PUT requests - router.put('/_coolroute', (req, res) => { - return db.put(req.uri, req.body) - .then(() => { - // Pub to the event bus that the route was called - bus('coolRouteCalled', { body: req.body }); - // Respond to the request - res.json({ status: 200 }) - }); - }); - - // Note: we're not explicity returning anything, but if we were - // performing some async action we could return a Promise -} -``` - -You aren't required to explicitly `return` any value from your plugin, but you can return a `Promise` if needed. - -## Lifecycle of Plugin - -A plugin is called... - -- once for every site in your Clay instance -- _after_ the storage module is instantiated -- _before_ bootstrapping happens diff --git a/docs/basics/publishing.md b/docs/basics/publishing.md deleted file mode 100644 index 2d24df8d..00000000 --- a/docs/basics/publishing.md +++ /dev/null @@ -1,80 +0,0 @@ -# Publishing - -When setting up a site in your Clay instance you add a controller \(`index.js` file\) to define the rules around your sites. One of the rules you can define is _how to determine what url to publish a page to_. This can be done in a number of ways, whether it's just using the current date or analyzing the data in the content of the page. The implementation is your decision \(as long as the url matches a defined Express route\). - -## Setting Publish Rules - -To add publishing rules simply export an Array of functions under the `resolvePublishUrl` property in your site's controller. - -```javascript -module.exports.resolvePublishUrl = [...]; -``` - -The functions will receive the same arguments as a `model.js`/`upgrade.js`: - -* `uri`: corresponds to the uri for the page being published -* `data`: the data for the page. Is not fully resolved page data, simply any references in page areas -* `locals`: information around the request, including the site it's being published to - -Each function in the Array should return a Promise which only resolves a single string value, the url to be published to. The functions will be executed in order, but the _first one that resolves a value_ will be accepted and the rest will be ignored. This is "reject quickly/resolve slowly" pattern, meaning each of the functions should reject quickly if the data doesn't match a format they want. - -```javascript -module.exports.resolvePublishUrl = [ - // regular dated articles - function (uri, data, locals) { - // ...do some logic with the data - return Promise.resolve(`${http://coolsite.com/2017/01/cool-content.html}`); - } -]; -``` - -The value that the functions return should be the full url \(protocol, host, path, etc\). This value will be used when creating `uris` to map vanity urls to proper instances of `pages`. - -## Dynamic Pages & Publishing - -[Dynamic pages](routes.md#dynamic-pages) allow one page template to render data in a variety of ways by letting you build pages that take an input a url and use that to render data. Because a dynamic page's url can be anything the usual 1-to-1 relationship of uri to page instance cannot work. For that reason, publishing a dynamic page is slightly different than other pages. All you have to do is make sure that your page has the `_dynamic` property set to `true` and Amphora will handle the rest. For example: - -```javascript -{ - "_dynamic": true, - "layout": "domain.com/_components/layout/instances/example", - "main": [ - ... - ] -} -``` - -With this property set Amphora will publish the page without generating a uri. As long as your router properly defines the page to use for the route, the page will render its dynamic content. - -## Modifying Page Data - -Sometimes you'll want to modify the `@published` instance of page data when publishing. Rather than increasing the complexity of `resolvePublishUrl` to handle this task, a separate API is provided purely for this process. - -```javascript -module.exports.modifyPublishedData = [...]; -``` - -Exporting an Array in `modifyPublishedData` will signify to Amphora that page data should be modified before being saved. A common use case for this is adding a "last modified" property to the page data for site maps or other uses. Using this API, your controller might include the following: - -```javascript -/** - * Adds lastModified to page object - * @param {object} pageData - * @returns {object} - */ -function addLastModified(pageData) { - pageData.lastModified = Date.now(); - return pageData; -} - -module.exports.modifyPublishedData = [ - addLastModified -]; -``` - -Each function in the `modifyPublishedData` will only recieve the page data, not the `locals` or `uri` of the page. The purpose of this is to discourage complex/time consuming modifications of the data. While functions in this Array can be both synchronous or asynchronous, it's advised to keep these functions simple. - -## `publishUrl` - -The question often arises of how to determine the vanity url of a page inside of a component's `model.js`. When a page is published, a `@published` instance of the page and every component instance is created. During this process, the `publishUrl` property is added to the `locals` object sent to each component. This essentially allows you to know when a `save` is being run on publish or not and is handy if the vanity url is needed in your component. - diff --git a/docs/basics/renderers/README.md b/docs/basics/renderers/README.md deleted file mode 100644 index adaead90..00000000 --- a/docs/basics/renderers/README.md +++ /dev/null @@ -1,56 +0,0 @@ -# Renderers - -{% hint style="info" %} -This page discusses renderer purpose and affordances, but once a renderer is written it enables you to write renderer specific `model.js` files. If you already have a functional renderer and are looking for information on renderer models, [see this page](https://claycms.gitbook.io/amphora/advanced/renderer-models). -{% endhint %} - -The main concern of Amphora is JSON, but to serve content on the web we need to support HTML, XML and any other format that might arise in the future. - -Rather than hardcoding support for different formats or supporting different rendering engines, Amphora provides an API that allows you to simply plug in any type of renderer. At instantiation time, Amphora can be passed a renderer object: - -```javascript -amphora({ - ... // other instantiation properties - renderers: { - ... - } -}) -``` - -## The Renderers Object - -The object that is passed in as the `renderers` value should be key value pairs where the key represents the extension of the request \(`.html`, `.rss`, etc.\) and the value is the renderer that should handle the formatting of the JSON to the expected output. Let's use [Amphora HTML](https://github.com/clay/amphora-html) as an example: - -```javascript -const amphora = require('amphora'), - amphoraHtml = require('amphora-html'); - -return amphora({ - ... - renderers: { - html: amphoraHtml - } -}) -``` - -Whenever any request comes into Amphora with a `.html` extension, the JSON data that Amphora composes will be passed to Amphora HTML for rendering. For information on how to write your own renders you can read [this doc on writing a custom renderer](https://github.com/clay/amphora/tree/3a300d4ec7af113afd102b4506e7566eb617c9c8/docs/topics/custom-renderers.html). - -## `default` Renderer - -The renderers object also accepts a `default` property which is used to define the renderer for a route whose request extension is not defined. For example, say you were making a request to `foobar.com`. The request does not explicitly declare the content type of the asset that lives at this url so Amphora would not know what format the user expects. By defining the `default` property in the renderers object you can explicitly tell Amphora which renderer to pass by specifying an extension. - -```javascript -const amphora = require('amphora'), - amphoraHtml = require('amphora-html'); - -return amphora({ - ... - renderers: { - html: amphoraHtml, - default: 'html' - } -}) -``` - - - diff --git a/docs/basics/renderers/custom-renderers.md b/docs/basics/renderers/custom-renderers.md deleted file mode 100644 index e329a96c..00000000 --- a/docs/basics/renderers/custom-renderers.md +++ /dev/null @@ -1,27 +0,0 @@ -# Building Custom Renderers - -{% hint style="info" %} -The docs address the renderer API as of Amphora v6.x. -{% endhint %} - -A custom renderer can do anything your needs might require when it comes to transforming JSON data from Amphora. All that is required is that your renderer export a `render` function. This function will receive a the arguments described below: - -* `data` \(Object\): The composed data for the page or component. This data will have passed through complete data composition, including `model.js` files and renderer specific models. This is the data you'll send to your templating language or formatting logic. -* `meta` \(Object\): This object contains three crucial properties: - * `locals` \(Object\): The [Express locals object](https://expressjs.com/en/api.html#res.locals) that has also been annotated by Amphora. This is the same `locals` object passed to component's `model.js` files during composition. - * `_ref` \(String\): This is the uri that was requested to be rendered. If you're rendering a `page` or an Express route, this will be the page uri. If you're rendering a component directly, this will be the component's uri. - * `_layoutRef` \(String\): This is only provided when rendering a `page` and it's value corresponds to the `layout` uri on the page. This is needed for finding the root template when rendering with different templating languages, such as Handlebars. -* `res` \(Object\): Simply the [Express Response](https://expressjs.com/en/4x/api.html#res) object. This means **it is the responsibility of the renderer to terminate the response**. - -An example renderer: - -```javascript -module.exports.render = function (state, res) { - var htmlResponse = ...; // Use state object to construct some HTML response.. - - res.html(htmlResponse); -}; -``` - -Having access to the Express Response object \(`res`\) means a renderer can attach custom headers, choose the response type and any other task you might need. - diff --git a/docs/basics/routes.md b/docs/basics/routes.md deleted file mode 100644 index 504c45af..00000000 --- a/docs/basics/routes.md +++ /dev/null @@ -1,50 +0,0 @@ -# Routing - -{% hint style="info" %} -These docs describe an API for routes that is current as of `v6.2.0`. Documentation for routing prior to this version will not be included because it will be deprecated in the future. -{% endhint %} - -## Basic Routing - -The `routes` API allows you to define routes to for your site within the site's controller \(`index.js`\) file. By exporting an array of route objects, Amphora will attach each route to the Express Router under a `get` handler. Previous versions of Amphora exposed the whole router to a developer to attach routes, but this has been updated in favor of greater stability/feature set in Amphora. - -To assign routes for your site, export an Array like the one below at the `routes` property of your site's controller. Routing patterns should be [Express compatible](https://expressjs.com/en/guide/routing.html#route-paths). - -```javascript -module.exports.routes = [ - { path: '/'}, - { path: '/:name'}, - { path: '/:year/:month/:slug' } -]; -``` - -## Redirects - -The router can handle redirects if you choose to handle these in Clay. Simply add the `redirect` property to your path object with the destination being the path you'd like to redirect users to. Make sure the destination path exists before adding in a redirect. - -```javascript -// Redirects to the trailing slash of version of the `/blog/` path -module.exports.routes = [ - { path: '/'}, - { path: '/blog/'}, - { path: '/blog', redirect: '/blog/'} -]; -``` - -## Dynamic Pages - -One of the problems the router aims to solve is `dynamic pages`. In Clay there is a 1-1 relationship between a `_uri` and a a `_page`, which makes it extremely hard to build a dynamic system which doesn't require a single page for every public url. - -An example of this would be building an archive page of blog posts that have a certain characteristic or tag. Ideally you'd have one page who would parse the url, find the value the user expects and then render a page with that value filled in all the places you would expect. - -To do this in Clay you can use a `dynamic page`, which allows you to define ONE page to resolve all requests at a given route. For example: - -```javascript -// All requests to `/archive/:tag` will be directed to `/_pages/someUniquePageId` -module.exports.routes = [ - { path: '/'}, - { path: '/archive/:tag', dynamicPage: 'someUniquePageId'} -]; -``` - -By adding this path object into your `routes` object you'll be able to create one page to handle all the requests to the `/archive/*` route. **Make sure your** [**dynamic page is published**](publishing.md#dynamic-pages--publishing) **or else this won't work!** diff --git a/docs/bootstrapping.md b/docs/bootstrap.md similarity index 100% rename from docs/bootstrapping.md rename to docs/bootstrap.md diff --git a/docs/building-renderers.md b/docs/custom-renderers.md similarity index 98% rename from docs/building-renderers.md rename to docs/custom-renderers.md index 01a83858..1a4a57ea 100644 --- a/docs/building-renderers.md +++ b/docs/custom-renderers.md @@ -1,5 +1,5 @@ --- -id: building-renderers +id: custom-renderers title: Building Custom Renderers sidebar_label: Building Custom Renderers --- diff --git a/docs/basics/event-bus.md b/docs/event-bus.md similarity index 97% rename from docs/basics/event-bus.md rename to docs/event-bus.md index 275e79f8..789ba1f1 100644 --- a/docs/basics/event-bus.md +++ b/docs/event-bus.md @@ -1,4 +1,8 @@ -# Event Bus +--- +id: event-bus +title: Event Bus +sidebar_label: Event Bus +--- As of Amphora version `6.6.0` the option of using [Redis as an event bus](https://redis.io/topics/pubsub) has been introduced. This event bus is intended to make it easier to a destructure a Clay instance and supporting platform packages \(i.e. Amphora Search\). By default the Bus module is not instantiated. Only by setting the [Redis Bus Host env var](event-bus.md#redis-bus-host) will the Bus module be active. @@ -56,4 +60,4 @@ for (let i = 0; i < CLAY_TOPICS.length; i++) { SUBSCRIBER.on('message', (channel, payload) => { console.log(`Channel: ${channel}\n\n\n${payload}`); }); -``` +``` \ No newline at end of file diff --git a/docs/event_bus.md b/docs/event_bus.md deleted file mode 100644 index 913c540a..00000000 --- a/docs/event_bus.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -id: event-bus -title: Event Bus -sidebar_label: Event Bus ---- - -As of Amphora version `6.6.0` the option of using [Redis as an event bus](https://redis.io/topics/pubsub) has been introduced. This event bus is intended to make it easier to a destructure a Clay instance and supporting platform packages \(i.e. Amphora Search\). By default the Bus module is not instantiated. Only by setting the [Redis Bus Host env var](event-bus#redis-bus-host) will the Bus module be active. - -The Event Bus is also intended to replace the plugin system in the next major version of Amphora \(v7\). On top of replacing the plugin system, the event bus will see some small changes to the payload of certain events as the plugin system is rearchitected. The end goal is to expose specific hooks in the Amphora lifecycle to the Bus as quickly as possible. - -## Bus Topics - -The following topics are published to the bus by Amphora: - -* `clay:publishLayout` -* `clay:publishPage` -* `clay:createPage` -* `clay:unschedulePage` -* `clay:schedulePage` -* `clay:unpublishPage` -* `clay:save` -* `clay:delete` - -## Configuring the Bus - -The Bus module has two configurations options which are both controlled by environment variables. - -### Redis Bus Host - -As mentioned, the Bus module is turned off by default. Only by setting the `CLAY_BUS_HOST` env var to a valid Redis url \(`redis://:`\) will the module be instantiated and events will be published to the instance. - -### Namespace - -By default, all topics published to the Bus are namespaced using `clay`, i.e. `clay:`. This namespace can be configured by the env var `CLAY_BUS_NAMESPACE`. For example, setting `CLAY_BUS_NAMESPACE` to a value of `mysite` will publish all events as `mysite:`. - -## Subscribing To The Bus - -Provided you have setup Amphora to pub to a Redis instance, the following code will subscribe to all events from Clay using the [`redis`](https://www.npmjs.com/package/redis) NPM module. - -```javascript -'use strict'; - -var redis = require('redis'), - SUBSCRIBER = redis.createClient(process.env.CLAY_BUS_HOST), - CLAY_TOPICS = [ - 'publishLayout', - 'publishPage', - 'unpublishPage', - 'createPage', - 'schedulePage', - 'unschedulePage', - 'save', - 'delete' - ]; - -for (let i = 0; i < CLAY_TOPICS.length; i++) { - SUBSCRIBER.subscribe(`clay:${CLAY_TOPICS[i]}`); -} - -SUBSCRIBER.on('message', (channel, payload) => { - console.log(`Channel: ${channel}\n\n\n${payload}`); -}); -``` \ No newline at end of file diff --git a/docs/glossary-docs.md b/docs/glossary-docs.md deleted file mode 100644 index 5bf0c99e..00000000 --- a/docs/glossary-docs.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -id: glossary-docs -title: Glossary -sidebar_label: Glossary ---- -## bootstrap - -An instantiation argument that defaults to `true`. If set to `false`, the internal [bootstrap](bootstrap) process will be skipped. - -## locals.publishUrl - -Property that only is available to components during the save of an `@published` instance of a component. This value is determined by whatever url is determined during [publishing](publish#setting-publish-rules). - -## _version - -A data property managed by Amphora when using the [Data Versioning](data_versioning) feature. This property should not be overwritten to by any `model.js` or external source. If it is, data upgrades will be re-run. Please see the _Data Versioning_ page for more information. diff --git a/docs/glossary.md b/docs/glossary.md index 575234ec..f49904e7 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -1,14 +1,16 @@ -# Glossary +--- +id: glossary +title: Glossary +sidebar_label: Glossary +--- +## bootstrap -## `bootstrap` +An instantiation argument that defaults to `true`. If set to `false`, the internal [bootstrap](bootstrap.md) process will be skipped. -An instantiation argument that defaults to `true`. If set to `false`, internal [bootstrap](startup/bootstrap.md) process will be skipped. +## locals.publishUrl -## `locals.publishUrl` +Property that only is available to components during the save of an `@published` instance of a component. This value is determined by whatever url is determined during [publishing](publishing.md#setting-publish-rules). -A propery only availble to components during the save of an `@published` instance of a component. This value is determined by whatever url is determined during [publishing](basics/publishing.md#setting-publish-rules). - -## `_version` - -A data property managed by Amphora when using the [Data Versioning](advanced/upgrade.md) feature. This property should not be overwritten to by any `model.js` or external source. If it is, data upgrades will be re-run. Please see the _Data Versioning_ page for more information. +## _version +A data property managed by Amphora when using the [Data Versioning](upgrade.md) feature. This property should not be overwritten to by any `model.js` or external source. If it is, data upgrades will be re-run. Please see the _Data Versioning_ page for more information. diff --git a/docs/images/upgrade_flow.png b/docs/images/upgrade_flow.png deleted file mode 100644 index 310b1f5e..00000000 Binary files a/docs/images/upgrade_flow.png and /dev/null differ diff --git a/docs/install.md b/docs/instantiation.md similarity index 84% rename from docs/install.md rename to docs/instantiation.md index 6f6421b2..6e57482a 100644 --- a/docs/install.md +++ b/docs/instantiation.md @@ -1,5 +1,5 @@ --- -id: install +id: instantiation title: Instantiation Arguments sidebar_label: Instantiation Arguments --- @@ -26,7 +26,7 @@ amphora({ Here we create a new Express app, pass it into Amphora and then Amphora will return an Express instance that has been modified with Clay core routes for each site you have created. Once that Express instance is returned \(`router` in this example\), we call the `listen` function, [just like an Express app would](http://expressjs.com/en/api.html#app.listen). -Assuming you have configured your sites properly and have some components, you'll now be able to access any Clay core routes and any data included in [internal bootstrap files](bootstrap) for components and sites will have been added. +Assuming you have configured your sites properly and have some components, you'll now be able to access any Clay core routes and any data included in [internal bootstrap files](bootstrap.md) for components and sites will have been added. ## Instantiation Arguments @@ -35,7 +35,7 @@ At instantiation time Amphora accepts a config object which contains properties * `app`: an Express instance. If one is not passed in, Amphora will create one during startup. The advantage of passing an instance into Amphora is the ability to add any middleware or other configuration necessary for your specific setup. * `providers`: an Array of strings which correspond to the supported authentication services in Amphora: `apikey`, `ldap`, `google`, `slack`, and `twitter`. * `sessionStore`: used for session management with user sessions when a provider is configured. For more information see the [Authentication](https://github.com/clay/amphora/tree/3a300d4ec7af113afd102b4506e7566eb617c9c8/docs/lifecycle/startup/authentication.md) page. -* `renderers`: an Object that references modules that can be used to transform component data into different formats. For example, [Amphora HTML](https://github.com/clay/amphora-html) is a module that renders component data to HTML using Handlebars templates. Renderers abide by an API that Amphora sets forth. The `renderers` Object should contain properties whose names correspond to request extensions and whose properties are the handlers for those extensions. A `default` property is used to specify the renderer to be used when no extension is specified in a request. For more information, see the [Renderers](building-renderers) documentation. -* `plugins`: an Array of Objects that have handlers for different plugin hooks that Amphora exposes. Different hooks are exposed for the startup, request and publish life cycles. For more information see the [Plugins](https://github.com/clay/amphora/tree/3a300d4ec7af113afd102b4506e7566eb617c9c8/docs/lifecycle/startup/plugins.md) page. -* `env`: an accommodation for renderers to expose environment variables used in `model.js` files on the client-side for [Kiln](https://github.com/clay/clay-kiln). These are only rendered in edit mode for a page. For a more thorough understanding of when/how these values are gathered and used, please see the [Component Models](renderer-models) documentation. -* `bootstrap`: a Boolean value which defaults to `true`. When set to `false` the internal [bootstrapping process](bootstrap#skipping-bootstrapping) will be skipped entirely. **It's advised not to set the value to** `false` **for production instances.** +* `renderers`: an Object that references modules that can be used to transform component data into different formats. For example, [Amphora HTML](https://github.com/clay/amphora-html) is a module that renders component data to HTML using Handlebars templates. Renderers abide by an API that Amphora sets forth. The `renderers` Object should contain properties whose names correspond to request extensions and whose properties are the handlers for those extensions. A `default` property is used to specify the renderer to be used when no extension is specified in a request. For more information, see the [Renderers](custom-renderers.md) documentation. +* `plugins`: an Array of Objects that have handlers for different plugin hooks that Amphora exposes. Different hooks are exposed for the startup, request and publish life cycles. For more information see the [Plugins](plugins.md) page. +* `env`: an accommodation for renderers to expose environment variables used in `model.js` files on the client-side for [Kiln](https://github.com/clay/clay-kiln). These are only rendered in edit mode for a page. For a more thorough understanding of when/how these values are gathered and used, please see the [Component Models](renderer-models.md) documentation. +* `bootstrap`: a Boolean value which defaults to `true`. When set to `false` the internal [bootstrapping process](bootstrap.md#skipping-bootstrapping) will be skipped entirely. **It's advised not to set the value to** `false` **for production instances.** diff --git a/docs/introduction.md b/docs/introduction.md index 36d7d7a1..def6612b 100644 --- a/docs/introduction.md +++ b/docs/introduction.md @@ -1,5 +1,5 @@ --- -id: intro +id: introduction title: Introduction sidebar_label: Introduction --- @@ -116,6 +116,6 @@ Fork the project and submit a PR on a branch that is not named `master`. We use ## Advanced Topics * [New Concepts For Developers and Designers](https://github.com/nymag/amphora/wiki#for-developers-and-designers) -* [Bootstrapping Data](bootstrap) -* [Routing](routes) -* [Plugins](publish) +* [Bootstrapping Data](bootstrap.md) +* [Routing](routing.md) +* [Plugins](plugins.md) diff --git a/docs/lifecycle/README.md b/docs/lifecycle/README.md deleted file mode 100644 index 10d81d90..00000000 --- a/docs/lifecycle/README.md +++ /dev/null @@ -1,4 +0,0 @@ -# Life Cycle - -* [Startup Cycle](./startup.md) -* Request Cycle (Coming Soon!) diff --git a/docs/plugin.md b/docs/plugins.md similarity index 99% rename from docs/plugin.md rename to docs/plugins.md index 51c6b5ce..a55f0026 100644 --- a/docs/plugin.md +++ b/docs/plugins.md @@ -1,5 +1,5 @@ --- -id: plugin +id: plugins title: Plugins sidebar_label: Plugins --- diff --git a/docs/publish.md b/docs/publishing.md similarity index 99% rename from docs/publish.md rename to docs/publishing.md index e7e742b2..878a61e1 100644 --- a/docs/publish.md +++ b/docs/publishing.md @@ -1,5 +1,5 @@ --- -id: publish +id: publishing title: Publishing sidebar_label: Publishing --- diff --git a/docs/renderer_models.md b/docs/renderer-models.md similarity index 67% rename from docs/renderer_models.md rename to docs/renderer-models.md index 93084474..1d6970fa 100644 --- a/docs/renderer_models.md +++ b/docs/renderer-models.md @@ -10,7 +10,7 @@ A common issue that anyone publishing content to the web faces is how to get the ## Solution -It's important to remember that Clay is a "webpage first" platform. The supported edit interface \([Kiln](https://claycms.gitbook.io/kiln)\) allows Clay data component editing through an HTML page, so generally components are always built with HTML rendering in mind. For that reason, the `model.js` file for a component can modify component/layout data for either a JSON or HTML formats. But what if you request a component with a `.xml` extension? [You'll need a renderer](https://claycms.gitbook.io/amphora/~/drafts/-LJUeZikGqO4SPbtu-9G/primary/basics/renderers) to handle the request, but what if that renderer expects a different input than the component's data? +It's important to remember that Clay is a "webpage first" platform. The supported edit interface \([Kiln](https://docs.clayplatform.com/clay-kiln/docs/intro)\) allows Clay data component editing through an HTML page, so generally components are always built with HTML rendering in mind. For that reason, the `model.js` file for a component can modify component/layout data for either a JSON or HTML formats. But what if you request a component with a `.xml` extension? You'll need a renderer to handle the request, but what if that renderer expects a different input than the component's data? That's where a renderer specific model comes in. It's exactly like a regular `model.js` file except that it's run _after_ the default regular `model.js` file and gives you a chance to modify data for a component to meet your renderers needs. The format for a renderer model is a filename in the following format:`.model.js` diff --git a/docs/routing.md b/docs/routing.md index 72df94dd..50b646da 100644 --- a/docs/routing.md +++ b/docs/routing.md @@ -48,4 +48,4 @@ module.exports.routes = [ ]; ``` -By adding this path object into your `routes` object you'll be able to create one page to handle all the requests to the `/archive/*` route. **Make sure your** [**dynamic page is published**](publish#dynamic-pages-publishing) **or else this won't work!** +By adding this path object into your `routes` object you'll be able to create one page to handle all the requests to the `/archive/*` route. **Make sure your** [**dynamic page is published**](publishing.md#dynamic-pages-publishing) **or else this won't work!** \ No newline at end of file diff --git a/docs/startup/README.md b/docs/startup/README.md deleted file mode 100644 index 8c487044..00000000 --- a/docs/startup/README.md +++ /dev/null @@ -1,17 +0,0 @@ -# On Startup - -The startup life cycle is meant to do a few main things: - -1. Setup any Amphora Plugins -2. Register any sites and setup core routes -3. Seed the database with any default data - -All of these processes are coordinated in [`setup.js`](https://github.com/clay/amphora/blob/master/lib/setup.js). - -## Actions - -* Registering Plugins \(Coming Soon!\) -* Add Site\(s\) \(Coming Soon!\) -* Register Renderers/Environment Variables \(Coming Soon!\) -* [Bootstrap](bootstrap.md) - diff --git a/docs/startup/bootstrap.md b/docs/startup/bootstrap.md deleted file mode 100644 index e45e467c..00000000 --- a/docs/startup/bootstrap.md +++ /dev/null @@ -1,40 +0,0 @@ -# Bootstrapping - -Bootstrapping is the process by which Amphora will look for specific data in your implementation to add to the database. This process runs _EVERYTIME_ the server restarts. - -Whenever the process first starts up, Amphora will look into each component directory and each site directory for a `bootstrap.(yml|yaml)` file. This YAML file will be converted into JSON and then the values will be written to the database for each site. - -## Why is this necessary? - -Bootstrapping is a great time for taking care of two actions: - -* Adding default data to a component -* Adding component instances to the database _that will never change_ from user input - -## Skipping Bootstrapping - -As of [Amphora 4.2.0](https://github.com/clay/amphora/releases/tag/v4.2.0) the bootstrapping process can be skipped. This is useful when developing server-side services for your implementation as it allows for more rapid startups on larger Clay instances, but this can be dangerous. - -As mentioned above, bootstrapping is great for seeding the default data for a component or site. If bootstrapping is turned off and you add a new component to your instance, the default data will not be added to your local database. For this reason it's encouraged to only use this feature when you know you won't need to the bootstrap process to run **and never in production environments**. - -To turn off bootstrapping, simply pass the `boostrap` property into Amphora at instantiation time with a `false` value: - -```javascript -amphora({ - // ...some other args - bootstrap: false -}) -``` - -### Default Data - -Since components and the data they hold will change and grow \(or shrink\) over time, it's necessary to update the default data that a component is created with anytime the server restarts. By including a bootstrap file in each component directory, you'll be able to make sure that changes to all aspects of the component can be changed within a single directory and that every time the server restarts you'll be working with the default data you expect. - -### Slow/Never Changing Component Instances - -Bootstrapping is also very handy for adding values which a user should never be able to change in the GUI. An example of this might be an ID for an analytics service. Since you would always want to have a reliable component instance to use while not allowing users to easily change this value, you might choose to have this in a `bootstrap.(yml|yaml)` file in your site's directory. If a user ever does modify a component instance that is created in this file, simply restarting the server will reset the value. - -## Word of Caution - -The affordances around bootstrapping mean that you can have a `bootstrap.(yml|yaml)` file in each site and each component. At startup time Amphora will try to read all of these and write the values to the database. Because of this, the more bootstrap files you have, the longer the startup time will be. - diff --git a/docs/startup/instantiation.md b/docs/startup/instantiation.md deleted file mode 100644 index 345d7fdf..00000000 --- a/docs/startup/instantiation.md +++ /dev/null @@ -1,37 +0,0 @@ -# Instantiation Arguments - -The most basic Amphora instantiation might look something like the following code: - -```javascript -const express = require('express'), - amphora = require('amphora'), - app = express(); - - -amphora({ - app: app // An Express instance -}) -.then(function (router) { - router.listen(port, ip); - console.log(`Clay listening on ${ip}:${port}`); -}) -.catch(function (error) { - console.error(error); -}); -``` - -Here we create a new Express app, pass it into Amphora and then Amphora will return an Express instance that has been modified with Clay core routes for each site you have created. Once that Express instance is returned \(`router` in this example\), we call the `listen` function, [just like an Express app would](http://expressjs.com/en/api.html#app.listen). - -Assuming you have configured your sites properly and have some components, you'll now be able to access any Clay core routes and any data included in [internal bootstrap files](bootstrap.md) for components and sites will have been added. - -## Instantiation Arguments - -At instantiation time Amphora accepts a config object which contains properties that affect everything from user sessions to plugins for enhanced functionality. Below is a quick list of arguments with references to further documentation resources on the subjects. - -* `app`: an Express instance. If one is not passed in, Amphora will create one during startup. The advantage passing an instance into Amphora is the ability to add any middleware or other configuration necessary for your specific setup. -* `providers`: an Array of strings which correspond to the supported authentication services in Amphora: `apikey`, `ldap`, `google`, `slack`, and `twitter`. For further information on configuring these providers see the [Authentication](https://github.com/clay/amphora/tree/3a300d4ec7af113afd102b4506e7566eb617c9c8/docs/lifecycle/startup/authentication.md) page. -* `sessionStore`: used for session management with user sessions when a provider is configured. For more information see the [Authentication](https://github.com/clay/amphora/tree/3a300d4ec7af113afd102b4506e7566eb617c9c8/docs/lifecycle/startup/authentication.md) page. -* `renderers`: an Object that references modules that can be used to transform component data into different formats. For example, [Amphora HTML](https://github.com/clay/amphora-html) is a module that renders component data to HTML using Handlebars templates. Renderers abide by an API that Amphora sets forth. The `renderers` Object should contain properties whose names correspond to request extensions and whose properties are the handlers for those extensions. A `default` property is used to specify the renderer to be used when no extension is specified in a request. For more information, see the [Renderers](https://github.com/clay/amphora/tree/3a300d4ec7af113afd102b4506e7566eb617c9c8/docs/lifecycle/startup/authentication.md) documentation. -* `plugins`: an Array of Objects that have handlers for different plugin hooks that Amphora exposes. Different hooks are exposed for the startup, request and publish life cycles. For more information see the [Plugins](https://github.com/clay/amphora/tree/3a300d4ec7af113afd102b4506e7566eb617c9c8/docs/lifecycle/startup/plugins.md) page. -* `env`: an accommodation for renderers to expose environment variables used in `model.js` files on the client-side for [Kiln](https://github.com/clay/clay-kiln). These are only rendered in edit mode for a page. For a more thorough understanding of when/how these values are gathered and used, please see the [Component Models](https://github.com/clay/amphora/tree/3a300d4ec7af113afd102b4506e7566eb617c9c8/docs/lifecycle/startup/models.md) documentation. -* `bootstrap`: a Boolean value which defaults to `true`. When set to `false` the internal [bootstrapping process](bootstrap.md#skipping-bootstrapping) will be skipped entirely. **It's advised not to set the value to** `false` **for production instances.** diff --git a/docs/storage-api.md b/docs/storage.md similarity index 100% rename from docs/storage-api.md rename to docs/storage.md diff --git a/docs/upgrade-data.md b/docs/upgrade.md similarity index 98% rename from docs/upgrade-data.md rename to docs/upgrade.md index 0b458ea1..30c280fa 100644 --- a/docs/upgrade-data.md +++ b/docs/upgrade.md @@ -1,5 +1,5 @@ --- -id: data_versioning +id: data-versioning title: Data Versioning (Upgrades) sidebar_label: Data Versioning (Upgrades) --- @@ -10,7 +10,7 @@ Data versioning is a feature of Amphora that aims to address the problem of iter Components follow a very defined path when they're requested. First, the data is retrieved from the database and then it's passed to a `model.js` `render` function for the component \(if one exists\). After that, the component data proceeds to the final output destination, whether that's to be templated into HTML or to be consumed as JSON. Upgrades take place immediately after a component's data is retrieved from the database, making the modified data accessible the `model.js`. -![Upgrade data flow](/amphora/images/upgrade_flow.png) +![Upgrade data flow](/amphora/img/upgrade_flow.png) ## How To Upgrade diff --git a/website/pages/en/index.js b/website/pages/en/index.js index 810c6337..6c52dc57 100755 --- a/website/pages/en/index.js +++ b/website/pages/en/index.js @@ -64,7 +64,7 @@ class HomeSplash extends React.Component {
- +
diff --git a/website/pages/en/versions.js b/website/pages/en/versions.js index 865738b9..c320cd6b 100644 --- a/website/pages/en/versions.js +++ b/website/pages/en/versions.js @@ -33,7 +33,7 @@ function Versions(props) { {latestVersion} - Documentation + Documentation Release Notes @@ -51,7 +51,7 @@ function Versions(props) { master - Documentation + Documentation Release Notes @@ -69,7 +69,7 @@ function Versions(props) { {version} - Documentation + Documentation Release Notes diff --git a/website/sidebars.json b/website/sidebars.json index dabf2f1f..26d8abd9 100644 --- a/website/sidebars.json +++ b/website/sidebars.json @@ -1,10 +1,11 @@ { "docs": { "Introduction": [ - "intro" + "introduction" ], "On Startup": [ - "install", + "startup", + "instantiation", "bootstrap" ], "Basics": [ @@ -16,22 +17,23 @@ "route" ] }, - "publish", - "plugin", + "publishing", + "plugins", { "type": "subcategory", "label": "Renderers", "ids": [ - "building-renderers" + "custom-renderers" ] }, "event-bus" ], "Advanced": [ + "advanced", "storage", - "data_versioning", + "data-versioning", "renderer-models" ], - "Helpful Links": ["glossary-docs"] + "Helpful Links": ["glossary"] } } diff --git a/website/siteConfig.js b/website/siteConfig.js index 9f30738c..8d1d1665 100644 --- a/website/siteConfig.js +++ b/website/siteConfig.js @@ -20,7 +20,7 @@ const siteConfig = { // For no header links in the top nav bar -> headerLinks: [], headerLinks: [ - { doc: 'intro', label: 'Introduction' }, + { doc: 'introduction', label: 'Introduction' }, { href: repoUrl, label: 'Github' } ], diff --git a/website/versioned_docs/version-7.4.0/bootstrapping.md b/website/versioned_docs/version-7.4.0/bootstrap.md similarity index 100% rename from website/versioned_docs/version-7.4.0/bootstrapping.md rename to website/versioned_docs/version-7.4.0/bootstrap.md diff --git a/website/versioned_docs/version-7.4.0/building-renderers.md b/website/versioned_docs/version-7.4.0/custom-renderers.md similarity index 98% rename from website/versioned_docs/version-7.4.0/building-renderers.md rename to website/versioned_docs/version-7.4.0/custom-renderers.md index 07a9727e..e261df46 100644 --- a/website/versioned_docs/version-7.4.0/building-renderers.md +++ b/website/versioned_docs/version-7.4.0/custom-renderers.md @@ -1,5 +1,5 @@ --- -id: version-7.4.0-building-renderers +id: version-7.4.0-custom-renderers title: Building Custom Renderers sidebar_label: Building Custom Renderers original_id: building-renderers diff --git a/website/versioned_docs/version-7.4.0/glossary-docs.md b/website/versioned_docs/version-7.4.0/glossary.md similarity index 95% rename from website/versioned_docs/version-7.4.0/glossary-docs.md rename to website/versioned_docs/version-7.4.0/glossary.md index ef0745b9..08015a15 100644 --- a/website/versioned_docs/version-7.4.0/glossary-docs.md +++ b/website/versioned_docs/version-7.4.0/glossary.md @@ -1,5 +1,5 @@ --- -id: version-7.4.0-glossary-docs +id: version-7.4.0-glossary title: Glossary sidebar_label: Glossary original_id: glossary-docs diff --git a/website/versioned_docs/version-7.4.0/install.md b/website/versioned_docs/version-7.4.0/instantiation.md similarity index 99% rename from website/versioned_docs/version-7.4.0/install.md rename to website/versioned_docs/version-7.4.0/instantiation.md index f7954168..15d21b8e 100644 --- a/website/versioned_docs/version-7.4.0/install.md +++ b/website/versioned_docs/version-7.4.0/instantiation.md @@ -1,5 +1,5 @@ --- -id: version-7.4.0-install +id: version-7.4.0-instantiation title: Instantiation Arguments sidebar_label: Instantiation Arguments original_id: install diff --git a/website/versioned_docs/version-7.4.0/introduction.md b/website/versioned_docs/version-7.4.0/introduction.md index 8a61b218..788b8fd5 100644 --- a/website/versioned_docs/version-7.4.0/introduction.md +++ b/website/versioned_docs/version-7.4.0/introduction.md @@ -1,8 +1,8 @@ --- -id: version-7.4.0-intro +id: version-7.4.0-introduction title: Introduction sidebar_label: Introduction -original_id: intro +original_id: introduction --- ![illustration of an amphora](/amphora/img/amphora-logo.svg) diff --git a/website/versioned_docs/version-7.4.0/plugin.md b/website/versioned_docs/version-7.4.0/plugins.md similarity index 97% rename from website/versioned_docs/version-7.4.0/plugin.md rename to website/versioned_docs/version-7.4.0/plugins.md index 74a0dc36..e3d1f7d4 100644 --- a/website/versioned_docs/version-7.4.0/plugin.md +++ b/website/versioned_docs/version-7.4.0/plugins.md @@ -1,8 +1,8 @@ --- -id: version-7.4.0-plugin +id: version-7.4.0-plugins title: Plugin sidebar_label: Plugin -original_id: plugin +original_id: plugins --- Plugins allow you to extend the functionality of your site by allowing you to attach routes to each site's router in your instance. While this may not seem any different than [defining routes for your site](routes), the basic site router will assign routes that only respond to `GET` requests and will run through Amphora's composition/rendering functionality. Plugins allow you to assign routes that respond to any [Express supported request method](https://expressjs.com/en/4x/api.html#app.METHOD) with your own custom handlers. diff --git a/website/versioned_docs/version-7.4.0/publish.md b/website/versioned_docs/version-7.4.0/publishing.md similarity index 98% rename from website/versioned_docs/version-7.4.0/publish.md rename to website/versioned_docs/version-7.4.0/publishing.md index e0527fd3..43ffcd1e 100644 --- a/website/versioned_docs/version-7.4.0/publish.md +++ b/website/versioned_docs/version-7.4.0/publishing.md @@ -1,8 +1,8 @@ --- -id: version-7.4.0-publish +id: version-7.4.0-publishing title: Publishing sidebar_label: Publishing -original_id: publish +original_id: publishing --- When setting up a site in your Clay instance you add a controller \(`index.js` file\) to define the rules around your sites. One of the rules you can define is _how to determine what url to publish a page to_. This can be done in a number of ways, whether it's just using the current date or analyzing the data in the content of the page. The implementation is your decision \(as long as the url matches a defined Express route\). diff --git a/website/versioned_docs/version-7.4.0/renderer_models.md b/website/versioned_docs/version-7.4.0/renderer-models.md similarity index 68% rename from website/versioned_docs/version-7.4.0/renderer_models.md rename to website/versioned_docs/version-7.4.0/renderer-models.md index 8b91de1b..d57a1607 100644 --- a/website/versioned_docs/version-7.4.0/renderer_models.md +++ b/website/versioned_docs/version-7.4.0/renderer-models.md @@ -11,7 +11,7 @@ A common issue that anyone publishing content to the web faces is how to get the ## Solution -It's important to remember that Clay is a "webpage first" platform. The supported edit interface \([Kiln](https://claycms.gitbook.io/kiln)\) allows Clay data component editing through an HTML page, so generally components are always built with HTML rendering in mind. For that reason, the `model.js` file for a component can modify component/layout data for either a JSON or HTML formats. But what if you request a component with a `.xml` extension? [You'll need a renderer](https://claycms.gitbook.io/amphora/~/drafts/-LJUeZikGqO4SPbtu-9G/primary/basics/renderers) to handle the request, but what if that renderer expects a different input than the component's data? +It's important to remember that Clay is a "webpage first" platform. The supported edit interface \([Kiln](https://docs.clayplatform.com/clay-kiln/docs/intro)\) allows Clay data component editing through an HTML page, so generally components are always built with HTML rendering in mind. For that reason, the `model.js` file for a component can modify component/layout data for either a JSON or HTML formats. But what if you request a component with a `.xml` extension? You'll need a renderer to handle the request, but what if that renderer expects a different input than the component's data? That's where a renderer specific model comes in. It's exactly like a regular `model.js` file except that it's run _after_ the default regular `model.js` file and gives you a chance to modify data for a component to meet your renderers needs. The format for a renderer model is a filename in the following format:`.model.js` diff --git a/website/versioned_docs/version-7.4.0/routing.md b/website/versioned_docs/version-7.4.0/routes.md similarity index 100% rename from website/versioned_docs/version-7.4.0/routing.md rename to website/versioned_docs/version-7.4.0/routes.md diff --git a/website/versioned_docs/version-7.4.0/storage-api.md b/website/versioned_docs/version-7.4.0/storage.md similarity index 100% rename from website/versioned_docs/version-7.4.0/storage-api.md rename to website/versioned_docs/version-7.4.0/storage.md diff --git a/website/versioned_docs/version-7.4.0/upgrade-data.md b/website/versioned_docs/version-7.4.0/upgrade.md similarity index 98% rename from website/versioned_docs/version-7.4.0/upgrade-data.md rename to website/versioned_docs/version-7.4.0/upgrade.md index 20bfa340..7557478c 100644 --- a/website/versioned_docs/version-7.4.0/upgrade-data.md +++ b/website/versioned_docs/version-7.4.0/upgrade.md @@ -1,8 +1,8 @@ --- -id: version-7.4.0-data_versioning +id: version-7.4.0-data-versioning title: Data Versioning (Upgrades) sidebar_label: Data Versioning (Upgrades) -original_id: data_versioning +original_id: data-versioning --- Data versioning is a feature of Amphora that aims to address the problem of iterating on component data. As properties are added or removed from a component's data it's easy to reach a point where data that is already in the database does not meet the requirements/expectations of a template or `model.js`. Data versioning allows you to track which "version" of data your component is on and then bring old data up to that current version, increasing the rate at which new features can be developed around a component. diff --git a/website/versioned_sidebars/version-7.4.0-sidebars.json b/website/versioned_sidebars/version-7.4.0-sidebars.json index 20c61c0e..745a5461 100644 --- a/website/versioned_sidebars/version-7.4.0-sidebars.json +++ b/website/versioned_sidebars/version-7.4.0-sidebars.json @@ -1,22 +1,22 @@ { "version-7.4.0-docs": { "Introduction": [ - "version-7.4.0-intro" + "version-7.4.0-introduction" ], "On Startup": [ "version-7.4.0-startup", - "version-7.4.0-install", + "version-7.4.0-instantiation", "version-7.4.0-bootstrap" ], "Basics": [ "version-7.4.0-routes", - "version-7.4.0-publish", - "version-7.4.0-plugin", + "version-7.4.0-publishing", + "version-7.4.0-plugins", { "type": "subcategory", "label": "Renderers", "ids": [ - "version-7.4.0-building-renderers" + "version-7.4.0-custom-renderers" ] }, "version-7.4.0-event-bus" @@ -24,11 +24,11 @@ "Advanced": [ "version-7.4.0-advanced", "version-7.4.0-storage", - "version-7.4.0-data_versioning", + "version-7.4.0-data-versioning", "version-7.4.0-renderer-models" ], "Helpful Links": [ - "version-7.4.0-glossary-docs" + "version-7.4.0-glossary" ] } }