MODx Web Development: Creating Lists

Exclusive offer: get 50% off this eBook here
MODx Web Development - Second Edition

MODx Web Development - Second Edition — Save 50%

Build dynamic websites with MODx PHP application framework and CMS

$23.99    $12.00
by Antano Solar John | March 2011 | Content Management Open Source Web Development

MODx is a content management system and PHP web application framework rolled into one. It allows menus to be dynamically created, based on the content available, as resources. Menus are basically lists of resources, and submenus are lists of lists (lists within a menu list). In MODx, the simplest way to create lists of all the resources is by using the [[wayfinder]] snippet. In this article by Antano Solar John, author of MODx Web Development - Second Edition, we will learn how MODx allows us to create these lists dynamically, and also learn how to present them as menus.

 

MODx Web Development - Second Edition

MODx Web Development - Second Edition

Build dynamic websites with MODx PHP application framework and CMS

        Read more about this book      

(For more resources on the subject, see here.)

Menu details in document properties

Every resource that can be shown in a menu must have the Shown in Menu option enabled in the resource's setting page. The Resource setting page also has two other options related to menus:

(Move the mouse over the image to enlarge it.)

  • Menu title—what to show in the menu. The resource title is used, if this value is left blank.
  • Menu index—when a list of the resources that are to be listed in the menu is created, the menu index can be used to sort the resources in the required order. Menu index is a number, and when creating lists we can specify how we want to use the index.

Authentication and authorization

When creating the list of resources, WayFinder lists only those resources that are accessible by the user depending on the access permissions set for each resource, and the web user group to which the user belongs.

Getting to know WayFinder

WayFinder is a snippet that outputs the structure of the resources as reflected in the resource tree. It creates the lists of all the resources that can be accessed by the current user, from those that been marked as Shown in Menu in the resource properties. Let's try out an exercise to discover WayFinder.

  1. Create a new resource.
  2. Set the name as testing wayfinder.
  3. Choose the template as (blank).
  4. Place the following as the content:

    [[Wayfinder?startId=`0` ]]

  5. Save the document, and then preview it.

You will see a screen like the one shown in the following screenshot:

MODx Web Development: Creating Lists

Notice that WayFinder has created a list of all of the resources, even the ones from the sample site. Each item is a link, so clicking on it leads you to the corresponding document. The generated HTML will look like the following example:

<ul><li><a href="http://localhost/learningMODx/" title="Home" >Home</
a></li>
<li><a href="/learningMODx/index.php?id=2" title="Blog" >Blog</a></li>
<li><a href="/learningMODx/index.php?id=15" title="MODx Features"
>Features</a><ul><li><a href="/learningMODx/index.php?id=16"
title="Ajax" >Ajax</a></li>
<li><a href="/learningMODx/index.php?id=22" title="Menus and Lists"
>Menus and Lists</a></li>
<li><a href="/learningMODx/index.php?id=14" title="Content Management"
>Manage Content</a></li>
<li class="last"><a href="/learningMODx/index.php?id=24"
title="Extendable by design" >Extendability</a></li>
</ul></li>
<li><a href="/learningMODx/index.php?id=33" title="Getting Help"
>Getting Help</a></li>
<li><a href="/learningMODx/index.php?id=32" title="Design" >Design</
a></li>
<li><a href="/learningMODx/index.php?id=53" title="Signup Form"
>Signup Form</a></li>
<li><a href="/learningMODx/index.php?id=6" title="Contact Us" >Contact
us</a></li>
<li><a href="/learningMODx/index.php?id=54" title="Getting to know
ditto" >Getting to know ditto</a><ul><li><a href="/learningMODx/index.
php?id=55" title="Sports RSS" >Sports RSS</a></li>
<li><a href="/learningMODx/index.php?id=56" title="Lifestyle RSS"
>Lifestyle RSS</a></li>
<li class="last"><a href="/learningMODx/index.php?id=57" title="IT
RSS" >IT RSS</a></li>
</ul></li>
<li class="last active"><a href="/learningMODx/index.php?id=58"
title="testing wayfinder" >testing wayfinder</a></li>
</ul>

