This guide covers how to use the tools that come with BrowserCMS to extend the functionality of your BrowserCMS site. The target audience for this guide is intermediate to advanced Rails developers. You should also read the Building a Site with BrowserCMS guide first as well, so you know how to create pages and put content on pages. This guide will cover:

Content Blocks are the basic unit used to add content to pages in a BrowserCMS site. There are several pre-built content types that are part of BrowserCMS core. The most commonly used one is the HtmlBlock content type, so we will use that as a starting example.

If you look at the HtmlBlock model in BrowserCMS core, you will see that it is an ActiveRecord model, just like any model you create in a Rails application. It also calls the acts_as_content_block method, which just sets up several Behaviors on the model. One of the key Behaviors to understand is the Rendering behavior. Essentially what this behavior does is to allow a model (by model I mean a subclass of ActiveRecord::Base) to act as a mini-controller. This is the same thing conceptually as Merb Parts or Rails Cells, the only difference is that content blocks are models as well, so they have attributes that are stored in the database like any other model.

In the BrowserCMS implementation, first the render method of the object is called, which is like an action. This is where instance variables are set. In the case of an HtmlBlock, there are no other instance variables to set up, so this step is just skipped. It is similar to a controller action that has no action method, it just goes straight to the view.

The view is the render template, which is inside the cms/html_blocks directory in the view path. If you look in the render template, you will see all it does is print the value of @content_block.content. Content is the name of the property that holds the HTML content.

Let’s say that you are using BrowserCMS to build a website that will display a list of products. The first step would be to create a product content block. This will give the users of the CMS a way to create products. To create a product content block, in an existing BrowserCMS project, run the content block generator:

You will notice that several things have been created:

If you look at app/models/product.rb, you will see that it is nothing more than:

The controller created at app/controllers/cms/products_controller.rb is equally empty:

This controller is the controller used in the actual CMS interface. If you want to create a controller to use in the front end of your application, create a products controller that is not in the CMS namespace, so as not to conflict the CMS functionality. You will most likely not need to customize the CMS controller at all.

The form partial at app/views/cms/products/_form.html.erb is the form that will be used when creating/editing the product content block in the content library of the CMS. The contents of this file will be:

The form helper methods that are prefixed with cms_ will wrap that form helper with the CMS styling and extra functionality. The cms_text_editor will show the user a WYSIWYG editor for editing HTML. Additional CMS form builder extensions are covered in the BrowserCMS Designer Guide.

The render template at app/views/cms/products/render.html.erb is the template that will be used to render the HTML when this product is placed directly on a page. It is also what is shown when you view a product within the content library of the CMS.

As you will see in the next section, custom content blocks are often not placed directly on a page, instead the data of a product is displayed through a portlet. For this reason, a more informational display, similar to what is automatically generated by the generator, is what the render template often contains. Depending on what your content block is, you may want to place the content block directly on a page, in which case you would most likely customize the render template.

Once you have created the product content block and created a few products in the content library, you need a way to display them on a page. To do that, you will want to create a portlet.

A portlet is used to display dynamic data on a page. A portlet is a content block. A portlet will typically perform some kind of database query in the render method and then render it’s view. One difference between a portlet and typical content block is that each instance of a portlet can have a unique template because that template is stored as data along with the portlet. Let’s generate a portlet to display the most recently created products:

What you will see created is:

What you don’t see created is a migration. Portlets use the DynamicAttributes behavior in order to store associated values in the database without having to create custom database tables. What this means is that you can set and then store a value for any attribute for a portlet.

So if you look at the form partial that was generate for this portlet, you will see this:

Every portlet instance has to have a name and that is stored in the main portlets table, but limit is stored in the portlet_attributes table. You could add anything to this form, such as <%= f.cms_text_field :foobar %>, and whatever the user enters for foobar would get saved with the portlet.

If you look at the code for the portlet, you will see:

As the comment says, you will want to fill in your application logic here. We’re going to get the most recent products and use the value the user entered for limit when they filled out the form. So edit the code to look like:

self in this case is the portlet instance, which is also available in the instance variable portlet</tt>. We are setting the <tt>products instance variable so that will be available in the view. If you look at the render template, you will see this:

