Sidebars

We recently covered the use here of two very handy features of reStructured Text (reST): namely the sidebar and figure directives. Sidebars and figures are very useful features for adding additional content styles to documents using reST, for example web diaries created using the EasyBlog product…

As demonstrated in this very article, a sidebar is an area for highlighted content which floats to the right of the actual article. The code for a sidebar in reST is as follows:

.. sidebar:: Sidebar Title
   :subtitle: Optional Sidebar Subtitle

   The sidebar content text would go here.

   .. image:: image.jpg (an optional image)

Those who would like their sidebars to float to the left or middle are out of luck—it’s to the right only for reasons of taste and aesthetics.

And for those interested in such things, the sidebar directive makes use of the following CSS:

.documentContent .sidebar {
       float: right;
       margin: 0 0 10px 20px;
       padding: 15px;
       width: 250px;
       border: &dtml-borderWidth; &dtml-borderStyle; &dtml-globalBorderColor;;
       overflow: hidden;
       }

.documentContent p.sidebar-title {
       font: normal 150%/150% <dtml-var headingFontFamily> !important;;
       background-color: &dtml-globalBackgroundColor;;
       padding: 4px 15px 2px 15px;
       margin: -15px -15px 10px -15px;
       border-bottom: <dtml-var globalBorderColor> solid 1px;
       }

p.sidebar-subtitle {
       font: normal 110%/110% <dtml-var fontFamily> !important;;
       padding: 0;
       margin: 0 0 4px 0;
       }

.documentContent .sidebar img {
       border: none !important;;
       }

#vs-scheme1 .documentContent p.sidebar-title, #vs-scheme1 .documentContent p.sidebar-subtitle {
       color: &dtml-vsScheme1;;
       }

#vs-scheme2 .documentContent p.sidebar-title, #vs-scheme2 .documentContent p.sidebar-subtitle {
       color: &dtml-vsScheme2;;
       }

#vs-scheme3 .documentContent p.sidebar-title, #vs-scheme3 .documentContent p.sidebar-subtitle {
       color: &dtml-vsScheme3;;
       }

#vs-scheme4 .documentContent p.sidebar-title, #vs-scheme4 .documentContent p.sidebar-subtitle {
       color: &dtml-vsScheme4;;
       }

#vs-scheme5 .documentContent p.sidebar-title, #vs-scheme5 .documentContent p.sidebar-subtitle {
       color: &dtml-vsScheme5;;
       }

#vs-scheme6 .documentContent p.sidebar-title, #vs-scheme6 .documentContent p.sidebar-subtitle {
       color: &dtml-vsScheme6;;
       }

#vs-scheme7 .documentContent p.sidebar-title, #vs-scheme7 .documentContent p.sidebar-subtitle {
       color: &dtml-vsScheme7;;
       }

Close observers of the above will note there are several optional dtml calls in this CSS. The dtml in this particular example is designed to work in conjunction with the vsCore product default stylesheet, alongside ploneDefault base_properties.doc, both of which we have modified to create customisable portal_tab colours. The dtml above acquires the colour values of the portal_tab active in a particular location, changing the sidebar title and subtitle colour to match. The sidebar would of course work equally well with a single "hard-wired" title and subtitle colour value for an entire site.

Figure floats

Floated to the left.

CSS styles have also been created to combine image float styles with the figure directive. There are now three CSS classes which can be applied to the figure directive: float-right, float-left, and float-centre, and what they do should be fairly self-evident—floating an image to the right, left and centre respectively. Keen observers of CSS will point out that there is no such thing as a float-centre command, which is quite correct, but in this case it seemed more consistent to name the class "float-centre" for the sake of users.

Floated to the right.

While the reST figure directive has always allowed a caption to be added along with an image, with a little additional CSS trickery the captions here have not only been styled with a little font-sizing and colour, but have also been positioned in a more aesthetically pleasing way at the bottom left corner of the images, without using the depracated align="left" html tag, which is the default method in reST.

Floated to the centre.

The reST code for these styles is as follows:

.. figure:: image.jpg
   :alt: float-left
   :figclass: float-left

   An image floated to the left.

.. figure:: image.jpg
   :alt: float-right
   :figclass: float-right

   An image floated to the right

.. figure:: image.jpg
   :alt: float-centre
   :figclass: float-centre

   An image floated to the centre

And the CSS employed is as follows:

.float-right {
     position: relative;
     float: right;
     text-align: left;
     border: &dtml-borderWidth; &dtml-borderStyle; &dtml-globalBorderColor;;
     margin: 0 0 23px 20px;
     padding: 0;
     clear: right;
     }

.float-left {
     position: relative;
     float: left;
     text-align: left;
     border: &dtml-borderWidth; &dtml-borderStyle; &dtml-globalBorderColor;;
     margin: 0 20px 23px 0;
     padding: 0;
     clear: left;
     }

.float-centre {
     position: relative;
     text-align: center;
     border: none;
     margin: 0 0 23px 0;
     padding: 0;
     clear: both;
     }

