Modx & blogging part 6: More on integrating templates


Modx, Articles, Styling

This time we'll complete the transformation of the Articles summary page.

I really like the power and flexibility of Modx. I especially like that you get all this for free. But with the zero cost, power and flexibility there are the inevitable downsides: poor and incomplete documentation leading to difficulty for all but the most advanced users to work out what the hell is going on at times.

This is one of the main reasons I am writing this series of posts. As I figure out through much trial and error how to do the things I want to do to build my Modx blogging site, I am capturing what I am learning and hopefully making it a little bit easier for others that are equally frustrated.

As previously mentioned, I am new to Modx (this blog is only the second site I have built, and the first using Revo). And at times it has been a real struggle to work out what to do. The first thing we are tackling in this post is a prime example of this: how to style SimpleSearch.

It should have been a trivial exercise but it was not. The wiki documentation was not only unclear but the code for the SimpleSearchForm template was simply wrong. Fortunately I eventually found a Forum post that I was able to deconstruct to get the correct template code and to use to figure out the steps involved.

UPDATE: I've subsequently discovered that there were many, many errors with the wiki documentation during a transition to a new platform. Thankfully, it appears that these errors have now been fixed (as at Dec '13).

So enough ranting and let's get to work...

Styling SimpleSearch

The templates that come with the SimpleSearch add-in are 'hidden'. I'm not exactly sure why or what this means, but in order to change the default style of the search form, you need access to it. This in turn means that you need to create a new version of the template so it can be modified. If this is documented anywhere I was unable to find it. What is documented is wrong. I did find the original template code in the filesystem at ../core/components/simplesearch/elements/chunks/ folder. Given how confused I was by the documentation I thought it best to go straight to the horse's mouth. This is the code in the chunk:

<form class="sisea-search-form" action="[[~[[+landing]]]]" method="[[+method]]">
    <label for="[[+searchIndex]]">[[ &namespace=`sisea` &topic=`default`]]</label>
    <input type="text" name="[[+searchIndex]]" id="[[+searchIndex]]"  value="[[+searchValue]]" />
    <input type="hidden" name="id" value="[[+landing]]" />
    <input type="submit" value="[[ &namespace=`sisea` &topic=`default`]]" />

I created a new chunk called rg.SimpleSearchFormTpl and pasted the code above into it.

Next, we need to insert the SimpleSearchForm call into the ArticlesContainerTemplate. Looking at the template, it is apparent that we need to replace this code:


with this code:


[[!SimpleSearchForm? &landing=`6`]]

However, in order to use the new template chunk we created above we need to modify this call as follows:

[[!SimpleSearchForm? &landing=`6` &tpl=`rg.SimpleSearchFormTpl`]]

We're nearly there but at this point it is still using the default styling and looks like this:

Default search form styling

To modify the styling, we need to go back to rg.SimpleSearchFormTpl and change it to reflect the classes in the Caprice stylesheet. After a bit of experimentation, I was able to simplify the chunk to look like this:

<form class="searchform" action="[[~[[+landing]]]]" method="[[+method]]">
    <input type="text" name="[[+searchIndex]]" id="[[+searchIndex]]" value="Type then hit Enter" onfocus="this.value=''" onblur="this.value='Type then hit Enter'" />
    <input type="hidden" name="id" value="[[+landing]]" />

with the result that the search form now looks like:

Search form properly styled

Phew! - a lot of work for a simple change. I hope you're still with me...

Styling Article summary information

If you remember back in part 5 we still had a few changes to make to the header and footer of the blog summary in order to create new styles for: date posted, tags, comments and so on. These elements are not found in the ArticlesContainerTemplate as they are part of the ArticleRowTpl. We've already made some minor changes to this template to modify the Posted by field. It currently looks like this:

<div class="post">
    <h2 class="title"><a href="[[~[[+id]]]]">[[+pagetitle]]</a></h2>
    <p class="post-info">[[%articles.posted_by]] <a href="[[~[[*id]]]]author/[[+createdby:userinfo=`fax`]]">[[+createdby:userinfo=`fax`]]</a> [[+tv.articlestags:notempty=` | <span class="tags">[[%articles.tags]]: [[!tolinks? &items=`[[+tv.articlestags]]` &target=`[[*id]]` &useTagsFurl=`1`]]</span>`]]</p>
    <div class="entry">
    <p class="postmeta">
      <span class="links">
        <a href="[[~[[+id]]]]" class="readmore">[[%articles.read_more]]</a>
        [[+comments_enabled:is=`1`:then=`| <a href="[[~[[+id]]]]#comments" class="comments">[[%articles.comments]] ([[!QuipCount? &thread=`article-b[[+parent]]-[[+id]]`]])</a>`]]
        | <span class="date">[[+publishedon:strtotime:date=`%b %d, %Y`]]</span>