This is simply a place holder, you should override this code with something similar to what you expect the user of your portlet to want to use. In this case, let’s go with:

Notice that in the last paragraph I said "similar to what you expect the user of your portlet to want to use". This value is simply the default starting point for the template of a portlet. The actual value is entered into the form when the user creates an instance of this portlet.

If you look back at the form partial that was generated, you’ll see:

What this does is preload the template with whatever you entered into the render template. The user is free to change it as they see fit and even have different values from one portlet instance to the next.

This guide covers how to use BrowserCMS to build and manage websites. After reading it, you should understand how to:

This guide is aimed at people who are managing sites using BrowserCMS, as opposed to programmers who want to customize it, or designers who want to create new designs for a site.

This document assumes that users have a working copy of BrowserCMS to play with, either on their local machine, or on a demo site. We don’t cover how to install CMS here, so see the Getting Started Guide in order to get up and running.

In addition, an installation of BrowserCMS will have several templates already installed. The theme might be the default BrowserCMS theme, or a custom theme designed for a specific client. This document does not cover how to design and create new themes/templates, but focuses on the day to day work that content managers will need to do.

There are several concepts which underly how BrowserCMS works. To be productive, users of BrowserCMS should ideally understand these ideas:

This section will cover some of the more frequent tasks that site managers will need to undertake in order to manage their website. For the purposes of this section, all examples assume a locally running copy of BrowserCMS, accessed as http://localhost:3000. A site hosted elsewhere might be running at http://yourcms.yourcompany.com.

To access that administrative portions of a CMS, you have to go to the admin login page. To do this, add /cms to your website’s URL. Working locally, this would be http://localhost:3000. From this page, you can log in with your username and password. For a local site, this will be username = cmsadmin and password = cmsadmin. For a live site, this will have been randomly set during install.

After you log in, you will be sent to the dashboard (/cms/dashboard). The details of this page will be covered later, but the dashboard serves a summary of content in various workflow stages. From here, you can jump to other sections of CMS.

To understand how editing pages in the CMS works, let’s jump over to the homepage. The quickest way to do that is to click on the BrowserCMS logo in the top left. This will always take you to the home page for your site. When you visit a page in BrowserCMS, and are logged in as editor, you will see the page exactly as a visiter would, with the addition of a toolbar at the top of the page. This toolbar gives you the tools/buttons necessary to make changes to pages, or jump to other CMS admin tabs.

One of the key concepts to make page editing easier in BrowserCMS is called In Context Editing. It allows you to browse the site as a visitor would, and then edit content directly on the page. By default, you can’t see the editable areas of a page (called Containers), because the Visual Editor is turned off. To show the containers, click the Turn On button on the right side of the toolbar, which turns on the visual editor. You should now see the containers highlighted on the page. The templates for each page determine what areas of the page are editable. Clicking the Turn Off button will hide the containers again, giving you a more accurate view of what the finished page will look like.

A container is marked by a box with a grey header, with several buttons on it. Each container has two controls, one to Add new content to that container (The + icon) and another to place existing content into the container. It also has a status indicator which shows if any content blocks in that container are in draft mode. Each container can hold zero or more content blocks.

Each block within a container is marked with a grey border, and several buttons. Blocks can be edited, reordered using the up or down arrows, or removed from the page (which does not delete it).

To edit some existing content, pick the block you want to edit, and click the wrench icon. This will take you to the edit screen for that block. Most content blocks placed on pages are usually Text blocks, which are just pure html content, with a name for organization purposes. On the Edit Text page, you can change the name, or use the WYSIWYG editor to make changes to the content. If you want to edit the source html directly, you can change your editor preference with the toggle to the top right of the editor.

Once your edits are complete, you can save your changes using the Save button at the bottom of the page. This will return you to the page, where you can see how your changes look in context to the rest of your page. Your changes won’t be visible on the public site yet, so you can choose to make more changes. See the next section on how to publish changes.

