You can’t get much more native to the web than JavaScript. Indeed, the programming language and its tools have evolved around and with the web – and today it’s central to any serious web programming. Not only is it the standard way of working client-side on the Web browsers, but it’s now becoming as important on the server side with the rise of node.js.

We can all agree that “manageable content” is an important topic in most web projects – though managing content has often been the show stopper for your workflows and coding habits: pushing you to use a Content Management System (CMS). At best, a CMS will force you to write JavaScript code from within its tedious framework – and in the extreme it can push you towards abandoning one or the other: JavaScript or Manageable Content.

This is one of the key problems we wanted to solve when we started working on the prismic.io platform. We also knew that consuming the content repository data from JavaScript (whether from a simple script running client-side, or from a full-featured application running server-side), would be one of the most common usage patterns.

prismic.io provides a content repository with a writing wroom, and an API allowing you to query that content in different ways and pull it into your website or app. It is a fundamental point in the prismic.io design that you can use whatever technology you want to build websites or applications that connect to your content repository. Not only can you choose the technology you prefer (or that is the best match for a particular project), but you will be able to use it in a very idiomatic way: we don’t build “technological bridges” to prismic.io, but we really create development kits and starter projects that embrace the community standards and best practices.

Hence, as soon as we have got our beta out – the JavaScript technology page shows you many ways to work with prismic.io. Let’s take a quick tour of what is available and why working with both prismic.io and JavaScript will make your next project easier.

What we call “development kit” is a minimal library with no dependencies, providing bindings for JavaScript to the prismic.io REST API. It can be embedded into any JavaScript-compatible project to consume the content coming from any prismic.io content repository.

The JavaScript development kit consists of a single file library that you can embed into a Web page to access a prismic.io repository from a web browser, or that you can use as a npm module to embed into a node.js application.

Let’s try to use it from the node.js interactive shell. First, install the prismic.io library from npm:

$ npm install prismic.io

Run the node interactive shell and load the dependency:

$ node
> Prismic = require('prismic.io').Prismic

For experimenting with the API we need to connect to a content repository. We can use the open API from our public example “Les Bonnes Choses” pastry shop.

You can now create a “prismic.io session” by fetching the API end-point.

> Prismic.Api('https://lesbonneschoses.prismic.io/api', function(err, o) { 
  if (err) console.error(err);
  // Store the Api object in a global variable so we can experiment further.
  else api = o; 
})

You can inspect the resulting api object to see that it contains several forms. A form represents a very useful API interface, by filling and submitting a form you will access your content repository data. Why do we have several forms? Simply because our api already created pre-filled forms that represent interesting queries you can run on your repository, based on the document collections that are setup in the writing-room.

For example there is a macarons form, that will retrieve all product documents tagged “Macaron” in this content repository. You can inspect this form data, to discover how it was pre-filled:

> api.form('macarons').data

You will see that it already contains a value for the q field that represents the query:

[:d = at(document.tags, ["Macaron"])] [:d = any(document.type, ["product"])]

Those are two predicates that will constraint the results of this query. You can read more about the available predicates in our documentation, but just know that these two ones will only select “product” documents tagged “Macaron”. What is intetersting here too, is that you can chose a prefilled form, and add predicates on top of it.

In addition of the q field, you also see that this form requires a ref field. You can read more about refs and releases in this previous blog post, but for now all you have to understand is that this ref represents the moment of the repository timeline on which you want to run your query. Most of the time you will run queries on the live version of your repository, a special ref that we call master ref, and whose identifier you can access from the api object:

> api.master()

So let’s fill the missing field in this macarons form to submit the query and inspect the resulting documents:

> api.form('macarons').ref(api.master()).submit(function(err, d) {
  if (err) console.error(err);
  // Store the result into a global variable so we can experiment further.
  else docs = d
});

The result of any query is an array of documents matching the given predicates and available at the provided ref. For the previous query you should get 7 results, that are all live Macarons availables on the “Les Bonnes Choses” example. You can run the same query from the “Les Bonnes Choses” API browser. API browser is a visual tool allowing you to experiment with your content and interactively compose your queries.

If you take a look at the query result on the graphical API browser, you will see that the resulting documents are composed of several fields (that we call document fragments). You can switch between the HTML and JSON views. The JSON view of the documents is of course the one you will get via the JavaScript development kit. Obviously, JSON is really easy to manipulate and to display using any JavaScript framework and templating engine.

On top of the raw JSON structure, we added a few useful helpers you can directly use in your application. For example, for the StructuredText fields, while we give you access to the very low-level JSON structure that describe every bit of text, but we also give you some handy helpers like the asHtml() function which does the HTML rendering for you:

docs.results[0].getStructuredText('product.description').asHtml()

It is a good idea to experiment more and get more familiar with the API, but we will now see that we provide more than this development kit to help you get started with prismic.io and your own project.

Embed prismic.io content into a simple Web page

We have created several starter projects to help you getting started in different situation. One common use case is to just embed a bit of manageable content into an existing Web page. This simple pattern doesn’t require a full-featured client side or server side JavaScript framework, but still that is something JavaScript perfectly does!

Here is a starter project published on our Github, it demonstrates this pattern using JQuery along with a minimal templating engine, to render a prismic.io document as HTML and to inject it into the existing DOM:

As you can see, it uses the same JavaScript library we just played with before, but embedded into a web page. It is then very simple to compose with the DOM manipulation features provided by JQuery to quickly add content management capabilities to any Web application.

That’s a good starting point if you want to display some bits of manageable content into an application that is not itself fully managed using JavaScript, but we all know that it becomes quickly limited for a bigger application.

Full featured single page app using BackboneJS

For a more sophisticated website or web application built with JavaScript you need a more powerful MVC framework. It is exciting that there are plenty of options in the today’s JavaScript eco-system, and the choice of your JavaScript MVC framework doesn’t bring any limitation to the way you will work with prismic.io.

As an example, we have created this example using RequireJS to organize our code base, and BackboneJS as a MVC framework: