First-Time Users

To a user, every new piece of software is not exactly an adventure nor a joy to use. There is a lot of apprehension surrounding anything new. What sort of things should I expect to see as a brand new user? Will it be intuitive? In many cases, there are many missteps and trials before something successful happens.

Barebones CMS has been rigorously tested to find all the key areas where users get stuck after installation. The people who participated in this test had zero documentation to go on and were rightfully frustrated when they encountered each problem. This portion of the Barebones CMS documentation is designed based on the results of the beta testing group so you quickly get up and running after completing the installation procedure.

Designing Your First Page

Upon logging into Barebones CMS for the very first time after installing, you are presented with a completely blank page with one minor exception: The upper-right hand corner has a link entitled 'Edit'.

"Easy Edit" appears in the upper-right.
"Easy Edit" appears in the upper-right.

This is known as "Easy Edit". Easy Edit allows you to quickly enter the administration and editing interface for a page. Clicking the "Edit" link brings you into the main interface.

The Main Interface

The main interface is divided into three distinct sections: An options menu on the left, a preview pane on the right, and various dialogs and editing interfaces above (normally hidden until needed).

Menu on the left, preview and dialogs on the right.
Menu on the left, preview and dialogs on the right.

You will spend approximately 95% of your time in the right-hand side of the interface. The menu on the left is for functionality that doesn't fit naturally anywhere else. You can create all the content for a page without using any of the menu options.

This leaves us with just two options on the right for a brand new page. The "Live Page" link is essentially a "Back" button. The remaining option is inside the preview pane and is a link labeled "Add Widget". You should focus on learning how to use the Widget interface first.

Using Widgets

Barebones CMS is designed around the concept that everything on the page is a widget. Your wireframe layout is a widget. Your content is a widget. Even your header and footer can be widgets.

Click to watch this screencast.
A screencast of how to add a Code widget and execute PHP code on a webpage.

Every page starts with a "Root/Page" Master Widget. Master Widgets contain widgets and also manage the order in which widgets appear. Widgets can contain anything - including Master Widgets. Therefore, it is possible to build any website using the Widget infrastructure in Barebones CMS.

There are three widgets included with the core Barebones CMS product: Code, Layout, Content. With these three pre-built widgets, you can successfully design any website. This website was designed in the Barebones CMS in a mere four hours (writing the documentation took a few weeks though).

Adding a 'Code' widget to the page.
Adding a 'Code' widget to the page.

Clicking "Add Widget" on the "Root/Page" Master Widget brings up your first dialog. Dialogs are embedded into the browser at the top of the page and, when the page becomes long enough, the browser will jump to the dialog. Pressing 'Esc' (Escape) on the keyboard or clicking the 'X' in the upper right corner of the dialog will close it and attempt to jump back to the position you were at on the page before the dialog appeared.

Next, select the 'Code' widget from the 'Widget' dropdown and give it a short but reasonably meaningful name in the 'Display Name' field. Click "Add". The preview area will update to show the new widget. If you visit the "Live Page", you won't see anything different but that is because nothing has been done yet beyond just adding the widget.

Each widget offers different options. The 'Code' widget, for instance, offers 'Edit Head', 'Edit Body', and 'Edit Action' options. Widgets can also be detached from one Master Widget and then optionally attached to another or just kept in the list of orphaned widgets for any reason you might have (little to no performance penalty).

Clicking 'Edit Body' displays the syntax highlighting code editor.
Clicking 'Edit Body' displays the syntax highlighting code editor.

Click 'Edit Body' and a new editor appears. This is an embedded browser-based syntax highlighting editor (ACE/Ajax.org Cloud9 Editor is displayed in newer web browsers, EditArea is displayed in older browsers). Copy the code below into the editor:

<?php
	echo 1 + 2;
?>

PHP code executing within the Code widget.
PHP code executing within the Code widget.

Click the 'Save' button in the editor and the preview area will update and you should see the number '3' appear (1 + 2 = 3). You have just successfully executed your first bit of PHP code within Barebones CMS using the Code widget. The Code widget is very useful for creating custom functionality on a page. If you are used to hand-coding your websites, the Code widget allows you to still hand-code sites while leveraging the caching system, the multilingual translation system, the revision system, and the file explorer without any extra effort.

The included widgets are very powerful and together can accomplish any task. The Code widget should really be a last resort solution to a problem. Many problems can be solved with the other two widgets - Layout and Content.

Detach the Code widget so you can start playing with the Layout widget.

Creating Layouts

There are two types of layout in web design: Wireframe layout and Content layout. Content layout involves things such as margins, padding, images, etc. around content. Wireframe layout keeps content layout contained to certain areas of the page. An example of a wireframe is a three-column layout. Wireframes are the hardest to get right across all browsers and is the primary source of web developer headaches - specifically, when developers are complaining about Internet Explorer and its "broken box model", they are inevitably talking about wireframes. There are various "solutions" out there that are still broken. However...

The Layout widget is the answer to web designer wireframe woes. Contained within the Layout widget are 13 pre-made Holy Grail layouts that cover all common wireframe layouts. These Holy Grail layouts all have no CSS hacks, are SEO friendly, all columns are the same length, no images, no Javascript, are fluid (but can be made fixed-width easily), no quirks mode, no IE conditional comments/hacks, are valid XHTML strict, take only minutes to integrate, and work in every browser, including the dreaded Internet Explorer. With these wireframe layouts, it is literally impossible to create content that causes a div to be too wide thus causing it to get pushed down the page in some broken way.

Click to watch this screencast.
A screencast of how to add a Layout widget and create a standard layout with widgets.