The basic rule of publishing is that all changes need to be published before they go live. This allows editors to always see how their page is going to look, before they decide to commit their changes. Any time you alter how a page looks, the CMS stores a new version of that page and all its content. This happens when you add a new block to a page, make an edit or remove a block from that page. Each time a change is made to content on a page, that page will go into Draft status. As an editor, you will see the latest version of that page, but the public will continue to see the last published version of that page.

Each page has a status of either Published or Draft. When you like how your changes look, and want to publish the page, push the Publish button in the upper left hand corner of a page. This will makes your changes live and visible to the world. When a page is published, each block on that page will also be published.

To add new pages to a site, click on the Site Map tab from any where within the CMS admin. The Site Map page shows a tree with all the sections and pages in your site. From here, you can add new pages or sections, choose a page to edit, or reorganize the site using drag and drop to move sections around.

To add a new page, click on the My Site section at the top of the site map. Then click the Add Page button in the toolbar. This will add a new page to the root of the site. There are several fields to fill out the important ones are the name and templates. When you name a page, the CMS will generate a default relative URL (a path) for it. You can also choose a template via a drop down, which will show all available templates for the current site.

After filling out those two fields, you can click save to create the new page. After saving, you will be taken to that page, which will be blank, not having content blocks selected for it.

When viewing a page, you can add new content to it. First, make sure the Visual Editor is turned on, so you can see the containers. Find the Add Content icon (+) on the container you want to add the new content to. You will then be able to choose what kind of content you want to create. Text is the most frequently used content type, and is essentially just HTML, including the ability to create links and include images.

Choosing Text will take you to the Add New Text screen. The first field will prompt you for a name. This name is used to help identify your content later, when you are looking for it in the Content Library. Naming Text blocks after the page they are going on is a common choice. The second field is content, which allows you to enter formatted text using a rich text (or WYSIWYG) editor. The editor has buttons for common formating options, like making text bold, copy/pasting of text (including from Microsoft Word) and creating links to other pages.

If you like, you can also change your text editor choice from ‘Rich Text’ to ‘Simple Text’, which will allow you to edit the source HTML directly. This choice is saved as user preference, so next time you edit content, you will use the same editor you picked.

When creating content for pages, its a common task to add images or link to files (like PDFs) in the body of the text. There are two steps to adding an image or file to a page. First you need to upload the image/file to the content library. The second is to link to or place the image within a Text block. It is possible to directly place an image or file block into a container (via the Add New Content option we talked about earlier) but this gives you less control over formating and placement.

To add an image or file to the content library, click the Content Library tab, and then click the Image or File menu items on the left hand side. (These content types are under the Core module, so you may need to click Core to show all the content types) Next click Add New Content on the main menu. From here, you can fill in all the details on your image/file, including the file on your local hard drive that you want to upload. One of the choices about creating Image and Files is which section they should be stored in. It’s a good idea to create one or more image/file galleries to keep your files organized.

After the file is uploaded, you can then place it on a page using a Text block.

To place an image, first find the text block that you want to edit (or add). Using the Rich Text editor, click the Insert/Edit Image button. Next click Browse Server, which will allow you to browse through all the images in your content library. This will popup a window which gives you a sitemap view of your site. You can drill down through the sections, finding which the one where you placed your image. Once you locate the image, click the image name to select it. This will add the path to the image to the Image Properties, and allow you to preview the image alongside the text. You can alter the image attributes (size and alignment) or just click Ok to place the image.

At this point, the Rich Text editor should display the image embedded in the text. You can then save the Text block, and see how it looks on your page.

Placing a file is very similar to placing an image. Select the Text block to edit, and click the Insert Link button. On the Link popup window, click the Browse Server button. Using the Site Map browser, choose the file you want to link to, and then select it. This will paste the path to the file into the Link window. Click Ok to add the link to the Text block.

BrowserCMS features two ways to locate pages to make changes to. The first one is just browsing around the site, using the same navigation that your site users would. The second is the by using the Sitemap.

When an editor is logged in, they can browse around the site using the same menus and links that a guest would. Each page will appear with a toolbar, which only editors see, which allows you to make changes to pages and their properties.