.documentContent .float-right p.caption, .documentContent .float-left p.caption {
     margin: 0 0 -18px 0;
     padding: 3px 0 0 0;
     bottom: 0;
     left: 0;
     font: normal 11px/13px Arial, Helvetica, sans-serif !important;;
     color: #000;
     }

.documentContent .float-centre p.caption {
     margin: 3px 0 0 0;
     padding: 0;
     font: normal 11px/13px Arial, Helvetica, sans-serif !important;;
     color: #000;
     }

Note that a small amount of dtml is again used to style the images with the border colour, width and style, as defined in the site base_properties doc—thereby matching the border around your floated images with the style of your portlets etc. Of course it may be more appropriate in some cases to hardwire this value.

Also of note is the fact that the floated-centre image doesn’t have a border, for the reason that without a fixed width defined the image container is via the block properties of CSS defaulting to 100% width, giving you a border that expands to the full width of your content column no matter the size of the image. Should there be a way to get the border to match the size of the image (the CSS attributes display, width and margin: auto were of no avail) the class will be updated to have a border.

We’ve written lofty paeans in praise of reStructured Text without bothering to tell people how to select it; we’ve now updated our Changing your Content Editor page to do the needful…

BTW, the excellent reStructured Text primer is a bit scarce on adding links; we’ve also updated the adding links page too…

Those who are not familiar restructured text may initially bemoan it’s lack of power and flexibility when compared to XHTML, but as often the case in life, initial appearances can be deceiving.

Although the use of CSS for styling and presentation is "best practice" in XHTML, it is not yet mandatory, which allows anyone with knowledge of such "deprecated" tags as "align=center" or "font", to illegally wreck havoc with your beautiful CMS-based site.

Outside of a mandatory 2 month course in basic XHTML and CSS, one solution which desperate webmasters have often deployed is to force site editors and contributors to work with WYSIWYG editors configured to strip out any and all illegal tags. Not only is this a somewhat draconian solution, and immensely frustrating from a user point of view, but it still doesn’t bring your site any closer to being beautifully or correctly formatted. Just not illegally so.

And don’t get me started on tables…

Restructured text on the other hand forces compliance to XHTML best practise precisely because it is not XHTML. By allowing users to work in an environment much closer to the simple text notepad which almost everybody is familiar with, and without a single (more often than not forgotten) tag in sight, the simplicity of ReST leaves the site contributor the concentrate on content, as God would have intended it, and takes care of the parsing of said content into strict XHTML for them.

But that’s not all. Presentation is still possible via CSS—also as God intends it—yet much to the relief of the site designer and webmaster—outside of the control of a user whose obsession with "beautifying" one little plant can be to the detriment of the wellbeing of the entire garden.

And not just the presentation of your basic paragraph and heading tags, but, watching closely, the ReST figure directive, which in combination with a little CSS jiggery-pokery detailed below is capable of deploying some quite remarkable effects.

The Polaroid Effect

Through deployment solely of the class "float-right-360" to the figure directive below, it is possible to add a polaroid effect to a photograph in the following manner:

As reStructuredText:

.. figure:: /images/the_moon.jpg
   :alt: the moon
   :figclass: float-right-360

    The moon during a lunar-eclipse. Pretty!

To produce the following image and caption:

The moon during a lunar-eclipse. Pretty!

Which is achieved with the following css:

.float-right-360 {
       position: relative;
       float: right;
       text-align: left;
       background-image: url(polaroid_360_270.png);
       background-repeat: no-repeat;
       margin: 10px 0 10px 20px;
       padding: 1px 8px 8px 1px;
       border: none;
       }

.float-right-360 img {
       border: #fff 7px solid;
       border-bottom: #fff 36px solid;
       width: 247px;
       height: 308px;
       }

.float-right-360 p.caption {
       position: absolute;
       font: normal 11px/13px Arial, Helvetica, sans-serif !important;;
       color: #000;
       margin: 0;
       padding: 0 10px 0 0;
       top: 321px;
       left: 10px;
       }

Note there is one limitation to this effect—the image used must be exactly 308px H by 247px W, because there simply aren’t enough "hooks" inside the figure directive to deploy the necessary number of background images to allow scaling.

As a work around to this limitation, one could create a variety of classes for pre-determined image sizes and orientations, which would also have the added benefit of forcing your users to stick to creating images in sizes complimentary to the overall site design.

Which raises another sore point about CMS’s which don’t employ image-sizing engines—but that would be another topic…

One problem with changing from HTML (or a content editor) to reStructured Text in Plone is that the text editor doesnt convert your old HTML docs to reStructured Text.

However, my experience so far is that if you copy the text of the page (not the code), click on the edit tab, delete the HTML code and paste the content of the page back in, it does a pretty good job of keeping the layout of the page. Paragraphs, bullet points and numbered lists are largely mantained. Of course, links images and preformatted text all have to be put back, but what can you do…