The Ruby API Client for LocomotiveCMS V4.
gem install locomotivecms_coal
First, load the gem:
require 'locomotive/coal'
client = Locomotive::Coal::Client.new('http://www.myengine.dev', { email: <EMAIL>, api_key: <API KEY> })
You can get the version of the remote running Engine by calling the following method:
client.engine_version
Note: Coal supports Engine version ~> 3.0.x. However, if you do need to request an Engine running a 2.5.x version, use following code instead:
client = Locomotive::Coal::ClientV2.new('http://www.myengine.dev', { email: <EMAIL>, api_key: <API KEY> })
We do not garantee that all the API resources will work with the V2 Client but PRs are accepted of course.
Get the name of the logged in account
my_account = client.my_account.get
puts my_account.name + " / " + my_account.email
If not logged in, then it's possible to create your account
client = Locomotive::Coal::Client.new('http://www.myengine.dev')
client.my_account.create(name: 'John Doe', email: '[email protected]', password: 'easyone', password_confirmation: 'easyone')
Update my account
client.my_account.update(name: 'Jane Doe')
Only available for super administrators in the LocomotiveCMS engine
Create
new_customer = client.accounts.create(name: 'John', email: '[email protected]', password: 'easyone', password_confirmation: 'easyone')
puts new_customer.name + " / " + my_account.email
Update an account
client.accounts.update(new_customer._id, name: 'Jane')
Get all my sites
my_sites = client.sites.all
puts "I've got #{my_sites.size}"
Create a new site
my_site = client.sites.create(name: 'Acme', handle: 'acme', locales: ['en'], timezone: 'UTC')
Destroy a site
my_site = client.sites.destroy(my_site._id)
Note: We first need to log in to the site. It can be done by calling the scope_by method of the client instance.
site = client.sites.by_handle('acme')
site_client = client.scope_by(site)
Or, in a shorter way:
site_client = client.scope_by('acme')
For the V2 Client, that would be this instead:
site = client.sites.by_subdomain('acme')
Get the list of pages in English
pages = site_client.pages.all(:en)
Get only the id/fullpath attributes
pages = site_client.pages.fullpaths(:en)
It is required when we need the id of an existing page according to its fullpath.
Create a page
page = site_client.pages.create(title: 'About us', slug: 'about-us', parent: 'index', template: 'Locomotive rocks!')
Update a page in French
site_client.pages.update(page._id, { template: 'Locomotive est trop fort!!!' }, :fr)
Destroy a page
site_client.pages.destroy(page._id)
Get a content type by its slug
Note: We first need to log in to the site the content type belongs to. It can be done by calling the scope_by method of the client instance.
site = client.sites.by_subdomain('acme')
site_client = client.scope_by(site)
content_type = site_client.contents.projects
Get the first 10 entries filtered by a property (published)
articles = site_client.contents.articles.all({ published: true })
Loop over all the content entries
page = 1
while page do
articles = site_client.contents.articles.all({ published: true }, page: page)
articles.each { |article| puts article.title }
page = articles._next_page
end
Note: You can also use the following syntax
content_type = site_client.contents.by_slug('projects')
articles = site_client.content_entries(content_type).all
Create a content entry
first_article = site_client.contents.articles.create(title: 'Hello world')
Update a content entry
article = site_client.contents.articles.all.first
site_client.contents.articles.update(article._id, { title: 'Hello world'})
Update a content entry in a different locale
# create the article in the default locale
article = site_client.contents.articles.create(title: 'Hello world')
# then update the title in another locale
site_client.contents.articles.update(article._id, { title: 'Bonjour le monde'}, :fr)
Destroy a content entry
site_client.contents.articles.destroy(article._id)
Get the list of snippets
snippets = site_client.snippets.all
To get the snippets in the FR locale:
snippets_in_french = site_client.snippets.all('fr')
Create a snippet
snippet = site_client.snippets.create(name: 'Header', slug: 'header', template: 'Locomotive rocks!')
# create a snippet in different locales
snippet = site_client.snippets.create(name: 'Header', slug: 'header', template: { en: 'Locomotive rocks!', fr: 'Locomotive déchire !' })
Update a snippet
site_client.snippets.update('header', template: 'Locomotive rocks!!!')
Destroy a snippet
site_client.snippets.destroy('header')
Get the list of sections
sections = site_client.sections.all
Create a section
snippet = site_client.sections.create(name: 'Header', slug: 'header', template: 'Locomotive rocks!', settings: [{ id: 'title', type: 'string' }])
Update a section
site_client.sections.update('header', template: 'Locomotive rocks!!!')
Destroy a section
site_client.sections.destroy('header')
Get the list of theme assets
assets = site_client.theme_assets.all
Create a theme asset
asset = site_client.theme_assets.create(source: Locomotive::Coal::UploadIO.new('<local path of my image>'), folder: 'images/header')
Update a theme asset
site_client.theme_assets.update(asset._id, source: Locomotive::Coal::UploadIO.new('<local path of my new image>'))
Destroy a theme asset
site_client.theme_assets.destroy(asset._id)
Get the list of content assets
assets = site_client.content_assets.all
Create a content asset
asset = site_client.content_assets.create(source: Locomotive::Coal::UploadIO.new('<local path of my image>'))
Update a content asset
site_client.content_assets.update(asset._id, source: Locomotive::Coal::UploadIO.new('<local path of my new image>'))
Destroy a content asset
site_client.content_assets.destroy(asset._id)
Get the list of translations
translations = site_client.translations.all
Create a translation
translation = site_client.translations.create(key: 'hello_world', values: { en: 'Hello world!', fr: 'Bonjour monde' })
Update a translation
site_client.translations.update(translation._id, values: { en: 'Hello world!!!', fr: 'Bonjour monde !!!'} ))
Destroy a translation
site_client.translations.destroy(translation._id)
Get the list of memberships
memberships = site_client.memberships.all
Create a membership
membership = site_client.memberships.create(role: 'author', account_email: '[email protected]')
Update a membership
site_client.memberships.update(membership._id, role: 'designer')
Destroy a membership
site_client.memberships.destroy(membership._id)
We only implemented a few resources (my_account, sites, content types, memberships and content entries) and for some of them, not all the actions have been implemented.
Check the issues section of the repository to see what is missing.
- Fork it ( http://github.com//locomotivecms/coal )
- Create your feature branch (
git checkout -b my-new-feature) - Commit your changes (
git commit -am 'Add some feature') - Push to the branch (
git push origin my-new-feature) - Create new Pull Request
Engine configuration:
- You need to run the last version (master branch) of the Locomotive engine.
- Pick a different database name to run your Coal specs against.
- Run
bundle exec rake development:bootstrap - Run the Locomotive server
bundle exec rails server
System configuration:
- edit your /etc/hosts file (*NIX systems) and add 2 lines 127.0.0.0 www.example.com acme.example.com
Christian, Greg and Ben from the Cogip/Insert International LTD who brainstormed with me (a very long time) to find this awesome name.
Copyright (c) 2020 NoCoffee. MIT Licensed, see LICENSE for details.