California XF Docs
  Guide   Developers Manual   Tutorials   Changelog

Create a story

In this first tutorial, we will set up a basic application that connects to a CXF instance and display a story such as an article or blog post. This tutorial has a nodejs version and a Ruby on Rails version, you can follow either one of them.

Prerequisites: nodejs or Ruby on Rails

Estimated completion time: 10 minutes

 

Create an API Key

Log into your CXF instance and select Config -> Service accounts from the menu in the navigation bar. Create a new service account by clicking on the + icon at the top of the results list, this will open a modal dialog where you must supply the name of the service account. Enter the name and click on the OK button.

The new service account will be selected on the list, and the details will be shown on the right side of the screen, on the details pane. Click on the API key tab and copy the randomly generated API key to use it later in your application project.

 

Configure the default versions

Select Config -> Settings from the menu to open the Settings application, and select Content settings from the explorer pane on the left of the screen. On the right of the screen search for the Public API Options and set the Default status to "published", the Default language to "English", and the Default environment to "production".

 

Create a story

Select Content -> Stories from the menu to open the Stories application. Create a new story template by clicking on the + icon at the top of the results list and selecting New story template from the dropdown, this will open a dialog where you must enter the name of the template. Enter a name, generate a slug, and click the OK button. The new template will appear on the results list.

Click on the small + icon on the right side of the new template to create a new story, and fill in the form as in the following image.

Click the OK button and your story will be selected in the results list. In the General tab of the details pane, search for the body field and click the edit button to open the editor. Start typing an awesome story, and when you're finished close the editor and click the Save to draft button. 

 

Render a story using nodejs

Open a terminal and create a new folder called tutorial. You can start a node project from scratch, but for the sake of simplicity, we will use the express-generator tool to scaffold a very basic project template. We will use handlebars (--hbs) as our view-rendering engine, this will save us from having to write HTML inside our javascript code.

We also install the axios library to make API requests, and nodemon which will help us to automatically restart our node server when changes are detected to our code.

mkdir tutorial
cd tutorial
npx express-generator --hbs
yarn install
yarn add axios nodemon

 

At this point, our project structure looks like this:

.
├── app.js
├── bin
│   └── www
├── package.json
├── public
│   ├── images
│   ├── javascripts
│   └── stylesheets
│       └── style.css
├── routes
│   ├── index.js
│   └── users.js
├── views
│   ├── error.hbs
│   ├── index.hbs
│   └── layout.hbs
├── yarn-error.log
└── yarn.lock

 

Add the watch script in the scripts section of the ./package.json file.

"scripts": {
  "start": "node ./bin/www",
  "watch": "npx nodemon ./bin/www"
},

 

Modify the ./routes/index.js file by adding the following line at the top, under the other require lines.

var axios = require('axios');

 

Modify the ./routes/index.js file replacing the code for the / route with the following code (make sure to replace the API key, the instance subdomain, and your story's slug with the appropriate values):

router.get('/', function(req, res, next) {
  const config = {
    headers:{
      ApiKey: 'XXXXX-----YOUR-API-KEY-----XXXXX',
    }
  };
  axios.get("https://XXX---YOUR-INSTANCE---XXX.mints.cloud/api/v1/content/story-versions/my-first-article?lang=en", config)
    .then(response => {
      let story = response.data.data;
        res.render('index', {
          title: story.title,
          body: story.body
        })
      }
    )
    .catch(err => next(err));
});

 

The previous code will make an API request to the CXF instance and render the index view, passing the title and the body variables. Note that response.data contains the JSON response from the CXF endpoint, which is an object that contains the requested story in the data key. Finally, we modify the ./view/index.hbs view as follows:

<h1>{{title}}</h1>
<p>{{{body}}}</p>

 

Start your server by typing:

yarn watch

 

Open your browser on http://localhost:3000, you should see a 404 error on your console. This is because the story has been saved but has not been published yet. Go back to your story in the CXF UI, select the dropdown next to the save button, and click the Save draft and publish now button. Refresh the page from your node application and now you should be able to see your story.

 

Render a story using the Ruby SDK

Create a new Ruby on Rails project using the following command

rails new tutorial

 

Add the mints gem to the Gemfile file.

...
gem 'mints', '~> 0.0.26'
...

 

Install the Gemfile dependencies using the following commands:

bundle update # run this command if bundle install fails
bundle install

 

Scaffold the files needed by the SDK in the project.

rails g mints_files

 

Modify the host and api_key configuration parameters mints_config.yml.erb file.

mints:
    host: https://XXX---YOUR-INSTANCE---XXX.mints.cloud
    api_key: XXXXX-----YOUR-API-KEY-----XXXXX

 

Modify the application_controler.rb to make the ApplicationController inherit from the Mints::BaseController from the CXF SDK, this will cause any derived controller will have access to the @mints_pub variable which is a client object that has wrapper methods around the CXF API:

class ApplicationController < Mints::BaseController
end

 

Generate a controller with the index action and view.

rails g controller blog index

 

Modify the ./app/controllers/blog_controller.rb file with the following code:

class BlogController < ApplicationController
  def index
    res = @mints_pub.get_story_version('first-steps', {lang: 'en'})
    @story = res['data']
  end
end

 

Note that the res variable contains the JSON response from the CXF endpoint, which is an object that contains the requested story in the data key. Finally, change the code inside the ./app/views/blog/index.html.erb file to render the story.

<h1><%= @story['title'] %></h1>
<p><%= raw @story['body'] %></p>

 

Start your server by typing:

rails s

 

Open your browser on http://localhost:3000/blog/index, you should see an error. This is because the story has been saved but has not been published yet. Go back to your story in the CXF UI, select the dropdown next to the save button, and click the Save draft and publish now button. Refresh the page from your application and now you should be able to see your story.