Ruby on Rails starter project for prismic.io
This is a blank Rails project that will connect to any prismic.io repository, and trivially list its documents. It uses the prismic.io Ruby developement kit, and provides a few helpers to better use it with Rails.
Launch the starter project
After forking and cloning the starter kit, it is immediately operational, so you can launch your
rails server command. You may have to update your gems by running
bundle install, but Rails will tell you about it if you must.
By default, the starter kit uses the public API of the "Les Bonnes Choses" repository; its endpoint is
https://lesbonneschoses.prismic.io/api. You may want to start by editing the
config/prismic.yml file to make your Rails application use your own prismic.io repository.
To get the OAuth configuration working (and be able to preview your future content release, as well as to access your API if it's private), go to the Applications panel in your repository settings, and create an OAuth application to allow interactive sign-in. Fill the application name and the callback URL (localhost URLs are always authorized, so at development time you can omit to fill the Callback URL field), and copy/paste the clientId & clientSecret tokens into the
You may have to restart your Rails server.
Get started with prismic.io
Understand the Ruby development kit
You'll find more information about how to use the development kit included in this starter project, by reading its README file.
Specifics and helpers of the Rails starter project
There are several places in this project where you'll be able to find helpful helpers of many kinds. You may want to learn about them in order to know your starter project better, or to take those that you think might be useful to you in order to integrate prismic.io in an existing app.
- its role: providing a module you can use as a mixin in your controllers to make it trivial to use prismic.io in your actions.
- provides the
apimethod to instantiate your
Prismic::Apiobject once per HTTP request.
- provides the
refmethod, retuning the ref id being currently queried, even if it's the master ref. To be used to call the API, for instance:
- provides the
maybe_refmethod, returning the ref id being queried, or nil if it is the master ref. To be used where you want nothing if on master, but something if on another release, for instance:
- provides all necessary controller actions to have the OAuth pages working: signin, signout, callback, ...
- the routes to the OAuth pages: signin, signout, callback, ...
- provides a basic
link_resolver(ref)method to iterate upon. For a given document, the
link_resolvermethod describes its URL on your front-office. You really should edit this method, so that it supports all the document types your content writers might link to (read the very last paragraph of our API documentation to learn more about what link_resolver is for).
maybe_refmethod, just like in the
PrismicControllermodule, to be used in the views.
- provides a basic
config/prismic.yml: centralizes all information about the prismic.io repository's API (endpoint, client ID, client secret, ...)
slug_checker(document, slug), which checks a provided slug against a document.
get_document(id, api, ref), which retrieves the document from its id.
- provides a number of other methods that some other helpers rely on (
init_api, ...). If you're integrating prismic.io into an existing project, you really want that file.
- allows you may customize the Ruby kit's behavior here.
*out-of-the-box allows you to write
as_html_safe(link_resolver(maybe_ref))in your views, instead of having to write
- allows you may customize the Ruby kit's behavior here. *out-of-the-box allows you to write
- we've also included some basic pages by default, with their routes, controllers and views:
- the "index" page displays all documents, paginated by 20, and lists them as links towards their "document" pages.
- "document" pages display a whole document in a trivial way.
- "search" pages are search results.
app/views/layouts/application.html.erb, all those pages contain the necessary UI components to have the OAuth working out of the box: signing in, signing out, selectbox to change the previewed content release, ...
Other technical operations
Work with a local database
You don't actually need a database to run this starter project, as prismic.io handles everything for you (content, users, ...); if your website is all about content, you may never even need a database at all! Therefore, our starter project comes without ActiveRecord (the part of Rails that handles the connection with databases, and the model tier)
However, if your project offers other features than displaying content, you may need to store and retrieve non-content data from a local database. Here's how you put ActiveRecord back in your Rails starter project:
- Comment-out the 4
requirestatements at the top of application.rb, replace them with
- Add the gem for the kind of database you have in mind to use (you can un-comment-out the one we left for SQLite, but we advise you to rather use the kind of database you will use in production).
- create your
config/database.ymlfile, which entirely depends on the kind of database you'll be using. Here are exemples of usual database.yml files, but you should rather check the documentation for the database gem you're using.
- Un-comment-out the
ActiveRecord::Migration.check_pending!line we left for you in test_helper.rb.
- Un-comment-out the
config.active_record.migration_error = :page_loadline we left for you in test_helper.rb.
Deploying your application
This starter project is immediately deployable on most hosting platforms that are compatible with Rails 4. To deploy it on Heroku, simply create a Heroku account, install the Heroku Toolbelt, and log into it by running
heroku login in your terminal.
Then, go to your project's directory in your terminal, and run:
heroku create git push heroku master
Now your site is live for the world to see!
Contribute to the starter project
Contribution is open to all developer levels, read our "Contribute to the official kits" documentation to learn more.
This software is licensed under the Apache 2 license, quoted below.
Copyright 2013 Zengularity (http://www.zengularity.com).
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this project except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0.
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.