Introduction
Architecture Guide
Contento is at it heart about managing content for websites. This high-level guide outlines the different kinds of objects that you will interact with in our admin panel.
Assets
Assets are any files you upload in the file manager. You can upload anything you like, and then reference to those files using the assets field type. From within an assets field you can also upload new files and select them immediately.
The file manager will let you re-name the file, add a description, change the filename and also download the source file. From this screen you can also see all the metadata for a file.
When working with the Content API you will often receive an asset that is an image, the URL for that image runs through our handy Image Optimization API so that you can crop, resize, change the quality or even format of the source image. The results are then sent through a CDN to the end-users browser.
Of course you are always free to just download the image and process it yourself, and in the future we will be adding integrations with popular image processing services like Imgix and Cloudinary so that you can do even more.
Content
The core object of Contento is content - everything you create that is a page on your website, or a piece of data that you might use within another page like a category, is content.
Content objects are at their heart very simple, and rely on content types to give them shape. A content object will always have a content type that it belongs to, which in turn will have fields and either be classed as a page, entry or block.
Content Types
These are how you structure and model your content. Decide between three core types of content, and then add fields to store your data in.
Pages
Use the pages object type to store actual pages on your site. These will have slugs / URLs, an SEO tab and the Visual Preview panel. Both SEO and Visual Preview are optional and need configuring in the site settings.
URI pattern tokens
Pages support a number of tokens when defining your URI pattern. You can include the following:
{id}and{slug}— these map to the ID or slug of the page.{language}— the language code of the page e.g.en.
You can also use composite field tokens to access properties of fields on the page in question. Currently we support Text and Content Links fields in the following formats:
{field.some_field_handle.text}— the value of a Text field.{field.some_field_handle.id}— theidfrom the first page linked in a Content Links field.{field.some_field_handle.slug}— theslugfrom the first page linked in a Content Links field.
Composite field tokens can be nested up to three levels deep - each level must be a Content Links field until the last level where it can also be Text.
For example the following patterns are valid where continent, country and city are Content Links fields and city_id is a Text field:
{field.continent.field.country.slug}{field.continent.field.country.field.city.slug}{field.continent.field.country.field.city_id.text}
Entries
Entries are for content that doesn’t have a dedicated page. That might be something like a category or tag that you use on the front of your site to provide re-usable metadata or to filter lists of pages by.
Blocks
When using the blocks field you can decide what types of block users can use. Different block types need different field configurations, so you can create as many as you like and then choose which ones to use on a per-field basis.
Fields
Once you have created the initial content type you can add fields to it - there are many different types of fields available to allow you to structure your content model to suit your needs. Below is a full list of them, with links to their content API object reference.
| Field type | Description |
|---|---|
| Assets | Allows users to add references to assets. |
| Blocks | Users can pick from a selection of block types, fill them in and then re-order them. |
| Content Links | Allows users to add references to other content objects. |
| Date | Renders using the browsers date picker and comes out of the API in ISO8601 format. |
| Decimal | Stores a decimal number value up to two decimal places. |
| Integer | Stores an integer number value. |
| List | Allows users to enter a simple list of text values, they can then re-order them to suit. |
| Long Text | A rich text editor that allows users to write formatted text documents which are then stored as raw HTML. |
| Text | Plain text data, with a maximum length of 255 characters. If you need more then consider using the long text field instead. |
| Toggle | Toggle fields are like switches, users can switch them on or off and you can use them for all sorts of things, like an alternative layout for part of a page. |
If you have a lot of fields you can consider grouping them into logical sets, each group is then rendered as a separate tab on the content editor or block editor interfaces.
Sites
In some Contento plans you can have more than one site - for example you might want to manage your main marketing site but also need to run a microsite or campaign-specific site. Use separate sites for each domain or subdomain that you want to manage content for within one team.
At present sites store very little additional information, in the future we plan to use sites to house integration settings that might enable things like more complex Netlify options or the use of Imgix instead of our Image Optimization API.
All assets, content and content types are stored within one site - so when using the Content API you have to declare which site you want to fetch data from.
Teams
Contento allows each registered user to create and belong to multiple teams. By default, every registered user will belong to a "Personal" team. For example, if a user named "Sally Jones" creates a new account, they will be assigned to a team named "Sally's Team". After registration, the user may rename this team or create additional teams.
Sites belong to teams, and everything else belongs to a specific site. Teams are also how we split up our billing plans, so if you have a personal team on the free plan, you can create a team for your organisation that has a paid plan and then invite your co-workers to it.