The Content Widget

The First-Time Users documentation briefly covered the Content widget in the Barebones CMS. This documentation covers everything about the Content widget that you will likely ever need to know.

Overview

The Content widget is the most complex widget of the default widgets in the Barebones CMS in terms of code complexity. The main purpose of the Content widget is to give content editors the ability to edit content on the page easily while maintaining clean XHTML output from the system.

The Content widget editor for the content on this page.
The Content widget editor for the content on this page.

The Content widget has a dialog to manage shortcode security options and the main editor. The Content widget makes extensive use of the Content Editor.

Features

The Content widget offers a number of features:

The Content widget is ideal for static content on a page. Static content is where the generated XHTML does not change and output can't be changed by another page. Images, videos, maps, etc. are all typically static content. Things that are considered truly dynamic content are rare and usually involve the Code widget.

Usage

Basic usage of the Content widget was covered in the First-Time Users documentation. The Content widget is carefully designed around both how web browsers and how web designers desire output - clean XHTML. As such, a "What You Mean" approach is used for creating content instead of a "What You See" approach. This may be slightly disconcerting to content editors expecting a word processor/WYSIWYG editor. However, this approach actually ends up being less frustrating in the end.

The basic editor is intentionally simple. Additional functionality can be accomplished two different ways - Classes and Shortcodes. The list of Classes, found to the right of the editor, is located at 'support/css/wymeditor.css'. Adding a new rule is fairly easy to do and should be kept to just applying a class to a tag (e.g. '<p class="myclass">') so that CSS styles can be applied via a Layout widget layout's CSS. Simply applying a new class to an existing tag will be sufficient for many needs. Shortcodes should be preferred for handling more complex problems.

Adding a new Shortcode is easy to do if it already exists. Download the desired, vetted Shortcode, extract the ZIP file locally, and then upload the files to the correct locations. Then reload the editor. Note that each Shortcode is loaded per page regardless of whether or not it is actually used. Shortcodes, therefore, should only be added on an as-needed basis. Only obtain Shortcodes from the Barebones CMS website. Each programmer here writing Shortcodes is vetted prior to letting them distribute Shortcodes and Widgets through the site.

If the Shortcode you want does not exist, you can ask on the forums or learn how to create a Shortcode and write it yourself.

For details on each toolbar icon, container, and class, read the documentation on Using the Content Widget.

The Content widget is cache profile aware and allows cache profiles to alter the output content. Cache profiles are alternate views of the same content depending on how the web request to the server is made. The most common use of cache profiles is to create alternate content views for desktops, mobile phones, and tablets. See the Creating Cache Profiles documentation to learn about the supported Content widget hooks.

Known Quirks/Bugs

There are a few known issues with the Content widget to take note of:

Microsoft Word Styles Removed

This is intentional. Copying and pasting from Microsoft Word into the content editor may initially copy styles depending on your web browser. However, saving the content runs the content through a number of steps to output clean XHTML, which strips out anything that isn't valid for the Content widget editor. Microsoft Word styles are simply removed.

Keep in mind that you are designing content for the web, not print. The two mediums are vastly different. The Content widget is built around designing content for the web. If you feel the need to write your content in Microsoft Word, do so, but use the "Paste from Word" toolbar button and then immediately save your content, close the editor tab, and then click 'Edit' again in the Content widget. Then go back and clean up the content applying styles as-needed.

This approach will keep you from pulling your hair out and also keep the output consistent. Consistent output make web designers very happy. Happy web designers do nice things for you.

Keyboard Shortcuts

The Content widget has a distinct lack of keyboard shortcuts that perform various operations. This is partly an issue with WYMEditor, the underlying editor. A lot of work has gone into this editor to make it functional with Barebones CMS but there are limitations.

The primary keyboard shortcut that is missing is the ability to close the current editor tab. Currently, the content author has to scroll to the top of the content, click the close button, then go do whatever else needs to be done. With really long content, this can be rather annoying.

Ideally, every bit of functionality will have a keyboard shortcut. However, Design Mode - how web browsers allow for content editors - is implemented differently in every browser and typically interferes with shortcuts. So adding keyboard shortcuts to some editor features may be impossible.

Switching 'Containers'

Applying a container (e.g. "Heading 1") and one ore more classes to the current paragraph and then pressing 'Enter' to start a new paragraph copies the current paragraph's container and classes to the next paragraph. This is usually not the desired behavior and results in a lot of extra work to remove odd whitespace and other issues that crop up as a result.

The recommended approach to entering content is to start the next paragraph and apply containers and classes to the previous paragraph as you go along. Problems are few and far between with this approach.

'Wrap Shortcode' Grayed Out

When inserting a Shortcode, the paragraph that the Shortcode occupies should have the 'Wrap Shortcode' class applied. However, for some strange reason, the 'Wrap Shortcode' option in the 'Classes' list remains grayed out even though clicking it correctly applies the class.

Getting the class to not be grayed out involves moving the editor's keyboard caret (the thing that blinks) around for a while. It really is not worth the effort. Just use the class and be done with it.

Double Paragraph Skipping

In very rare circumstances, usually involving lots of copying and pasting within the editor, the editor can enter a state where the cursor can't enter a specific paragraph and jumps between every other paragraph. When this happens, save your work, close the editor tab, and then click 'Edit' again in the Content widget.

Saving the content will run the content through the XHTML filter on the server and clean up whatever was causing the problem.

Copied Relative Hyperlinks

Copying text that contains a relative hyperlink from WYMEditor to another location in WYMEditor causes the hyperlink to suddenly gains a '../../../../' prefix. I have no idea what causes this but it is a known bug in WYMEditor and a rather irritating one at that. Absolute URLs that include the 'http://' are not affected.

© CubicleSoft