As seen in the preceding output, the generated list is just a set of <ul> and <li> tags. Let's go step-by-step, in understanding how the preceding output can be customized and themed, starting with menus of one level.

 

Theming

To be able to theme the list generated by WayFinder to appear as menus, we need to understand how WayFinder works in more detail. In this section, we will show you step-by-step how to create a simple menu without any sub-items, and then proceed to creating menus with sub-items.

Creating a simple menu

Since, for now, we only want a menu without any submenu items, we have to show resources only from the top level of the resource tree. By default, WayFinder will reflect the complete structure of the resource tree, including the resources within containers, as seen in the preceding screenshot. WayFinder lets you choose the depth of the list via the &level parameter. The parameter &level takes a value indicating the number of levels that WayFinder should include in the menu. For our example, because we only want a simple menu with no submenu items, &level is set to 1.

Now, let us change the testing wayfinder resource, which we just created, to the following code:

[[Wayfinder?startId=`0` &level=`1` ]]

Preview the resource now, and you will see that the source code of the generated page in place of Wayfinder is:

<ul><li><a href="http://localhost/learningMODx/" title="Home" >Home</
a></li>
<li><a href="/learningMODx/index.php?id=2" title="Blog" >Blog</a></li>
<li><a href="/learningMODx/index.php?id=15" title="MODx Features"
>Features</a></li>
<li><a href="/learningMODx/index.php?id=33" title="Getting Help"
>Getting Help</a></li>
<li><a href="/learningMODx/index.php?id=32" title="Design" >Design</
a></li>
<li><a href="/learningMODx/index.php?id=53" title="Signup Form"
>Signup Form</a></li>
<li><a href="/learningMODx/index.php?id=6" title="Contact Us" >Contact
us</a></li>
<li><a href="/learningMODx/index.php?id=54" title="Getting to know
ditto" >Getting to know ditto</a></li>
<li class="last active"><a href="/learningMODx/index.php?id=58"
title="testing wayfinder" >testing wayfinder</a></li>
</ul>

Now, if we can just give <ul> and <li> respective classes, we can style them to appear as a menu. We can do this by passing the class names to the parameter &rowClass.

Change the contents of the preceding testing wayfinder to:

<div id="menu">
[!Wayfinder?startId=`0` &level=`1` &rowClass=`menu`!]
</div>

Now, open style.css from the root folder, and change the CSS to the following code. What we are doing is styling the preceding generated list to appear like a menu, by using CSS:

* { padding:2; margin:0; border:1; }
body { margin:0 20px; background:#8CEC81; }
#banner { background: #2BB81B; border-top:5px solid #8CEC81; borderbottom:
5px solid #8CEC81; }
#banner h1 { padding:10px; }
#wrapper { background: #8CEC81; }
#container { width: 100%; background: #2BB81B; float: left; }
#content { background: #ffffff; height:600px; padding:0 10px 10px
10px; clear:both; }
#footer { background: #2BB81B; border-top:5px solid #8CEC81; borderbottom:
5px solid #8CEC81; }
.clearing { clear:both; height:0; }
#content #col-1 {float:left;width:500px; margin:0px;padding:0px;}
#content #col-2 {float:right; width:300px; margin:0px; padding:30px 0
10px 25px; border-left:3px solid #99cc66; height:500px;}
#content #col-2 div {padding-bottom:20px;}
#menu {
background:#ffffff;
float: left;
}
#menu ul {
list-style: none;
margin: 0;
padding: 0;
width: 48em;
float: left;
}
#menu ul li {
display: inline;
}
#menu a, #menu h2 {
font: bold 11px/16px arial, helvetica, sans-serif;
display: inline;
border-width: 1px;
border-style: solid;
border-color: #ccc #888 #555 #bbb;
margin: 0;
padding: 2px 3px;
}
#menu h2 {
color: #fff;
background: #000;
text-transform: uppercase;
}
#menu a {
color: #000;
background: #2BB81B;
text-decoration: none;
}
#menu a:hover {
color: #2BB81B;
background: #fff;
}