The Site Map allows editors to see a more conventional file and folder metaphor to browse through the structure of the site. Clicking the Sitemap tab will take editors to this view. Once on the sitemap, editors can expand/collapse sections by clicking on the +/- buttons. They can drill down into each section, to locate the page they want to make changes to. Once the page is located, either select the page and click Edit Page on the toolbar, or just double click the page name. Both take users to the Edit Page view, which allows them to modify the page content.

Mistakes happen. Sometimes you make a change to a page, and you don’t like how it looks, or you just want to go back to last week’s version. To roll back a page to an earlier version, you must first edit that page (either by navigating to or by the sitemap). Select the List Versions button from the toolbar. This will show the complete history of the page, along with who made changes, when the change occured, and note about what change happened in that version.

To see what an older version looked like, select a version, and click View on the toolbar. (Recommended Tip: Open the version in a new tab in your browser, by Ctrl-Click on PC, or Command-Clicking on Mac. This will let you compare several versions side by side.) If you like that version, you can revert to it in two ways.

From the List Versions page, you can revert by selecting the version, then clicking Revert. If you are viewing an older version, you can revert by clicking the Revert to This Version. In both cases, it will restore the page to what it looked like in that version, and will mark the page as Draft. Once the editor has reviewed the changes, they can publish it.

Reverting can be a bit tricky to understand. The basic challenge comes from the fact that both pages and block have their own versions, and blocks can be shared across pages. Consider the example of two pages, Page A and Page B, which both share a Text Block C. Every change to C will also create a new version of A and B. Reverting page A will also likely revert page B. Since reverting a page puts it into Draft, you now have two pages in draft mode. You need to publish both of them to make their changes live. This might be manageable for two pages, but imagine you had a Text called footer which was shared across 20 pages.

See ‘Bulk Publishing’ below for details on how to publish multiple pages at once.

There are two ways that BrowserCMS supports navigation. The first is that navigation is manually added as HTML to templates. This is suitable for Fixed Space navigation, which might need to be exactly 400 pixels wide and contain exactly 4 menu items, potentially using images for buttons. The second is using dynamic navigation, which can easily grow as the site architecture does. This is more suitable for sub-sections of the site. BrowserCMS allows editors to dynamically render menus based off pages in the sitemap.

When developers create templates, they can set up menus so that they dynamically link to pages in the sitemap. Menus will show both pages and sections, and can show go one or more levels deep, which reflects how users are drilling down into the site architecture. By default, when an editor adds a page or section to the sitemap, under a specific section, a link to that page will automatically be added to the dynamic navigation. For both pages and sections, you can have the option to Hide from menus, which you can do by editing the properties of either pages or sections. Hiding a page from a menu means its still accessible to the public (if the user knows the URL), but just doesn’t appear in the menus.

When pages and sections are created, they are added last in their parent section. They can be reordered though from the Sitemap, by dragging and dropping. To move a page or section, click-hold and drag the page/section where you want it to be. This allows editors to both reorder pages within a specific menu, or move it to another area of the site entirely.

Dropping an item onto a page will place it after that page. Dropping an item onto a section will put it in that section, as the last item. Be aware that moving pages will immediately make changes in how the dynamic site menus appear (there is no publish step needed).

It’s a common task to want to restrict specific users from being able to see certain pages. This might include creating a members section, where only registered and approved users can see the content. BrowserCMS allows editors/admins to restrict user access based on sections. Individual pages get their security from their immediate parent. For example, if there is a section called Member Only, which a Guest cannot see, all pages in that section will be block, and guests (unregistered users) that try to access those URLs will be sent to the Access Denied page.

The first step to secure a section is to set up the groups who are allowed to see it. An administrator can create a new group by clicking the Administration tab, then selecting the Groups item from the left menu. Click the Add Group button, give the group a name (Members), and choose Registered Public User as the group type. By default, this group will able to view all sections within the site. After saving the group, you can alter which sections a user can see, by clicking the name of the group. In this case, the new Member group’s permissions are fine.

The next step is to create a user in the Member group. On the Administration tab, click the Users menu item on the left menu, and click Add User on the toolbar. Fill in the basic user information (name, username, email and password) and check the newly added Members group (but no others)

