Customising the Drupal theme Newswire for ProsePoint

  • strict warning: Non-static method view::load() should not be called statically in /home/prosepoint.org/bzr/public_html/profiles/prosepoint/modules/views/views.module on line 879.
  • strict warning: Declaration of views_handler_argument::init() should be compatible with views_handler::init(&$view, $options) in /home/prosepoint.org/bzr/public_html/profiles/prosepoint/modules/views/handlers/views_handler_argument.inc on line 0.
  • strict warning: Declaration of views_handler_filter::options_validate() should be compatible with views_handler::options_validate($form, &$form_state) in /home/prosepoint.org/bzr/public_html/profiles/prosepoint/modules/views/handlers/views_handler_filter.inc on line 0.
  • strict warning: Declaration of views_handler_filter::options_submit() should be compatible with views_handler::options_submit($form, &$form_state) in /home/prosepoint.org/bzr/public_html/profiles/prosepoint/modules/views/handlers/views_handler_filter.inc on line 0.
  • strict warning: Declaration of views_handler_filter_node_status::operator_form() should be compatible with views_handler_filter::operator_form(&$form, &$form_state) in /home/prosepoint.org/bzr/public_html/profiles/prosepoint/modules/views/modules/node/views_handler_filter_node_status.inc on line 0.
  • strict warning: Non-static method view::load() should not be called statically in /home/prosepoint.org/bzr/public_html/profiles/prosepoint/modules/views/views.module on line 879.
  • strict warning: Declaration of views_handler_filter_boolean_operator::value_validate() should be compatible with views_handler_filter::value_validate($form, &$form_state) in /home/prosepoint.org/bzr/public_html/profiles/prosepoint/modules/views/handlers/views_handler_filter_boolean_operator.inc on line 0.
  • strict warning: Declaration of date_api_filter_handler::value_validate() should be compatible with views_handler_filter::value_validate($form, &$form_state) in /home/prosepoint.org/bzr/public_html/profiles/prosepoint/modules/date/includes/date_api_filter_handler.inc on line 0.
  • strict warning: Non-static method view::load() should not be called statically in /home/prosepoint.org/bzr/public_html/profiles/prosepoint/modules/views/views.module on line 879.
  • strict warning: Declaration of views_plugin_row::options_validate() should be compatible with views_plugin::options_validate(&$form, &$form_state) in /home/prosepoint.org/bzr/public_html/profiles/prosepoint/modules/views/plugins/views_plugin_row.inc on line 0.
  • strict warning: Declaration of views_plugin_row::options_submit() should be compatible with views_plugin::options_submit(&$form, &$form_state) in /home/prosepoint.org/bzr/public_html/profiles/prosepoint/modules/views/plugins/views_plugin_row.inc on line 0.
A themeing case study

Following on from our previous article about customising the ProsePoint default theme, we have customised another generic Drupal theme for ProsePoint. With this article, we're now going to:

  • Release a ProsePoint version of the Drupal theme Newswire, and
  • Provide a case study example about the ProsePoint-specific customisations involved.

Download the theme

You can download the ProsePoint version of the Drupal theme Newswire. Uncompress it, and place it in your .../sites/all/themes or .../sites/default/themes directory, then enable it from Administer // Site building // Themes.