Whereas previously we replaced the entire content of the ArticlesContainerTemplate with the code from the Caprice blog.html file and then made changes to include the various Articles elements, this time we will leave a lot of the ArticleRowTpl in place and modify it to adjust to the Caprice styles for each element.

The relevant Caprice classes that we want to use are:

  • date
  • day
  • month
  • title
  • comments
  • tags

Their purpose should be self explanatory. The challenge is to modify ArticleRowTpl to include them. To go through the changes line by line would make this already long post much, much longer. I'll leave that mostly up to you. If anything is unclear feel free to ask me in the Comments. I will highlight a few of the changes below the new ArticleRowTpl code, which follows:

<!-- Begin Info -->
<div class="info"> 
  <!-- Begin Date -->
  <div class="date">
    <div class="day">[[+publishedon:strtotime:date=`%d`]]</div>
    <div class="month">[[+publishedon:strtotime:date=`%b`]]</div>
  <!-- End Date --> 
  <!-- Begin Meta -->
  <div class="meta">
    <h3 class="title"><a href="[[~[[+id]]]]">[[+pagetitle]]</a></h3>
          [[+comments_enabled:is=`1`:then=`<a href="[[~[[+id]]]]#comments" class="comments">[[%articles.comments]] ([[!QuipCount? &thread=`article-b[[+parent]]-[[+id]]`]])</a>`]]
          [[+tv.articlestags:notempty=`<span class="tags">[[!tolinks? &items=`[[+tv.articlestags]]` &target=`[[*id]]` &useTagsFurl=`1` &outputDelim=``]]</span>`]]
    <!-- End Meta -->

    <div class="clear"></div>

    <span class="links">
      <a href="[[~[[+id]]]]" class="readmore">[[%articles.read_more]]...</a>
<!-- End Intro -->

  • I needed to split the published date into two separately styled elements (lines 5 & 6).
  • I decided not to use the Created by element and so removed it.
  • For the tags I had to add a null outputDelim in order to remove the commas. I also removed [[%articles.tags]] to get rid of the Tags: label.
  • I significantly changed the order of the elements and wrapped them in the Caprice classes.

This just leaves pagination to be fixed. I can sense another challenge ahead...

Styling pagination

If you look at the bottom of the blog summary you will see two sets of pagination - the pagination generated by Articles and the dummy pagination provided by the Caprice template, as below:

Pagination styling

We need the first to look like the second, and to then remove the dummy entry. If you view the page source, this is what you will see:


(and yes, there is a missing <ul> tag)

We've got a long way to go to get from the first to the second, but fortunately the process if fairly straightforward. Unfortunately it is yet another different method from those we've used when styling the other page elements. Some consistency would be nice.

First, in order to wrap the whole pagination in a <div> with a class of "page-navi":

  1. Navigate to the blog resource and click on the Template tab.
  2. Identify the [[+paging]] placeholder in the content panel.
  3. Edit the content to wrap the div around the paging placeholder.
  4. Save the page.

The code should look like this:

<div class="page-navi">

and the page like this:

Pagination part styled

Next, navigate to the blog resource and click on the Advanced Settings tab followed by the Pagination tab. We will be changing four of these settings.

  1. In the Page Nav Tpl, remove the <ul> tags. This will remove the extra unordered list tag that can be seen in the original code listing.
  2. In the Page Active Tpl, change the class name from "active" to "current" to align with the Caprice styling.
  3. In the Page First Tpl and the Page Last Tpl change First and Last to << and >> respectively. This is a cosmetic change to align with the Caprice styling.
  4. In the Page Prev Tpl and the Page Next Tpl change << and >> to < and > respectively. This is a cosmetic change to align with the Caprice styling.

Save the changes and view the results. It should look like the dummy section below it. Finally, remove the dummy code from the ArticlesContainerTemplate.

This ended up being a much longer post than intended but was brought about by the difficulty and inconsistency of re-styling all the Articles elements. While I understand why (Articles is a combination of many add-ins from different sources and simply reflects the power and diversity of Modx), it would have been nice if all the underlying elements could have been exposed in a consistent manner.

Next up will be a much simpler undertaking where we review the various templates we've been restyling and look for opportunities to turn appropriate sections of code into re-usable chunks.

Add a Comment