Welcome to part 8 of our series of tutorials on building a website with MODx CMS. So far we’ve looked at:
Part 1: Introduction to MODx
Part 2: Installing MODx
Part 3: Working with Templates
Part 4: Introducing Chunks
Part 5: Introducing Snippets
Part 6: Introducing Template Variables
Part 7: Introducing Ditto
As we work through these tutorials, we’re building a MODx resource site called Learn MODx. In the last installation we introduced Ditto and continued working on the Library section of our resource website. In today’s installation we’re going to continue working some more with Ditto, and learn how to template our output so that our Library page has the look we want. In the learn we will learn a little more about Ditto, its parameters, and its placeholders.
Before we proceed, I need to mention a couple of things. In the comments to Part 7 – Introducing Ditto, fellow MODx’ers Kongondo and Zaigham both pointed out that I was using deprecated parameters in my Ditto call… old habits :). Thank you much for pointing that out guys. In the current install, we’re using version 2.1 of the Ditto snippet. As Kongondo pointed out, the &startId parameter has been deprecated in this version of Ditto. The parameter still works, but we are going to use the supported parameter for our current version of Ditto, which is &parents.
Therefore, before we proceed any further, let’s open up our Library page and alter our Ditto call:
[!Ditto? &startID=`6` !]
[!Ditto? &parents=`6` !]
The lesson here is that I should heed my own advice and always read the documentation for the snippet we’re using to make sure that we’re using the correct up-to-date parameters and such
The Ditto home page gives us all the parameters and placeholders for the current version of Ditto: http://ditto.modxcms.com/files/snippet-ditto-php.html
Alright, so with that out of the way, we’re now going to move on with our Library page. If you recall from the last tutorial, the end result of our Ditto statement was that our Library page looked like this: (click on image for larger view)
I want the individual entries on that page to look a little different. I would like to remove the user name as well as the date, and only have the title and the content, as well as a read more link that the visitor can click on and go to the page with the full content.
Create a Custom Template
The first step is to create a chunk with a template that will determine what our Ditto output looks like. I will then call this template into the Ditto call.
Go to Administer -> Resources -> Manage Resources and create a new chunk. We’re going to call this chunk librarytemplate.
The template that we create will, like all other templates, be simple HTML. However, we need to add placeholders for the different parts of our content, such as the title, the summary, and the read more link.
The syntax for placeholders is [+placeholder+]. Several placeholders are supported by Ditto. You can find a full list of Ditto placeholders in the Wiki. Note however that this list is for version 1.0 of Ditto, and not all of them may be supported in version 2. I have not been able to find a current complete list of Ditto 2.0 placeholders. If one exists, please let me know in the comments and I will add it.
OK, so for our custom template to simply have a hyperlinked title, the summary, and a read more link, we simply put the following code in our librarytemplate chunk.
<h3><a href="[~[+id+]~]">[+pagetitle+]</a></h3> [+introtext+] <a href="[+url+]"> read more...</a>
What this basically means is that our title will be a <h3> level title and will link back to the main page. You can see the syntax is simply the same as for creating a regular link, except that we’re using placeholders.
[+introtext+] will place the summary text, and the final <a href…. call will place the read more link. In that last line I could have used [~[+ID+]~] and it would still have worked, but using [+url+] is cleaner and separates the meaning of the two links.
Alright, save the chunk.
Ditto Output with a Custom Template
We will now go into our Ditto call and tell it to use this template that we’ve created to theme the output of our Library page. We do this by using the tpl parameter.
So in the Library page, alter your Ditto call to include the template parameter and call your new template chunk.
[!Ditto? &parents=`6` &tpl=`librarytemplate`!]
If we save the page and now look at our Library page, you see that the author and date no longer show, and we now have a “read more” link at the end of each entry.
Looking good :).
Now I definitely haven’t exhausted the list of books I want to share that are useful for MODx’ers. Many skills will come together to make you better at building your MODx websites, HTML/CSS skills, PHP skills, design skills, and who know how many other MODx books are going to be published. This list is definitely going to grow! And if I leave my Library page as it is now, it’s going to grow longer and longer, and you’ll have to scroll and scroll and scroll… and eventually it won’t even load .
I need to tell the Ditto call to only list x number of entries per page. For now, because I only have 5 entries, I am going to ask it to list only 2, for purposes of demonstration.
To do this, we use the Ditto parameter display, so our Ditto call looks like this:
[!Ditto? &parents=`6` &tpl=`librarytemplate` &display=`2` !]
This will display only two entries on the Library page:
Now what you’ll realize immediately is that Ditto doesn’t automatically paginate or give you a way to navigate to the next page of books. You have to add more parameters and placeholders to create this navigation. You can read more on paginating at the Ditto page (http://ditto.modxcms.com/tutorials/pagination.html).
I will add two parameters to my Ditto call:
[!Ditto? &parents=`6` &tpl=`librarytemplate` &display=`2` &paginate=`1` &paginateAlwaysShowLinks=`0` !]
- Setting the paginate parameter to 1 turns pagination on (zero turns it off).
- Setting the paginateAlwaysShowLinks to zero leaves the “Next” or “Previous” (or whatever navigation text you’re using) placeholders empty when the current page is the last (or first) page of results.
The last thing I need to do to complete my pagination is to add some placeholders below the Ditto call to display my navigation. I will simply add
[+previous+] [+pages+] [+next+]
below my Ditto call. I can also place this in <div> tags so that I can style it as per the instructions on the Ditto pagination page.
So my Library page content area looks like this:
We can now save the Library page and look at the results.
We now have page numbers at the bottom and a navigation that lets us move through pages in our Library. It may not look too hot , but it works, and adding hotness can be achieved by styling. You can follow the instructions on the Ditto Pagination webpage to style your navigation.
There are so many things you can do with Ditto, I could not possibly cover them all, I don’t even know them all , but I hope that these tutorials give you a starting point to learn the basics and explore more on your own using the documentation at the MODx website, asking questions at the MODx forums, and experimenting with your websites.
For now, we’re going to leave Ditto alone, and move on to other things in the next tutorial, adding more functionality and goodies to our MODx resource site as we continue to learn more MODx basics! So stay tuned
As always, I welcome any comments, corrections, and hellos!
And do remember to grab your copy of the MODx Web Development book!
http://ditto.modxcms.com/ – Ditto Official Site and Documentation
http://ditto.modxcms.com/tutorials/creating-a-custom-template.html – More on creating custom Ditto templates
http://wiki.modxcms.com/index.php/Ditto_Placeholders - List of Ditto placeholders, be aware that this list is for an older version of Ditto and they may not all be supported in the current version.
http://www.pogwatch.com/ditto/ditto-parameters.html?tab=ph – Complete list of Ditto 2.1 placeholders
http://www.pogwatch.com/ditto.html – Lots of Ditto information