Before you can start publishing content there are a few things you need to do. You need to add the locale and dialects to be supported in your installation — even if you only have one language, you have to set at least one default.

We also have to add templates and describe the page types that can be used in the site.

This guide assumes that you have followed the installation instructions and have a Gluttonberg install ready to go.

Logging In

Boot up your merb application, then go to localhost:4000/admin. You will be presented with a login form. You can login with the user you set up during installation.

Add Dialects and Locales

Dialects

Once you’re logged into the back end you can go to Settings > Dialects. You need to add the dialects first, since the locales depend on them.

Click on new. You need to give the dialect a human readable name — English, Spanish etc. — and a code. Generally this code should conform to the ISO 639-2 standard, but doesn’t need to. The only thing you need to bear in mind is that if you are using multiple locales, they will appear in URLs, so you need to use something that works in web addresses i.e. all lower-case, no spaces.

Add as many as you think you need. Make sure at least one of them is set as the default. If you only have one dialect, it should of course be the default.

Locales

Locales are managed in much the same way as Dialects. The only difference is you need to associate the dialects that each locale will supply content for.

For example we may create a locale called Spain and associate it with Spanish and Catalan dialects.

There also needs to be default locale, so don’t forget to pick the one you want.

Page Descriptions

Each page added and managed with Gluttonberg needs to be given a Page Description. These define the various blocks of content that appear in the page, their names and what type they are e.g. Plain Text, Rich Text, Image, Video etc.

These descriptions are defined in config/page_descriptions.rb. The actual definitions are made using a DSL which will be outlined below.

Configuration Block

The definitions need to be contained in a block like this:

Gluttonberg::PageDescription.add do

1. Definitions here…
end


Inside of this configuration block, we can then define multiple page description. A very simple page description would look like this:

page :home do label "Home" description "The homepage, with selected features." view "home" home true

end


The label meant to be a human-readable name for this description, which will be displayed in the back-end when the user edits a page. The description is optional and can be used to give a little more detail about the page description if the label is insufficient.

View defined the template that will be used to render the page with this description.

Content blocks for the page are defined using the section declaration. Each section needs to be given a label and a type. The type refers to the model used to store that content. For example the built in types are :rich_text_content, :plain_text_content, :image_content.

Additional custom content types can also be added, the steps for doing this are detailed in: Page Descriptions

Layouts and Templates

Templates for pages work in roughly the same way they do for regular Merb applications. Each page is rendered with a combination of a layout and view template.

The templates for pages live in the templates directory at the root of your Merb application — this may change in the future. If you don’t have this directory, you just need to start up your app — the directory will be created on first run.

Within templates/ there are directories for layouts and pages.

Naming Conventions

Templates can be automatically selected based on a set of naming conventions. Firstly, if a page description lacks a specified layout or page template, Gluttonberg will fall back to a default. You just need to give the templates the name default.html.haml.

Secondly, you can define templates for different combinations of locales and dialects. For example to define a page template for for Australia/English, you can add a template pages/default.au.en.html.haml

This template will then be the default for that particular locale/dialect combination.

These naming conventions also allow a fall-back if an exact template is missing, from specific to more general. So based on our previous example, the fall back from top to bottom would be like this:

default.au.en.html.haml default.au.html.haml default.html.haml

Layouts

Layouts live in templates/layouts/. These are Merb layouts, so there is nothing special about them.

Page templates

Page templates are placed into template/pages. Straight up Merb templates, so anything you would normally do in Merb you can do with these. The only real kink is writing out page content, which is covered in: Templates and Rendering Content

Adding Content

Now we have all the pieces in place, we can go and add some content. In the back-end you can now go to Content > Pages. From there you can click “new”.

Now, you won’t be able to edit content directly here, instead you need to define all the meta-data associated with a page first. After this is done you will be able to edit the content for each locale/dialect pair you have defined.

Read Managing Content for a more detailed explanation of the steps involved.

Once you have some content entered into the database, you can now visit the front-end to see what it looks like.