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.

In the Package Management screen click on the 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.

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.

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.

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.

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.

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.

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

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.

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.

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.

Applying templates to resources

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

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.

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.

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.

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 .

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.

Creating the outerTpl chunk

Go to the Elements Tab and right click on chunks, then click on 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:

[[+wf.wrapper]]

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.

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

([[+wf.classes]])

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

([[+wf.wrapper]])

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 a.active {border-bottom:3px solid #2DA8F8;}

To:

#menu ul li.active {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.