This add-on is operated by Elegant Labs Inc.

Headless CMS Builder for modern applications.

Last updated July 27, 2023

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:

$ 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.

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

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

Creating a content type

1. 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.

2. 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.

3. 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 the Last Name field as the content type’s title.

4. 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.

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]

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.

Migrating between plans

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:

$ 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.