-
Notifications
You must be signed in to change notification settings - Fork 9
User's manual
This guide covers how to use BrowserCMS to build and manage websites. After reading it, you should understand how to:
- Create new pages
- Organize your site navigation via the sitemap.
- Place content on pages.
- Dynamically display content on pages using portlets.
- Create and assign permissions to users.
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 templates for a site.
This guide is for BrowserCMS 3.3.
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:
-
Pages – Visitors experience your site primarily via pages. Pages are really compound documents, consisting of more than one editable area of content. The allows for intricate design, without needing to be edited via single giant HTML area.
-
Content Blocks – Blocks are the most granular bits of content in a system. Pages usually have one or more blocks of content associated with them. Content blocks can be anything from a simple fragment of HTML, to a News Article (which might have multiple data fields like name, body and summary), to portlets, which dynamically display other types of content.
-
Portlets – Sometimes you don’t want to manually place all the content on your site. You want to set up some rules, so that when new content is entered, it appears in multiple places. Portlets are generally how that gets done. Portlets are really just a slightly special version of blocks, which generally query for other blocks, and then format them for display.
-
Sections – Each page lives in a section. Sections the primary way pages are organized. Menus are usually dynamically constructed based off the hierarchy of sections and pages. Sections also handle security, where individual groups are allowed to see pages within a given section. Sections and pages can be reordered by using the Site Map tab.
-
Templates – Each page has a template, which handles governs the styles and layout for that page. A template will determine what areas of the page are editable, how many columns it has and how the navigation will work. A website will usually have multiple templates (i.e. Home Page and Subpage) which provide different layout choices for users when they create new pages.
-
Users and Groups – Security is handled via users and groups. A user might represent a ‘public’ user, who can access some sections of your website (like a ‘Members only section’). Or they might be a ‘CMS’ user who has the ability to make changes to the content via the CMS editing tools. Each user can be part of multiple groups, which define what they can do, including editing pages, viewing content or publishing new pages.
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.
In Context Editing
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.
Containers
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.
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).
Making changes
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.
Publishing pages
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.
Adding a new page
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.
Adding new text content to a page
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.
Adding images and files to pages
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.
Uploading files
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.
Placing an image
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 link to a file
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.
Navigating to find pages
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.
Using the Sitemap to find pages
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 Gotchas
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.
Understanding how dynamic navigation works
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.
Moving pages/sections in the sitemap
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.
Creating the groups
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.
Adding users
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)
Restricting the sections
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: * Rights – Who can edit and who can publish? * Tasking – Who the work is assigned to? * Notification – How do people know they have new content to look at.
This section covers how to create a simple workflow, that covers two kinds of groups of people. * Contributors: These people should be able to edit pages and content, but should not be able to publish them. * Publishers: These people should be able to edit pages/content, and can publish them.
Basic Contributor and Editor workflow
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.
Bulk publishing
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’.
Tasks
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.
Adding content via the Content Library
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.