Elegant CMS
Last updated July 27, 2023
This article is a work in progress, or documents a feature that is not yet released to all users. This article is unlisted. Only those with the link can access it.
Table of Contents
Overview
Elegant CMS provides a headless content management system for your apps.
All content is available according to the JSON API standard.
Content can be compartmentalized between several different apps.
Access to editing content can be controlled through permissioned users; these users do not need Heroku accounts.
Provisioning the add-on
Elegant CMS can be attached to a Heroku application via either the standard UI or the CLI:
A list of all plans available can be found here.
$ heroku addons:create elegant-cms
-----> Adding elegant-cms to sharp-mountain-4005... done, v18 (free)
After you provision Elegant CMS, two config vars (ELEGANT_CMS_URL
and ELEGANT_CMS_TOKEN
) are available in your app’s configuration. These are the credentials required to access the JSON API.
Additional API keys can be added manually for specific purposes from within the dashboard.
The Elegant CMS Dashboard
The Elegant CMS dashboard allows you to administer the app spaces where content is stored, the users who will be editing that content, and the content itself.
You can access the Elegant CMS dashboard by visiting the Heroku Dashboard and selecting the application in question. Then, select Elegant CMS from the Add-ons menu.
You can also access Elegant CMS via the CLI:
$ heroku addons:open elegant-cms
Opening elegant-cms for sharp-mountain-4005
Entity Types
Within Elegant CMS there are several entities you will be able to manage:
- Account
- Users
- Apps
- Content Types
- Contents
Upon creation, the add-on will create a user, account, and app corresponding to your Heroku account. The default account is a container for your app and any additional apps you want to add. Your user will have owner/admin privileges across your entire account, so it is recommended that you create new users for content editors.
Accounts
Accounts are the root-level container under which apps can be collected.
Keep in mind, a user can have permissions for multiple accounts, but only the apps under the current account are displayed at any one time. Users can have different privileges across any number of accounts or apps, so accounts are a good way to compartmentalize groups of similar apps.
Users
By default, your add-on has its own user. This is a sort of super-admin for the entire account, and must be accessed via Heroku. However, other users are identified by their email address and sign in through the Elegant CMS Homepage. You can invite these users via email, and they do not need to have a Heroku account. In this manner you can invite content editors with permissions to edit content within a single app.
The roles available to users are admin
and author
. Generally, admins can modify the structure of your apps’ content types, as well as adding/removing authors and overseeing content. Authors can only author content within the app they’re permissioned for.
Adding users to all apps in an account
To add a user to all of the apps in a particular account, click on “Manage Accounts” in the dropdown menu in the top-right corner next to your icon. Then, choose an account in order to add a user who will now have access to all of the apps within that account.
Adding users to one app
To add a user to only one app in a particular account, while in the app, click on “Settings” in the left menu. Here is where you can add a user who will now have access only to the app on which you are currently working.
Apps
Apps are the containers for content. Generally, they should correspond to the content available to an actual application, though that is not a requirement.
In the top-left corner of the dashboard navigation, Elegant CMS will list all of the apps that you have created. In addition, you will see the ability to add new apps.
Content types
Within each app, you can create **content types` into which you enter your content. Some examples of content types are:
- Blog posts
- Player metadata
- Articles
- Image galleries
- Configurations
- Lists of artists mapped to their respective pieces
Upon provisioning the add-on, creating a content type is the first step you must take before entering content.
Creating a content type
Create a new content type
Click Create and assign a friendly name. The system will suggest an API identifier, which a developer can use later to pull this content from the API.
Add fields
Elegant CMS has many field types you can enter content into. Choose the fields that best suit your needs. Once inside a field, you will have additional configuration options. Most fields are self-explanatory.
Assign a title
You assign one of a content type’s fields to serve as its title. This determines which field is presented in the UI when you’re browsing content. Be sure to select a title that makes it easy to distinguish content. As an example, if you have a
Person
content type, you might assign theLast Name
field as the content type’s title.Configure scheduling (optional)
You can add scheduling to a content type, which allows content to be scheduled with a start and end date. The API will adhere to the schedule you configure.
Field types
Each content type can have one or more fields of the following types:
Text: Perfect for basic text or HTML. Text entry fields can be as simple as a single unformatted line, or as feature-rich as a full WYSIWYG editor.
Number: Allows for both integers and decimals.
Date and Time: Allows a user to use a simple GUI to enter a date/time.
Image: Allows a user to upload an image. You can specify validations to enforce both an exact size or a ratio, such as 4:3.
File Upload: Allows the user to upload a file, such as a PDF or XLS.
Media Collection: Allows a user to bulk upload and then order a collection of images. This is very useful for galleries often used in content apps.
Content Connector: This is one of the more powerful fields. This allows you to reference another content type to join the two together. As an example, if you define one content type for “Cars” and another for “Models”. You can create a connector that maps Cars to Models. When a user creates a new Car entity, they are presented with a simple interface that allows them to select the car’s corresponding model. The list of models is populated from all of the Model entities that have been created.
Entering content
In the Content tab, you are presented with a list of all created content, ordered by the last modified date. You can search, filter, and order content as necessary to fit your needs.
From this interface, you can also create new content for any of the content types that you have defined.
Retrieving data with the API
The API is accessed through an API key. Your account can have as many API keys as you want, divided amongst your apps.
By default, an API Key is generated for you when you provision the add-on. This key’s Token
is stored in the ELEGANT_CMS_TOKEN
config var, however you can add tokens or change the default token at any time.
Generating new API keys
Navigate to Settings > API. Here you can generate an API key for the app you are currently using (listed in the top-right corner of the navbar). You can create multiple keys if you need to distribute them to various consumers of your content and want to control access.
Making an API request
When sending a request to the API at api.elegantcms.io
, you need to pass the authorization token in the header:
- Header Key =
Authorization
- Header Value =
Token token=[ELEGANT_CMS_TOKEN or token_from_dashboard]
Note the case of the two Token words and the whitespace between them.
API request example: Ruby
def load_elegant_data
#build our URI, request and headers
elegant_uri = URI.parse(ENV['ELEGANT_CMS_URL'])
http = Net::HTTP.new(elegant_uri.host, elegant_uri.port)
http.read_timeout = 2
request = Net::HTTP::Get.new(elegant_uri.request_uri)
request["Authorization"] = 'Token token=' + (ENV['ELEGANT_CMS_TOKEN'])
#make the request and store the response
response = http.request(request)
#This will be a JSON encoded string, so lets parse it into a hash.
return JSON.parse(response.body).with_indifferent_access
end
Common request parameters
You can pass parameters in your API requests to filter, sort, or paginate results:
filter[type] =
Slug name of content type you want to filter on
filter[uuid] =
Filter on a single piece of content by its UUID
filter[publish_status] =
Filter on content status based on schedule settings
Possible values:
published
expired
filter[status] =
Filter on user selected status
Possible values:
live
draft
page[number]=
Select page number
page[size]=
Select items to return
sort=
Select a column to sort your results by
Possible values:
updated_at
Example parameter usage
Default listing returns only published content, with a status of live
:
https://api.elegantcms.io/api/v1/contents
Get all content from a content type:
https://api.elegantcms.io/api/v1/contents?filter[type]=game-meta-data
Get a specific piece of content by uuid:
https://api.elegantcms.io/api/v1/contents?filter[uuid][]=1ca80738-bac2-4b06-9870-96fa5d691b3f&filter[uuid][]=5652b051-a0e8-4675-a091-6b5bf0accc3c
Equivalent to passing no parameters:
https://api.elegantcms.io/api/v1/contents?filter[publish_status]=published&filter[status]=live&page[number]=1&page[size]=25&sort=-updated_at
Pagination:
https://api.elegantcms.io/api/v1/contents?page[number]=2&page[size]=100
Filtering on scheduled content: (filter[publish_status] valid values: published, expired, upcoming, none, all):
https://api.elegantcms.io/api/v1/contents?filter[publish_status]=expired
Sorting on valid values: updated_at, -updated_at:
https://api.elegantcms.io/api/v1/contents?sort=updated_at
Filtering on content status: valid value: live, draft, archived:
https://api.elegantcms.io/api/v1/contents?filter[status]=draft
Local development
After you provision the add-on, it is possible to develop against the content by simply copying the configuration variables to a local config file.
Credentials and other sensitive configuration values should not be committed to source-control. It is also recommended to create a separate app entity within Elegant CMS to test your localhost builds.
Migrating between plans
Because higher-tier plans have different quantities of resources available, the tier can always be raised, but decreasing a plan tier without first ensuring your account qualifies could lead to loss of data.
Use the heroku addons:upgrade
command to migrate to a new plan.
$ heroku addons:upgrade elegant-cms:newplan
-----> Upgrading elegant-cms:newplan to sharp-mountain-4005... done, v18 ($49/mo)
Your plan has been updated to: elegant-cms:newplan
Removing the add-on
You can remove Elegant CMS via either the Heroku dashboard Resources
tab or via the CLI:
This will destroy all associated data and cannot be undone!
$ heroku addons:destroy elegant-cms
-----> Removing elegant-cms from sharp-mountain-4005... done, v20 (free)
Status
Status of the service is available at Elegant CMS Status
Support
Feel free to reach out to us at our Support email or via one of the Heroku Support channels.