Also remember to change the template of the resource to the learning MODx default template.

Now preview the page, and you will see something like the one shown in the following screenshot:

The HTML code returned will be similar to the following:

<ul><li class="menu"><a href="http://localhost/learningMODx/"
title="Home" >Home</a></li>
<li class="menu"><a href="/learningMODx/index.php?id=2" title="Blog"
>Blog</a></li>
<li class="menu"><a href="/learningMODx/index.php?id=15" title="MODx
Features" >Features</a></li>
<li class="menu"><a href="/learningMODx/index.php?id=33"
title="Getting Help" >Getting Help</a></li>
<li class="menu"><a href="/learningMODx/index.php?id=32"
title="Design" >Design</a></li>
<li class="menu"><a href="/learningMODx/index.php?id=53" title="Signup
Form" >Signup Form</a></li>
<li class="menu"><a href="/learningMODx/index.php?id=6" title="Contact
Us" >Contact us</a></li>
<li class="menu"><a href="/learningMODx/index.php?id=54"
title="Getting to know ditto" >Getting to know ditto</a></li>
<li class="menu last active"><a href="/learningMODx/index.php?id=58"
title="testing wayfinder" >testing wayfinder</a></li>
</ul>

Notice that for each menu item, the class menu has been applied. Although we have not applied any custom style to the menu class, we have shown you that when you are building more fine-grained menu systems, you have the ability to have every item associated with a class.

MODx Web Development - Second Edition Build dynamic websites with MODx PHP application framework and CMS
Published: February 2011
eBook Price: $23.99
Book Price: $39.99
See more
Select your format and quantity:
        Read more about this book      

(For more resources on the subject, see here.)

Nested menus

When we have more than one level of the menu structure, we will want different styling for the top menu and the menu items. This effectively means that we need to have different classes for different levels. Also, some menu systems have different styling for the first and the last elements. Such flexibility in styling is also possible with the WayFinder snippet. Let us consider a two-level structure with the class names that we might want illustrated, shown at the side. For this example, the list will be:

<ul>
<li> Menu1 Name </li> outer first
<ul>
<li> Menu item 1</li> inner first
<li>Menu item 2</li> inner
<li>Menu item 3</li> inner
<li>Menu item 4</li> inner last
</ul>
<li> Menu2 Name</li> outer
<ul>
<li> Menu item 1</li> inner first
<li>Menu item 2</li> inner
<li>Menu item 3</li> inner
<li>Menu item 4</li> inner last
</ul>
<li> Menu3 Name</li> outer last
<ul>
<li> Menu item 1</li> inner first
<li>Menu item 2</li> inner
<li>Menu item 3</li> inner
<li>Menu item 4</li> inner last
</ul>
</ul>

The following are the list of parameters that we will need to use to be able to have the respective class names in the generated list:

MODx Web Development: Creating Lists

Now change the content in the testing wayfinder document to:

<div id="menu">
[!Wayfinder?startId=`0` &level=`2` &outerClass=`outer`
&innerClass='inner' &lastClass=`last` &firstClass=`first`
&hereClass=`active`!]
</div>

This code will result in an output similar to the following code. Notice that the class names are similar to the structure that we wanted, as outlined earlier.

