Add editable elements to your page

Once you have created a page, you will want to add editable content to your page.

Editable content is content that the editors of the site will be able to edit in the back office provided by the Engine.

We are going to show you an example with a very basic index page.

Create the index page

If you just installed Wagon and generated a new app, you should already have a file under:

app/views/pages/index.liquid

This file should look as follows:

---
title: Home page
published: true
handle: home
---
{% extends 'layouts/simple' %}

{% block content/main %}

<div class="row">
  <div class="col-lg-4">
    {% editable_text first_column %}
      <h2>Heading #1</h2>
      <p>Donec id elit non mi porta gravida at eget metus. Fusce dapibus, tellus ac cursus commodo, tortor mauris condimentum nibh, ut fermentum massa justo sit amet risus. Etiam porta sem malesuada magna mollis euismod. Donec sed odio dui.</p>
    {% endeditable_text %}
  </div>
  <div class="col-lg-4">
    {% editable_text second_column %}
      <h2>Heading #2</h2>
      <p>Donec id elit non mi porta gravida at eget metus. Fusce dapibus, tellus ac cursus commodo, tortor mauris condimentum nibh, ut fermentum massa justo sit amet risus. Etiam porta sem malesuada magna mollis euismod. Donec sed odio dui. </p>
    {% endeditable_text %}
 </div>
  <div class="col-lg-4">
    {% editable_text third_column %}
      <h2>Heading #3</h2>
      <p>Donec sed odio dui. Cras justo odio, dapibus ac facilisis in, egestas eget quam. Vestibulum id ligula porta felis euismod semper. Fusce dapibus, tellus ac cursus commodo, tortor mauris condimentum nibh, ut fermentum massa.</p>
    {% endeditable_text %}
  </div>
</div>

{% endblock %}

Simplify the index page

Modify the header of the index page to look as follows:

---
title: Home page
listed: true
published: true
position: 0
editable_elements:
    'content/main/first_column': "<text>"
    'content/main/second_column': "<text>"
    'content/main/third_column': "<text>"
---
{% extends 'layouts/simple' %}

{% block content/main %}

 <div class="row">
  <div class="col-lg-4">
    {% editable_text first_column %}
      <h2>Heading #1</h2>
      <p>Donec id elit non mi porta gravida at eget metus. Fusce dapibus, tellus ac cursus commodo, tortor mauris condimentum nibh, ut fermentum massa justo sit amet risus. Etiam porta sem malesuada magna mollis euismod. Donec sed odio dui.</p>
    {% endeditable_text %}
  </div>
  <div class="col-lg-4">
    {% editable_text second_column %}
      <h2>Heading #2</h2>
      <p>Donec id elit non mi porta gravida at eget metus. Fusce dapibus, tellus ac cursus commodo, tortor mauris condimentum nibh, ut fermentum massa justo sit amet risus. Etiam porta sem malesuada magna mollis euismod. Donec sed odio dui. </p>
    {% endeditable_text %}
 </div>
  <div class="col-lg-4">
    {% editable_text third_column %}
      <h2>Heading #3</h2>
      <p>Donec sed odio dui. Cras justo odio, dapibus ac facilisis in, egestas eget quam. Vestibulum id ligula porta felis euismod semper. Fusce dapibus, tellus ac cursus commodo, tortor mauris condimentum nibh, ut fermentum massa.</p>
    {% endeditable_text %}
  </div>
</div>

{% endblock %}

Note the editable_elements keys that we added to the header of the page.

They refer to the editable_text tags that are included in the body of the page.

The keys entries must include the whole path to the editable element within the editable blocks.

Because the index.liquid page automatically generated by the Wagon extends the 'layout/simple' and 'layout/simple' includes nested blocks containt

Add some content to your page

Let us imagine that you are preparing a website for your favorite Jamaican restaurant, where they propose different meals everyday and want their clients to know the meals of the day.

You could go this way:

---
title: Index
listed: true
published: true
position: 0
editable_elements:
    'some_block/some_slug': "<text>"
    'some_block/some_slug': "<relative path to the file under the public/samples folder>"