The package actually contains two themes: the base Drupal Newswire theme (so there's no need to get that separately), and a ProsePoint version of the theme. It's the latter one you want to eanble.

Please note this theme needs to be used with ProsePoint 0.09 or later.

If you just want to use the theme, you can skip reading the rest of this article below.

Newswire

For this exercise, we chose to customise the Drupal theme Newswire by Adaptive Themes. From reading other people's postings on drupal.org and elsewhere, Newswire seems to attract a fair amount of attention from users looking for a newspaper-style theme, so we decided it was an appropriate and practical choice. We won't go into the layout and features of the theme here. If you want to know, we'll refer you to the Newswire Drupal project page.

ProsePoint themes are Drupal themes

Firstly, let it be stated that ProsePoint themes are Drupal themes, albeit with a few extra customisations. Everything that applies to Drupal themeing also applies to ProsePoint themeing. Furthermore, you can use a Drupal theme with ProsePoint. You just won't have any ProsePoint-specific themeing. If you're okay with that, then that's fine.

Subthemeing Newswire

Instead of directly modifying the Newswire theme, we chose to subtheme it and customise the subtheme instead. This has a number of advantages, but the most important one is that we only need to implement the changes that we want. This makes things easier to track, and if a new version of Newswire is released, our subtheme would automatically inherit the improvements.

Of course, if we create a subtheme, we need to give it a different name. For the purposes of this article, we'll call it PP Newswire and the code prefix will be pp_newswire.

Creating the subtheme

To create the subtheme, we made a new directory pp_newswire and created a theme info file pp_newswire.info. A theme info file contains a list of declarations about the properties of the theme. In our case, we can inherit many of these properties from the parent theme so we don't have to mention them. There are two important lines for us to know about:

base theme = newswire

This line tells ProsePoint what is the parent (or base) theme.

stylesheets[all][]   = pp_newswire.css

This line tell ProsePoint to include the CSS stylesheet pp_newswire.css, which will occur after all the stylesheets of the parent theme. This allows pp_newswire.css to override the stylesheets of Newswire.

ProsePoint customisations

We have tried to keep the number of ProsePoint-specific themeing customisations to a minimum, and really, there's only one that might have a noticeable impact on usability. The other customisations are purely cosmetic and very much optional. We'll cover them in order of importance.

Visual editor (TinyMCE) wysiwyg themeing

A ProsePoint theme should theme the visual editor (TinyMCE) so it is as wysiwyg as possible. We really believe it is important to mainstream end users that what they type in the editor is very close to the final output. Note we said "very close". We realise it's not technically feasible to be 100% wysiwyg, but we also know 95% wysiwyg is quite achievable, and we would like all ProsePoint themes to do this.

To theme the visual editor, the PP Newswire's template.php file implements a function pp_newswire_tinymce_content_css() to return the location of a CSS file that styles the content area of the visual editor. For PP Newswire, this file is pp_newswire/tinymce_content.css.

In template.php, we put:

function pp_newswire_tinymce_content_css()
{
  return path_to_theme() . '/tinymce_content.css';
}

The file tinymce_content.css informs the visual editor how to make its contents look like the final output. Depending on the parent theme, it can be quite a chore extracting these styles out and reproducing them in tinymce_content.css. We were fortunate with PP Newswire because it is a well structured theme - all of the relevant styles were kept in either reset.css or style.css.

To create tinymce_content.css, we first copied the entire contents of pp_newswire/reset.css into it. Then we appended the entire contents of pp_newswire/style.css. That gave us a tinymce_content.css which was almost sufficient.

Comparing the editor contents with final output, we discovered that the styling for h2 elements wasn't quite wysiwyg (Note: The demo install of ProsePoint 0.09 has a convenient About page which contains sample html elements). It turns out Newswire has the following CSS style:

div.node h2 {
  font: bold 1.447em Georgia, "Times New Roman", Times, serif;
  margin-bottom: 0;
}

which applies to h2 elements in the final output, but obviously doesn't apply to h2 elements in the editor because there is no div.node wrapper. So, we manually appended the following style to tinymce.css:

h2 {
  font: bold 1.447em Georgia, "Times New Roman", Times, serif;
  margin-bottom: 0;
}

It's exactly the same styling, but now it applies to the editor contents, making the h2 element wysiwyg.

This step resulted in a tinymce_content.css file with all the relevant styling from the Newswire theme.

Next, we needed to add ProsePoint specific CSS styling in order to make images and media float in the editor. This was also relatively straightforward. We simple copied the styling from the relevant parts of the file tinymce_content.css of the default tma2 theme and appended to our tinymce_content.css (As of ProsePoint 0.09, these were the last 8 CSS declarations of .../profiles/prosepoint/themes/tma2/tinymce_content.css).

Comparing the editor contents with final output, it looked like everything was in place ... Done!

Well, almost. There is one discrepancy, and that's due in part to a feature of the Newswire theme. This theme comes in three colour schemes, and depending on the colour scheme, the shading of striped table rows differs. Our subtheme PP Newswire also inherits this feature. With tinymce_content.css as it stands, it only supports the default colour scheme. In other words, if you change the colour scheme of PP Newswire, the shading of striped table rows changes in the final output, but it doesn't change in the visual editor.

One way to fix this would be to create three versions of tinymce_content.css, and depending on the selected colour scheme, the function pp_newswire_tinymce_content_css() would pass the appropriate one to the visual editor.

We're going to cheat here, and leave this as a homework exercise for the reader :)

Other than that, the file tinymce_content.css was complete, and together with the function pp_newswire_tinymce_content_css() in template.php, the visual editor was now wysiwyg (or close enough).

One final caveat: Making the editor wysiwyg only makes sense in the case of node output. For example, if the visual editor is used to edit a custom block instead of a node, then it may not necessarily be wysiwyg because block styling is usually different from node styling.

Teaser image themeing

The next themeing customisation relates to teaser images. When a story is viewed as a teaser, The ProsePoint Editor module extracts one image (if present) out of the story text and places it in a separate node content variable so the theme can do whatever it desires with it.

For the default ProsePoint theme tma2, the teaser image is placed before the node title and floated to the left. This is what allows the image to appear beside the title instead of below it (which is how generic Drupal themes would show it).

To theme this same effect for PP Newswire, we have to override the node template. Specifically, we wanted to create an explicit template for story teaser nodes customised for our purposes.

Firstly, we added the following code to template.php:

function pp_newswire_preprocess_node(&$variables, $hook) {
  $node = $variables['node'];

  // Add a node-type-teaser suggestion
  if ($node->teaser) {
    $variables['template_files'][] = 'node-'. $variables['node']->type . '-teaser';
  }

  // If there is an extracted teaser image, do some processing
  if (isset($node->teaser_pp_img)) {
    $variables['teaser_pp_img'] = $node->content['teaser_pp_img']['#value'];
    $variables['body_content'] = $node->content['body']['#value'];
  } 
}

This function does two things. The first stanza instructs ProsePoint to use a template file node-story-teaser.tpl.php for story teasers (if such a template file exists and can be found). Actually, this template override rule applies to all content types, not just stories, but let's stay on topic. The second stanza just copies a couple of strings containing rendered html into variables for convenience later.

Next, in order for our subtheme to override the node template of the parent theme, we copied node.tpl.php from Newswire into PP Newswire's directory and modified it to suit our purposes. We changed line 26:

  <?php print $content; ?>

to

  <div class="content clear-block">
    <?php print $content; ?>
  </div>

In other words, we added a <div> wrapper. And then we changed line 31:

    <div class="tags"><?php print $terms; ?></div>

to

    <div class="tags taxonomy"><?php print $terms; ?></div>

In other words, we added an extra class taxonomy. These two changes to node.tpl.php aren't actually related to teaser images, but they were useful for other general purposes.

Next, we copied node.tpl.php into a file node-story-teaser.tpl.php and modified it to suit our purposes. We added:

  <?php if ($teaser_pp_img): ?>
    <div class="teaser-image">
      <?php print $teaser_pp_img; ?>
    </div>
  <?php endif; ?>

at line 2 near the top of the file. This displays the teaser image before the node title.

Then, we replaced line (approximately) 26:

  <div class="content clear-block">
    <?php print $content; ?>
  </div>

with

  <div class="content">
    <?php if ($field_subtitle_rendered): ?>
      <?php print $field_subtitle_rendered; ?>
    <?php endif; ?>

    <?php if ($field_source_rendered): ?>
      <?php print $field_source_rendered; ?>
    <?php endif; ?>

    <?php if ($field_date_rendered): ?>
      <?php print $field_date_rendered; ?>
    <?php endif; ?>

    <?php if ($body_content): ?>
      <?php print $body_content; ?>
    <?php endif; ?>
  </div>

(Please note that $teaser_pp_img and $body_content were assigned from template.php as explained previously.)

This instructs the theme not to print out the entire node contents, but to print just the subtitle, source, date and body fields. The reason for this is because $content contains all the node content fields including the teaser image. If we printed out $content, we'd have the teaser image appearing a second time.

CCK field themeing

The last set of customisations was themeing for CCK fields and is very much optional.

For story nodes, we wanted to turn off labels for the Subtitle, Source, and Date fields. (Actually, the more correct way to do this is through the display settings for the story content type rather than through the theme. However, we did it through the theme so users wouldn't have to configure any further settings)

For edition nodes, we wanted to change the output of the Headlines and Other stories fields for editions. These two fields are CCK fields, and by default, display node titles without any formatting. We decided to list story titles within a <ul> list instead.

In template.php, we added the following function:

function pp_newswire_preprocess_content_field(&$variables) {
  // Some customisations for story content type
  // Turn off some field labels for story
  if ($variables['node']->type == 'story' && in_array($variables['field_name'], array('field_subtitle', 'field_source', 'field_date'))) {
    $variables['label_display'] = 'hidden';
  }

  // CCK field items default to using <div>
  $variables['field_list_start_tag'] = '';
  $variables['field_list_end_tag'] = '';
  $variables['field_list_item_tag'] = 'div';

  // For some cases, change this to <ul> and <li>
  if (($variables['field_name'] == 'field_headlines' && $variables['teaser']) ||
      ($variables['field_name'] == 'field_stories')) {
    $variables['field_list_start_tag'] = '<ul>';
    $variables['field_list_end_tag'] = '</ul>';
    $variables['field_list_item_tag'] = 'li';
  }
}

The first stanza turns off the previously mentioned field labels for story nodes. The second and third stanzas calculate what tags to use for the subsequent field template file.

Next, we want to override the default themeing for CCK fields. To do this, we copied the file content-field.tpl.php from the CCK module (.../profiles/prosepoint/modules/cck/theme/content-field.tpl.php) and modified it to use our previously defined tag strings. Please look in the file in the PP Newswire theme your for all the gory detail.

Other changes

In addition to the ProsePoint specific customisations, we also made a small number of other changes:

  • We added some general CSS style overrides to pp_newswire.css.
  • We changed the RSS feed icon in the first menu bar so it isn't hardcoded to rss.xml, but instead changes depending on what page the user is viewing.
  • We fixed up a small IE layout bug for the channel RSS icon when viewing channel pages (Newswire uses the more general word Category instead of channel).

Conclusion

This case study describes the customisations made to the Drupal theme Newswire for better integration with ProsePoint. There is just one customisation that may have a noticeable impact on usability, and that is the wysiwyg themeing of the visual editor. The others changes are cosmetic and optional. Overall, they are not many nor major. This is expected, because ProsePoint themes are really just Drupal themes with a few extras.

Thank you for reading.

Comments

NewsWire Theme

Thanks for posting this thorough analysis of theming NewsWire for ProsePoint. I like the theme, and may try it. If so, I will comment on how it turns out. Thanks. Michele