Integrating a Template into MODX part 2

Integrating a Template into MODX part 2

In our second part of this tutorial we will cover how to download and install MODX Extras, creation of categories in MODX to keep our site organized, applying templates to resources, uploading our assets into MODX, create a Chunk tpl and create a Wayfinder navigation. There's a lot to cover so lets get started.

Download & Install Extras

MODX comes with a package manager built into the core in order to install extras and extend MODX s functionality. Open your MODX installation in your browser and hover over the System tab and you will see the first option in the drop down is Package Management, lets click on it.

Package Management Link

In the Package Management screen click on the Download Extras button.

Download Extras Button

This will bring you to the Package Browser screen where you can search or Browse through all the available MODX extras you wish to install.

Package Browser

Based on our assessment we know which extras we need, these are: Wayfinder (Dynamic Navigation Creator), Gallery (Image Gallery Manager) and FormIt (Form Creator with built in validation) let s find these and download them using the Package Browser.

Since the 3 extras we need are very popular they are in the Most Popular table on the Package Browser page, if they weren t we could ve used the Extra Search field in order to search for the individual packages.

Most Popular Table & Extra Search

First we need to download the packages, proceed to click on the name of each package we need to download in the Modx Popular table and you will be taken to a page where you can download each package.

Download Wayfinder

Download Gallery

Download FormIt

Install Extras

Now that we have downloaded our extras we have to install them, click on the Back to Package Management link in the Package Browser.

Back to Package Management

As you can see our Package Manager has the 3 extras we downloaded ready to be installed, click on the green install button then continue to start the installation process, once the installation is completed you will see a console modal window with a success message.

Install Package Button

Continue Button

Console Window


Tip: You can also download extras from the MODX site and install them manually via the Package Manager, just download any extra from the MODX site and upload them to the core/packages directory then click on the little arrow in the Download Extras button and select Search Locally for Packages, click Yes on the prompt and your package will appear in the Package Manager ready to install.

Manual Package Installation

Inserting templates into MODX

In the MODX Manager click on the Elements tab on the left tree navigation this is where all your Templates, Template Variables, Chunks, Snippets, Plugins and Categories are created and stored.

Elements Tab

Now, right click on the Templates link and select New Template.

New Template Link

This will open the New Template page, once in the New Template page insert a name for your template, I am calling mine Homepage to keep it simple, in the Description text area I am putting a brief description what this template should be used for.

New Template Page

Next let s go back to your text editor and go to the Homepage template and select all (Ctrl+a), then copy (Ctrl+c) your selected text, now back in the New Template page in the Template Code (html) text area paste (Ctrl+v) your html code, hit save and you have just inserted your template into MODX.

Now to keep our templates organized let s create a new Category so we can store them, right click on Categories and select New Category this will open the New Category dialog where you can insert the name of your Category, I will name mine Soho and click Save.

New Category/New Category Dialog

You will now have a Soho folder under your Category folder now let s insert our templates into our Soho folder. If you look at the top right portion of our template you will see it has a Category Drop Down menu click on it and select Soho, then click Save. This will insert the template into the Soho folder and it will update the Template Tree on the left. Once the Soho folder is visible in the Template Tree we can drag and drop our remaining templates into the folder or you can go into each template and change its Category field.

Category Drop Down

TipTip: If the Template Tree doesn t update when you Save the template changes, you can press the Refresh Tree button.

Applying templates to resources

Click on the Resources Tab select the Home Resource under the Web Context.

Web Context & Home Resource

Now let s click on the Uses Template drop down on the right hand side and change our template to use the Homepage Template, click Save then View to see what our homepage looks like.

Change Template

As you can see our homepage is broken since we haven t uploaded any of the images, css or javascript files. Let s fix that.

Broken Homepage

Uploading CSS, Javascript and Images into MODX

While you can use the MODX File Manager to create folders and upload files it is much easier to do so via FTP, so open your favorite FTP client and upload the Images, CSS and scripts folder inside the assets folder.

Refresh your page and if done correctly your homepage should have all styles applied to it, this is why we spent that extra time in the first part of this tutorial setting up our files locally.