The next step is to add the new section, which will be restricted so that only users who are in the Member group can see them. Go to the sitemap, select the My Site (which is the root of the site) and click Add Section. Name the section Members Only, and then uncheck all public permissions except for Member. Next add a page to this section and publish it.

Now, when users who aren’t logged in (Guests) try to visit any pages in the Members Only section, they will be redirected to the Accessed Denied page.

When the number of contributors to a website grows, it may be necessary to restrict who has rights to publish content. This would allow for multiple editors to contribute and edit content, but content would be passed to one or more ‘publishers’ in order to commit the changes publicly. Workflow in BrowserCMS has several concepts which make it work:

This section covers how to create a simple workflow, that covers two kinds of groups of people.

The first step is to create two new groups, both of which should be of type ‘CMS User’. One should be called Contributor, and should only have the ‘Edit Content’ permission. The second group should be called ‘Publisher’, and should have ‘Edit Content’ and ‘Publish Content’ permissions. Next create two users, and assign one of them to each group.

The user in the Contributor group, will be able to make changes to pages and blocks, but will not be able to publish it themselves. When they are done with a page, on the Edit Page view, they can use the Assign button to pass the page to somebody who has publishing rights. Assigning a page provides a drop down with all users who have Edit Content permissions. The contributor can choose the assign to the Publisher, give it a due date and a comment, and then assign the page. This will notify the Publisher via email they have a new task assigned to them, along with the URL to the page.

The Publisher can then log in, find the page they want to review, make sure the changes are acceptable, then publish the page. Once they are down with their task, they can click the Complete Task button to close the task out. In addition, editors and publishers can always find what open tasks they have by going to the My Dashboard.

The dashboard is the landing page for editors when they log in. It has two main areas, one shows all pages currently in draft. The other shows open tasks assigned to the current users.

Some operations in the CMS can put multiple pages into Draft mode as a side effect. This includes making an edit to a block which is shared across multiple pages, as well as reverting a page with shared blocks on it. The Page Drafts panel shows all pages in the CMS which are currently in draft mode. An editor can choose to review each page to make sure it looks right, by clicking on the name of the page. Or they can just select all pages they want to publish via the checkbox, and then click ‘Publish Selected’.

All of the open tasks that are assigned to a user will appear on that user’s dashboard, in the Tasks panel. Users can click on the name of the page to review it, and either complete the task, or assign it someone else.

For most sites, the majority of the content will be placed directly on pages using Text blocks. Another alternative is to use portlets, which can dynamically select and render content. Portlets are usually part of individual modules, and are used to find and display content from that module. For example, the News module comes with several portlets, designed to find News Articles by specific criteria. One portlet may display a single Article (using an id parameter in the URL), while another may show the headlines to all Articles, chronologically ordered.

Portlets are one of the primary extension points of BrowserCMS, which allows programmers to create new dynamic behavior and allow it to be placed on pages alongside static content. Each portlet will have several attributes which allow users to configure the portlet. These attributes might include a name, max # of results to display, and a template to allow users to change how the portlet displays. This section assumes the News Module has been installed, and walks through the placing and configuring of a portlet.

Start by creating a new page. Select the Add New Content icon in the container you would like to add the portlet to. On the Select Content Screen, choose the Portlet type. Then choose which type of portlet you would like to add (Choose the News Archive portlet). Give the portlet a name, leave the categories empty and use the default template.

The News Archive portlet is designed to show a list of New Article blocks. So by default, there probably aren’t any News Articles in the database, so the Archive won’t be displaying anything. Let’s add some News, so we can see how it looks.

Choose the content library tab, and open the News module, by clicking the News link on the left. The News Article content type should be selected. Click the Add New Content to create a News Article. On the form, fill in a suitable name, summary, set the release date to today and body, and then click save.

Now return to the recently added portlet. You can do this by opening the Core module, selecting portlets and browsing/searching for the portlet you created. This will allow you do see the portlet in isolation from the page. Alternatively, you can return to the page you were on, to see the portlet where it is placed. The portlet should now be displaying a summarized version of the News Article you just created. You can control how the portlet displays the list by editing the template, which requires an understanding of Ruby/ERB and Html.