Cloud Connected

Thoughts and Ideas from the Gitana Development Team

Precompile your Text fields with Markdown or Handlebars

One of the new features in Cloud CMS 3.2.41 is the f:precompile feature. This feature tells Cloud CMS to automatically precompile one or more fields on your content items whenever the content is saved.

With precompiling in place, you can now let your editors work in Markdown or use Handlebars tags in their content and then have that content automatically convert into HTML (or another output format) for use in your front-end applications.

An Example

Suppose, for example, that you defined an artcle with two fields (title and body). We define a third field (html) to store the precompiled text. The schema might look like this:

{
    "title": "my:article",
    "type: "object",
    "properties": {
        "title": {
            "type": "string",
            "title": "Title"
        },
        "body": {
            "type": "string",
            "title": "Body"
        },
        "html": {
            "type": "string",
            "title": "HTML"
        }
    }
}

Let's set up the body field to use Markdown. That way, our editors can write things using Markdown and avoid the torrid affair of dealing or modifying HTML directly. We can also make the html field hidden so that editors don't have to see that field and can instead just focus on what matters.

We can define a form like this:

{
    "fields": {
        "body": "markdown",
        "html": {
            "hidden": true
        }
    }
}

When editors use this form, it will look like this:

precompile1.png

Awesome! Now let's add a mandatory feature to the my:article type so that any articles our editors create and work on will automatically have their html field updated. To do so, we modify the my:article schema and add the following to the end:

{
    ...,
    "mandatoryFeatures": {
        "f:precompile": {
            "steps": [{
                "sourceProperty": "body",
                "targetProperty": "html",
                "processor": "markdown"
            }]
        }
    }
}

The f:precompile feature lets use define one or more steps that should execute upon save. In this case, we tell the feature to auto-convert the markdown from the body field and save it in the html field.

As an editor, we can now use a form to create an article. Let's say they fill in the following markdown:

# Milwaukee Brewers win World Series!
The [Milwaukee Brewers](https://www.mlb.com/brewers) have made history, becoming the first MLB team to with 162 games straight and sweep the World Series in 4.

Here is what the creation form would look like:

precompile2.png

The editor clicks Create. That's it, they're all done.

As a developer, if you were to now crack open the JSON for what they created, it'd look like this:

{
    "title": "Milwaukee Brewers win World Series!",
    "markdown": "# Milwaukee Brewers win World Series!\nThe [Milwaukee Brewers](https://www.mlb.com/brewers) have made history, becoming the first MLB team to with 162 games straight and sweep the World Series in 4.\n",
    "html": "<h1>Milwaukee Brewers win World Series</h1><p>The <a href='https://www.mlb.com/brewers' title='Milwaukee Brewers'>Milwaukee Brewers</a> have made history, becoming the first MLB team to with 162 games straight and sweep the World Series in 4."
}

The html field contains your precompiled HTML - ready to go and be used in your front-end web site or application.

Future Roadmap

We're very pleased to offer the f:precompile feature as it further delivers on our philosophy of having Cloud CMS "do things automatically" on behalf of your editors. Our vision, which is often state but bears repeating, is that we'd like editors to be able to "Click on Save and walk away". The system should do things automatically for them (by adding value, saving time and reducing error). It should perform these things and additionally normalize the expected results so that developers get precisely what they need.

In terms of the roadmap for this feature, some of the things we're thinking about include:

  1. Additional text processors
  2. More default, out-of-the-box Handlebars helpers
  3. Precompiling to additional output formats (such as PDF)
  4. Storing output onto attachments

We'd love to hear your feedback.

As always, let us know what we can do to make Cloud CMS a better product for you and your organization!