div id="menu">
<ul class="outer"><li class="first"><a href="http://localhost/
learningMODx/" title="Home" >Home</a></li>
<li><a href="/learningMODx/index.php?id=2" title="Blog" >Blog</a></li>
<li><a href="/learningMODx/index.php?id=15" title="MODx Features"
>Features</a><ul class="'inner'"><li class="first"><a href="/
learningMODx/index.php?id=16" title="Ajax" >Ajax</a></li>
<li><a href="/learningMODx/index.php?id=22" title="Menus and Lists"
>Menus and Lists</a></li>
<li><a href="/learningMODx/index.php?id=14" title="Content Management"
>Manage Content</a></li>
<li class="last"><a href="/learningMODx/index.php?id=24"
title="Extendable by design" >Extendability</a></li>
</ul></li>
<li><a href="/learningMODx/index.php?id=33" title="Getting Help"
>Getting Help</a></li>
<li><a href="/learningMODx/index.php?id=32" title="Design" >Design</
a></li>
<li><a href="/learningMODx/index.php?id=53" title="Signup Form"
>Signup Form</a></li>
<li><a href="/learningMODx/index.php?id=6" title="Contact Us" >Contact
us</a></li>
<li><a href="/learningMODx/index.php?id=54" title="Getting to
know ditto" >Getting to know ditto</a><ul class="'inner'"><li
class="first"><a href="/learningMODx/index.php?id=55" title="Sports
RSS" >Sports RSS</a></li>
<li><a href="/learningMODx/index.php?id=56" title="Lifestyle RSS"
>Lifestyle RSS</a></li>
<li class="last"><a href="/learningMODx/index.php?id=57" title="IT
RSS" >IT RSS</a></li>
</ul></li>
<li class="last active"><a href="/learningMODx/index.php?id=58"
title="testing wayfinder" >testing wayfinder</a></li>
</ul>
</div>

Now preview the page, and it will look like the one shown in the following screenshot:

Notice that the inner items are also shown. We will change this behavior by adding some CSS styling to show this inner menu only on hover.

Now, edit style.css to be the following:

* { padding:2; margin:0; border:1; }
body { margin:0 20px; background:#8CEC81; }
#banner { background: #2BB81B; border-top:5px solid #8CEC81; border-
bottom:5px solid #8CEC81; }
#banner h1 { padding:10px; }
#wrapper { background: #8CEC81; }
#container { width: 100%; background: #2BB81B; float: left; }
#content { background: #ffffff; height:600px; padding:0 10px 10px
10px; clear:both; }
#footer { background: #2BB81B; border-top:5px solid #8CEC81; border-
bottom:5px solid #8CEC81; }
.clearing { clear:both; height:0; }
#content #col-1 {float:left;width:500px; margin:0px;padding:0px;}
#content #col-2 {float:right; width:300px; margin:0px; padding:30px 0
10px 25px; border-left:3px solid #99cc66; height:500px;}
#content #col-2 div {padding-bottom:20px;}
#menu {
background:#ffffff;
float: left;
}
#menu ul {
list-style: none;
margin: 0;
padding: 0;
width: 48em;
float: left;
}
#menu ul li {
display: inline;
}
#menu a, #menu h2 {
font: bold 11px/16px arial, helvetica, sans-serif;
display: inline;
border-width: 1px;
border-style: solid;
border-color: #ccc #888 #555 #bbb;
margin: 0;
padding: 2px 3px;
}
#menu h2 {
color: #fff;
background: #000;
text-transform: uppercase;
}
#menu a {
color: #000;
background: #2BB81B;
text-decoration: none;
}
#menu a:hover {
color: #2BB81B;
background: #fff;
}
#menu li {position: relative;}
#menu ul ul {
position: relative;
z-index: 500;
}
#menu ul ul ul {
top: 0;
left: 100%;
}
div#menu ul ul,
div#menu ul li:hover ul ul,
div#menu ul ul li:hover ul ul
{display: none;}
div#menu ul li:hover ul,
div#menu ul ul li:hover ul,
div#menu ul ul ul li:hover ul
{display: block;}

Now preview the page and note that the submenu items are shown only on hover. This is also shown in the next screenshot.

Note again that the class name generated previously is only for information purposes. This is to let you know that you have a finer-grained menu system available to you if you need it. Had you replaced the call to Wayfinder with just [!Wayfinder?startId=`0` &level=`2`!], it would have still worked.