---
{% extends parent %}

{% block content/main %}

  <h3>Hello world</h3>
  <p>Our daily meals are:</p>
    <ul>
    <li>Main dish: <span>Jerky Chicken</span></li>
    <li>Drink: <span>Fish tea</span></li>
  </ul>
  
{% endblock %}

Now you have a nice little list with two items. Nothing groundbreaking, though.

If Rick, the boss of the restaurant wants to update its daily meals, he has to install Ruby, then Wagon, then edit the index.liquid file in vi (or whichever editor he likes) and then deploy it to the server...

You can guess that this wont last for long.

This is were the Engine and the editable elements come into play.

Create your first editable_element

Instead of inserting some basic html in your file, you could have done it this way:

---
title: Index
listed: true
published: true
position: 0
editable_elements:
    'main/main_dish': "Jerky Chicken"
    'main/main_drink': "Fish tea"
---
{% extends parent %}

{% block main %}

  {% editable_text 'Main dish', slug: 'main_dish', format: "raw", rows: 1, hint: "Insert here the name of main dish of the day." %}
  {% editable_text 'Main drink', slug: 'main_drink', format: "raw", rows: 1, hint: "Insert here the name of main drink of the day." %}


  <h3>Hello world</h3>
  <p>Our daily meals are:</p>
    <ul>
    <li>Main dish: <span>{{ main_dish }}</span></li>
    <li>Drink: <span>{{ main_drink }}</span></li>
  </ul>
  
{% endblock %}

Now, instead of having to install Ruby, Wagon, learning html, deploying, etc., Rick will now be able to update its website by logging into the Engine and update its site from the nice user interface provided by the Engine.

Let's comment what we've done.

1. The editable_text tags inserted in the body of the file

Let's first start with lines 14 and 15. On lines 14 and 15, we are going to define two editable_text tags which are going to be accessible from the Engine for the editor (Rick) to modify the content.

The first parameter of the editable text tag is a human readable string, between single brackets, that will be used as a label for the editable_text tag. The second parameter is the slug. The slug serves as a unique identifier to make references to the editable_text.

You can discover the other parameters that editable_text accepts on this page.

To explain what we have done above, however:

the format option defines the format in which the text entered by the user will be captured. It can be html, raw or text. Because we only want our user to be able to enter a couple of words, we will use raw;
the rows option indicate the number of rows the input field will have in the Engine;
the hint option indicates a hint that the editor will see next to the input field to help him understand which data he shall input.

2. The editable_elements keys inserted in the header of the file

Then, at lines 7 and 8, we are going to define default content for each of the editable elements we are inserting into the page. This allows us to keep our code organised and separate the data from the business logic.

The syntax is quite straightforward. The name of the slug, preceded by a slash, and then the names of the blocks in which the editable_text tags are inserted. You will learn more about blocks and page inheritance here. But note that if the editable_text tag is inserted within several nested blocks, you will have to reference each of these blocks, from the top level to the lowest level.

For instance, if the "main_dish" editable_text had been inserted into a block entitled sub_block, itself nested within a block entitled main_block, the syntax would be as follows:

'main_block/sub_block/main_dish': "Jerky Chicken"

3. The rendering zone of the editable_elements in the body of the file

On line 21 and 22, we replaced the text content of the by liquid filters making references to the slugs of the editable_text tags defined above.

When the pages will be displayed on a browser, the Wagon servers will automatically replace these filters by the data included in editable_elements keys in the header.

In addition, when deploying your site to the Engine (you can learn more about deploying here), if you use the -d option when doing:

$ bundle exec wagon push production -d

the Engine will automatically fill in, with the values of the editable_elements keys in your header:

the html page visible with the browser to any visitor of the site;
the input field corresponding to the slug of the editable_element, where the editor will have the opportunity to modify the content.

editable_file and editable_control

In addition to edtiable_text, you may use the editable_file and editable_control tags which works more or less the same way.

Learn more about:

That's it.