Assets Uploaded

What is Wayfinder?

Wayfinder is a Snippet by kylej that scans a specified portion of the MODx document tree, finds all documents that satisfy a certain criteria (determined by the Parameters), and outputs a formatted list of those documents. The formatting of the output is template-driven, and can contain any combination of HTML, CSS and JavaScript, yielding an enormous degree of flexibility.

You can view the Official Wayfinder documentation here if you want to learn everything about Wayfinder then download this free ebook.

Creating Our Wayfinder Calls

Click on Elements tab in the File Tree, and then click on the Homepage template. Now we need to locate the navigation in our template so we can replace it with our Wayfinder call. Scroll down until you find the unordered list (ul tag) with an ID of nav .

ul with nav ID

We need to replace this unordered list with our Wayfinder call, so delete the ul with ID nav and replace it with this code:

[[Wayfinder? &startId=`0` &level=`1` &outerTpl=`soho-nav`]]

Your template should now look like this.

Let s analyze what Wayfinder is doing, first we call our snippet which would be but this on its own would not do anything so we add a few parameters to tell it what we want it to display.

We add the ? to tell Wayfinder we are sending some parameters then we add the &startId=`0` what this does is tell Wayfinder we want it to list all resources starting at the root of our site in this case the Web Context, we proceed by adding a second parameter &level=`1` this lets Wayfinder know we only want the first level resources to be displayed and our final parameter is &outerTpl=`soho-nav` this paremeter tells Wayfinder we want it to use a Chunk called soho-nav as its outer template which we will create in our next step.

TipTip: You can change the startId to any resource ID in the File Tree, depending on your parameters Wayfinder will output the child resources of the startId as an unordered list by default or you can customize the Wayfinder output by using a outerTpl, innerTpl and a rowTpl. If you want Wayfinder to display all resources in the ul use &level=`0`. For more information on all of Wayfinders parameters and options please refer to the official Wayfinder documentation.

Creating the outerTpl chunk

Go to the Elements Tab and right click on chunks, then click on New Chunk.

New Chunk

Once in the New Chunk Page let s name our chunk soho-nav which is what we used in our Wayfinder call, insert a brief description what this Chunk is used for (so the next dev doesn t go crazy trying to figure out what it does) and in the Chunk Code text area let s place the default value of a Wayfinder outerTpl which is:


Now we have to add the id to our ul so let s add id= nav to our outerTpl ul, so your outerTpl should look like this now.

Chunk Page

Let s explain what a Chunk is and what we are doing using it for the outerTpl. A Chunk is raw HTML code that can be reused anywhere on your site all you have to do in order to display a chunk on your site is use the tag , Chunks can also be used as templates when used in conjunction with snippets like Wayfinder and getResources and many other MODX extras. Each snippet has its own way of handling templates (tpl) so make sure to read the instructions on how to use any particular extra.

In this case we are telling Wayfinder to use the Chunk soho-nav as its template by passing the templates name in the &outerTpl parameter. Wayfinder will then use the chunk as its HTML output when creating the navigation.

So basically we are saying Wayfinder create an unordered list and use the default Wayfinder classes


and use the id nav for this list and output the inner contents


Now Save your Chunk and preview your resource, your nav is almost done but if you pay close attention the nav is missing the active state indicator (the blue underline). To fix this we have edit our style.css file, click on the File Tab, and then expand the assets folder, expand the css folder and finally click on the style.css file. Now do a find (ctrl+f) for active in the css file it should be on line 40 and change line 40 from:

#menu ul li {border-bottom:3px solid #2DA8F8;}


#menu ul {border-bottom:3px solid #2DA8F8;}

Wayfinder by default adds an active class to the li that is active, it also adds a first and last class to the first and last li in any list, by changing this line of code we changed it from applying the active class to the a href to the li with the active class generated by Wayfinder. Save and refresh your page and now the active class is working like it should.

Wayfinder has many parameters and features in most cases you would only need to have a simple Wayfinder call with an outerTpl and a rowTpl to achieve any navigation you want, refer to the official Wayfinder documentation for all the features and options.