Now that we have the menus appearing in this page, let us make them appear in all the pages. Note that we created this page only for testing, and to find out how WayFinder works. We will need to use the code that we have come up with in this page in the default Learning MODx template.

Change the default Learning MODx template to the following:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/
TR/xhtml11/DTD/xhtml11.dtd"> <html xmlns="http://www.w3.org/1999/
xhtml" xml:lang="en">
<head>
<base href="[(site_url)]"></base>
<title>Learning MODx</title>
<meta http-equiv="Content-Type" content="text/html;
charset=iso-8859-1" />
<link rel="stylesheet" type="text/css" href="assets/templates/
learningMODx/style.css" />
</head>
<body>
<div id="banner">
<h1>Learning MODx</h1>
</div>
<div id="wrapper">
<div id="container">
<div id="content">
<div id="col-1">
<div id="menu">
[!Wayfinder?startId=`0` &level=`2` &outerClass=`outer`
&innerClass='inner' &lastClass=`last` &firstClass=`first`
&hereClass=`active`!]
</div>
<h1>[*pagetitle*]</h1>
<br/>
[*#content*]
</div>
<div id="col-2" >
<div > [!WebLogin!] </div>
<div>
[!Ditto? &parents=`47` &tpl=`dittofrontpage`!]
</div>
</div>
</div>
</div>
<div class="clearing"> </div>
</div> <!-- end of wrapper div -->
<div id="footer">It is fun and exciting to build websites with
MODx</div></body>
</html>

Save the template, and then preview the Home page. It will look like the example shown in the following screenshot:

Now that you have learned how to theme lists that are two levels deep, you may be wondering how to theme lists that are more than two-levels deep. You can theme such lists by using the levelClass parameter. For example, if you set &levelClass = `level`, then the level items will have the classes level1, level2, level3.

[!Wayfinder?startId=`0` &level=`5` &outerClass=`outer`
&innerClass='inner' &lastClass=`last` &firstClass=`first`
&hereClass=`active` &level2=`xxx` &level3=`yyy`!]

MODx Web Development - Second Edition Build dynamic websites with MODx PHP application framework and CMS
Published: February 2011
eBook Price: $23.99
Book Price: $39.99
See more
Select your format and quantity:
        Read more about this book      

(For more resources on the subject, see here.)

Changing the name in the menu

Let us change the name of the menu title for the page called 'Getting to know ditto', which lists all of the blog entries. To do that, perform the following steps:

  1. Click on the resource Getting to know ditto and edit it.
  2. Change the menu title to Feeds.
  3. Save the document.
  4. Repeat the above steps for the document SignUp Form and change the menu name to Register.

Notice that the menus have changed, as shown in the following screenshot:

Doc Manager

Doc Manager is a module that allows you to change the template, template variables, and other resource properties of one or more resources. Using the Doc Manager makes it easier to make changes to multiple resources simultaneously. Doc Manager can be accessed from the Doc Manager menu item in the Modules menu. The following is a screenshot of the Doc Manager:

As you can see, it has five tabs:

MODx Web Development: Creating Lists

Following is a screenshot of Sort Menu Items after selecting the Parent as Learning MODx(0) - the root folder. The parent for sort menu items was selected done by clicking on it and then clicking on Go.

Note that this module still calls resources as documents, as they were called in earlier versions of MODx. So you can safely substitute the word document with resource when you come across it here in this module.

With the exception of Sort Menu Items, all actions have a field at the bottom called Specify a Range of Document IDs.

The resources on which the changes have to be made are selected by entering the appropriate value in this field. You can specify a single resource, or a range of resources, with the operator. You can refer to a resource and all of its immediate children by entering the resource ID followed by an *. You can specify a resource and all its children by entering the resource ID followed by **. You can have a list of all of these syntaxes, as long as they are separated by commas; for example: 10,20-30,5*,8**. This will make the selected changes in:

  • Resource 10
  • Resources 20 to resource 30
  • Resource 5 and all of its immediate children
  • Resource 8 and all of its children

Removing pages from the menu

You might notice that menu items are generated even for pages from the MODx sample site. Because our purpose for having these pages is only to look at them and learn, we do not want them to be appearing in our menus. Also, there are a few pages that we have created to test the functionality; and we will want to hide these, too. You can hide resources one by one by selecting the resource, clicking on Edit, deselecting the Shown in Menu checkbox, and then saving the resource. Alternatively, you can use the Doc Manager to change the properties for a set of documents.

To change the Shown in Menu setting using the Doc Manager, carry out the following steps:

  1. Click on the Modules menu, and then select the Doc Manager menu item.
  2. Click on the Other Properties tab.
  3. Change the Available Settings to Show/Hide in Menu.
  4. Select the Hide in Menu checkbox.
  5. In the Specify a Range of Document IDs field, list the IDs for all of the documents that you want to hide separated by commas. It can be something like 2*,15*,33,39*,32,6,58. Notice that * stands for the document with the given ID and its immediate children.

Note that the preceding ID list could be different for you depending on the order in which you created the documents.

Now click on Preview and the page will look like the example shown in the following screenshot:

Summary

In this article we have learned how to use the snippet [[WayFinder]] to create lists of documents. We also saw how the snippet parameters for WayFinder make the list creation flexible.


Further resources on this subject:


About the Author :


Antano Solar John

Antano Solar is a techie to the core—a tech evangelist who is passionate about using technology to revolutionize the learning experience! Antano has contributed to the open source community in terms of documentation, code, and support, with a variety of platforms based on languages such as PHP, Perl, Lisp, Python, and Ruby.

He loves to share his tech excitement with fellow techies and non-techies, and does so through publishing papers, books, and delivering seminars at colleges, universities such as the IIT, and corporate tech events.

He has published a paper on enhancing wireless networks in an IEEE Journal. His paper on an engine helping machines understand objectives by meta-modeling, using Neurolinguistic Programming principles and Deep Structure, is considered a landmark.

An avid hacker, Antano has won two Yahoo hack-day awards. He recently won the award for developing a Hybrid Search Engine from scratch in 24 hours that uses Machine Intelligence and Social Intelligence to identify, search, and present the information in the required format.

Professionally, until recently, Antano was a Consultant and a Trainer providing IT solutions and sessions on VoIP, Networks and Software Plaforms, and Languages. He is currently the Chief Technology Officer at NuVeda Learning. In his current role, he is responsible for the development and deployment of Learning Management Systems that are used by large MNCs globally. He also plays the role of a Chief Architect in the research and development of technologies related to the understanding and measuring of Learning. He is excited by the challenges of using complex technologies such as Artificial Intelligence and Natural Language Processing.

Occasionally, when Antano needs to take a "Tech" break, he likes to train and tell stories!

Books From Packt


CMS Design Using PHP and jQuery
CMS Design Using PHP and jQuery

Inkscape 0.48 Essentials for Web Designers
Inkscape 0.48 Essentials for Web Designers

Joomla! 1.6 First Look
Joomla! 1.6 First Look

Squid Proxy Server 3.1: Beginner's Guide
Squid Proxy Server 3.1: Beginner's Guide

Building Websites with ExpressionEngine 2
Building Websites with ExpressionEngine 2

WordPress 3 Complete
WordPress 3 Complete

Agile Web Application Development with Yii1.1 and PHP5
Agile Web Application Development with Yii1.1 and PHP5

Alfresco 3 Web Services
Alfresco 3 Web Services


Code Download and Errata
Packt Anytime, Anywhere
Register Books
Print Upgrades
eBook Downloads
Video Support
Contact Us
Awards Voting Nominations Previous Winners
Judges Open Source CMS Hall Of Fame CMS Most Promising Open Source Project Open Source E-Commerce Applications Open Source JavaScript Library Open Source Graphics Software
Resources
Open Source CMS Hall Of Fame CMS Most Promising Open Source Project Open Source E-Commerce Applications Open Source JavaScript Library Open Source Graphics Software