How do you get one of these miraculous wireframes on a page in Barebones CMS? Simple:

  1. Add a 'Layout' widget.
  2. 'Configure' the widget.
  3. Select 'New Layout'.
  4. Select the desired layout from the dropdown. Give it a name. Click 'Create'.
  5. Click 'Activate'.

The page may now appear a bit messy. A new Layout widget layout usually adds multiple Master Widgets to the page so widgets can be placed into each individual column and the header and footer. Click 'Edit HTML' and 'Edit CSS' to bring up the browser-based syntax highlighting editor to make changes to the layout as you see fit.

A lot of modern designs usually have some sort of custom layout (header, content placeholder, and footer) and then embed a two or three column wireframe inside that. For custom designs that don't fit a standard model for the outermost wireframe, there is the 'Blank Slate' layout. But keep in mind that it is easy to put Layout widgets inside Layout widgets to create complex wireframes (e.g. a three column layout inside a two column layout).

The Layout widget also supports cache profiles. A cache profile can literally be anything but is commonly used for browser sniffing the incoming request and serving up cached mobile-friendly content. This is a somewhat advanced layout technique that is covered more in-depth elsewhere in the Barebones CMS documentation.

Creating Content

Once you have a layout on the page that you are happy with, it is time to start adding content. While this can be done with the Code widget, the Content widget is preferred wherever possible. The Code widget is useful for when you need refined margins and padding that won't be used anywhere else. The Content widget is great for cranking out consistent content like this documentation and also allows those with the Content Editor privilege to edit the content.

Click to watch this screencast.
A screencast of how to add a Content widget and create basic content.

You should now familiar with the process of adding widgets to the page. This time though, use one of the Master Widgets inside the Layout to add a Content widget. Once added, click 'Edit' and the Content editor will appear.

The tabbed content What You Mean editor.  Basic tools and shortcodes on top, content to the left, and block-level content styling and transformations to the right.
The tabbed content What You Mean editor. Basic tools and shortcodes on top, content to the left, and block-level content styling and transformations to the right.

The Content widget is the easiest of the three widgets to use and understand. However, it may be a bit disconcerting for those expecting to get a WYSIWYG editor. WYMEditor powers the Content widget and operates on a "What You Mean" instead of a "What You See" principle. Designing content for the web is very different from designing content in a word processor. What You Mean is the correct approach for the web. WYMEditor is very fast, lightweight, and, most importantly, generates clean XHTML, which is easy to style.

Most browser-based editors are a bit buggy. The best approach is to write your text first and then apply styles to the previous paragraph after you start the next paragraph. Otherwise, you will be wrestling with whitespace issues. The same goes for hyperlinks, images, and other elements. Apply them after you have started the next paragraph.

Experiment for a bit to get some content into the editor.

Using Shortcodes

The content editor is a heavily modified WYMEditor that uses shortcodes to offer advanced functionality that fits in with the What You Mean approach of doing things. You mean to put an image here or a Google map or a video or... You get the idea. A shortcode appears as an icon on the toolbar that, upon clicking, inserts a placeholder image that represents the shortcode. Double-clicking the placeholder image opens the configuration dialog for the shortcode. This allows for a consistent approach to adding any content-based feature you desire.

Click to watch this screencast.
A screencast of how to add a Shortcode to content.

Let's add an image to the content. First, create a new paragraph (press Enter) before the first line of content where you want the image to appear and place the cursor inside. Click the 'Image' icon in the toolbar. A new placeholder appears. In the 'Classes' box on the right, click 'Wrap Shortcode'. You should always put shortcodes in their own paragraph and wrap them using 'Wrap Shortcode' so that web designers can correctly style up the content using CSS.

Shortcodes appear on the toolbar (Flash, Image, and Syntax Highlighter in this case).  Placeholder images, which represent the shortcode, should be wrapped with the 'Wrap Shortcode' class.
Shortcodes appear on the toolbar (Flash, Image, and Syntax Highlighter in this case). Placeholder images, which represent the shortcode, should be wrapped with the 'Wrap Shortcode' class.

Double-click on the new placeholder. A dialog should appear that allows you to upload/transfer an image to the server or use the URL of an image. Upload an image, enter alternate text and save the information. Be sure to also save the content too (otherwise it won't show up).

Configuring shortcode security.
Configuring shortcode security.

You may note that the preview area won't show the image. This is because shortcodes are considered a security issue. To preview images in the content editor, a developer has to relax the security restrictions. While logged in as a developer, click 'Configure Security' to configure shortcode security. Changes made to shortcode security are effective site-wide.

Once you finish getting the image to display, you may also note that classes (e.g. 'Float Right') may not "work properly". This is where a designer with Firebug or an equivalent tool looks at the DOM and creates the appropriate CSS to perform the correct content layout for the site.

Finalizing the Page

Once the page is basically complete, it is important to finalize the page by giving it a title and apply page-level tweaks for Search Engine Optimization (SEO) purposes. To do this, click on the 'Edit Properties' link in the menu on the left. A new dialog will appear. The most commonly edited options are toward the bottom - 'Page Title' and 'Meta Description'. Enter in a page title, click 'Save', and the page is finished.

What's Next?

At this point, you are probably ready to wander off and do your own thing. However, the following documentation is highly recommended reading:

Learn more about the Code Widget, Layout Widget, and Content Widget.

Learn how to create Great Layouts and Great Content.

Learn how to Create More Pages.

That should be about it. If you get stuck, don't forget about the rest of the documentation and the friendly folk over at the Barebones CMS forums!

And if you find Barebones CMS useful, please donate toward future development efforts.

© CubicleSoft