09 Jun

Author Benjamin Marte Category Tutorials Comments (12)

Comments (12)

  1. Kevin Razmus:
    Jun 11, 2012 at 09:10 PM

    Great work Ben! I must say, you put a lot of time into showing exactly how and where to go. Excellent MODX tutorial, can't wait to see what's next!

  2. Benjamin Marte:
    Jun 11, 2012 at 09:42 PM

    Thanks for the kind words Kevin, hopefully you decide to write up a tutorial one of these days too so we can share it with the MODX community.

  3. takeaway menu design:
    Jan 04, 2013 at 04:56 AM

    Wow that was unusual. I just wrote an very long comment but after I clicked submit my comment didn't show up. Grrrr... well I'm not writing all that over
    again. Regardless, just wanted to say wonderful blog!

  4. Shoe:
    Feb 08, 2013 at 01:53 AM

    What an extremely positive and inspiring posting.

    I am always very impressed with your work. You produce extremely helpful info.

    Keep it up. Keep blogging. looking forward with true anticipation to opening your next post.

  5. Dipesh Parajuli:
    May 09, 2013 at 03:49 AM

    for the menu i have paste

    [[Wayfinder? &startId=`0` &level=`1` &outerTpl=`ldta-nav`]]

    but when i save and preview it only home is showing, not other menu like about us, contact. why?

    On my css i have class does this make any difference for id.



    do i have to put id=""

    my css for menu.
    .topmenu {
    background-image: url(../images/menubg.jpg);
    background-repeat: repeat-x;
    width: 978px;
    height: 37px;
    float: left;
    border: 1px solid #000000;
    .topmenu ul {
    width: 100%;
    height: 37px;
    list-style-type: none;
    .topmenu ul li {
    height: 37px;
    float: left;
    padding-right: 20px;
    padding-left: 20px;
    .topmenu ul li a {
    font-family: Arial, Helvetica, sans-serif;
    font-size: 12px;
    font-weight: bold;
    line-height: 37px;
    color: #FFFFFF;
    text-decoration: none;
    display: block;
    height: 37px;
    float: left;
    padding-right: 21px;
    padding-left: 21px;
    .topmenu ul li a:hover {
    background-image: url(../images/menu-hov.jpg);
    background-repeat: repeat-x;
    background-position: left top;

  6. Benjamin Marte:
    May 11, 2013 at 02:05 PM

    @Dipesh what does ldta-nav outertpl have inside? Also make sure the resources are published and not hidden from the menus.

    Good luck.

  7. Dipesh Parajuli:
    May 12, 2013 at 12:39 AM

    @Benjamin Marte,

    thanks for reply, My resources is in published, On chunk i had put this, wayfinder

    Name: ldta-nav


    So on Home page menu i had paste this one

    [[Wayfinder? &startId=`0` &level=`1` &outerTpl=`ldta-nav`]]

    So, on id what i had to put.

    So, on my last inquiry i had send you my css for that menu.

  8. Benjamin Marte:
    May 12, 2013 at 10:27 AM

    @Dipesh if you are following the tutorial your ldta-nav chunk should look like this:


    So yes, you need the ID on the ul if your css is targetting it by ID.

    I hope that makes sense, good luck.

  9. baptize:
    Jul 13, 2013 at 01:36 PM

    Thank you for this excellent tutorial.
    I'm not sure where to upload the files to inside modx??

  10. Benjamin Marte:
    Jul 16, 2013 at 08:18 AM

    @baptize that is totally up to you, you can create a folder and upload all of your images there.

  11. Zae Vega:
    Aug 29, 2013 at 11:52 AM

    Thanks a lot Benjamin! Everything s so clear and easy to follow, that I actually built my first MODX project from HTML/CSS/JS completely with your tutorials.


  12. Benjamin Marte:
    Sep 17, 2013 at 03:26 PM

    @Zae Vega glad these were helpful for you and congrats on making your first site in MODX

    @David glad you got it working

Leave a Comment

This thread has been closed from taking new comments.

Scroll to top