(713) 568-2763

Building Your First Website in MODx

Building Your First Website in MODx

Building Your First Website in MODx

Building Websites in MODx

MODx has been my content management platform of choice for quite some time now. There are many features that make MODx awesome. Many developers could go into great detail of just how awesome MODx is… I am, however, only going to scratch the surface. Rather than show how MODx can flex its muscles doing complicated things, I am going to help you get your feet wet by getting you started on a new site. I will show that even for simple sites, MODx is a great choice.

MODx requires that it be installed in a PHP/MySQL environment preferably on an Apache server. There are guides-a-plenty detailing this process. We will not be going over all that here.  My goal is to help you build a website in a quick and efficient manner. This is a tutorial not for those new at HTML/CSS, but for those new at MODx.

My Assumptions

  1. You know HTML
  2. You know CSS

3) You already have a design

Configuring MODx

Once installed, there are a few things that I take care of before beginning.

1) Install plugins – There is a package management area under the dropdown “System”. There are many plugins to choose from. There are 2 that I always use without question: If and Wayfinder. If gives you the power to use if/then within your site. In other words, you can have MODx make a decision on what to output depending on a pre-defined condition. A prime example of this would be to have MODx differentiate between your home and subpages.  You would simply tell MODx to output the big fat banner on the home page but output the smaller banner for all your subpages. This is an incredibly useful plugin. Wayfinder might as well come standard with MODx. To me, it is a crucial part of what makes building sites in MODx so easy to use and maintain. Wayfinder, simply stated, takes care of your navigation and menus. It’s more than that, though. Powerful thing this Wayfinder is.  But for now let’s just stick with using it for navigation.

2) Minor Configuration – Also under “System” is the system settings area. I usually make at least 3 changes here. First I turn on Friendly URLs. This allows you to reference the pages using an alias. I much prefer referencing pages by name than by an ID. Once in “system settings” use the dropdown labeled “filter by area” and choose Friendly URL. Near the end of this list is a setting for “Use Friendly URLs”. Right-click this row and choose “Update Setting” then change the value to “Yes”. Save. Now jump to the “Back End Manager” area.  Look for “Resource Tree Node Field”. It defaults to “pagetitle”. I prefer “menutitle”, and I will explain why in a bit. Now jump to the “Site” area and look for “Site Name”. Change this to the actual name of your site.

3) Create Chunks, Template Variables and Snippets, and Template file – Say what?!  Get used to these for they pretty much make up your site. Chunks are like PHP includes in that they are blocks of HTML that can be used when necessary. Snippets are like Chunks except that they are for PHP code. (PHP will not render or run if inside of a Chunk.) Template Variables (TVs) are crucial to understand in order to be as efficient as you can be. TVs give you the flexibility to make page-specific changes to shared template code. In other words, say you might have a chunk for the sidebar that all pages use. But on this one page you need to add an extra CTA or something.  But all pages are using the same code you say… not a problem with template variables.

4) Create “css” and “images” directories in the root. If you use a standard starting CSS file then put it in the “css” directory.  Either name it “styles.css” or change the name in the CSS call in the template file. Put all of your cut out template images in the “images” directory.

Let’s Get Started

Ok you set up hosting and you have installed MODx. If you read the part above then you have also installed 3 plugins and made 4 configuration adjustments. Now let’s start building your site.

The Template File

MODx comes standard with a template file. Let’s go overwrite it!  Take the following code and overwrite the current Base Template content:

<!DOCTYPE HTML>

<html>

<head>

<title>[[*pagetitle]]</title>

<base href=”[[++site_url]]” />

<meta http-equiv=”Content-Type” content=”text/html; charset=utf-8″ />

<meta name=”description” content=”[[*introtext]]” />

<meta name=”keywords” content=”[[*meta-keywords]]” />

<link rel=”stylesheet” type=”text/css” media=”screen,projection” title=”Default” href=”/css/styles.css” />

[[*css]]

[[*scripts]]

</head>

<body>

<div id=”wrap”>

[[$header]]

[[!If?

&subject=[[*body-class]]

&operator=EQ

&operand=home

&then=[[$banner]]

&else=[[$banner-sub]]

]]

[[$main-content]]

[[$side-content]]

[[$footer]]

</div>

</body>

</html>

This is the structure for all of your pages. Many people will create multiple template files for various types of pages within a site. There is nothing wrong with that. In fact, it might even be easier. Not me.  I use one template file and then use TVs to make any page-specific changes that need to be made. Here is a quick rundown on some of the strange stuff you are seeing:

 [[*pagetitle]] – this is a MODx placeholder. Remember making that change in the system settings from pagetitle to menutitle? This will make more sense soon, once we add “pages”.

[[*introtext]] –  This is another MODx placeholder. We will be using this built-in field for our META Decription field.

[[*meta-keywords]] , [[*css]], [[*scripts]] – These are all TVs that we are about to create. They allow us to add code that is specific to just that page.

[[*body-class]] – Here is another TV that we will create next. This one gives us much flexibility moving forward. Hang in there you will find out why.

[[$header]], [[$main-content]], [[$side-content]], [[$footer]] – These are all chunks that we will create. These house the code required for each of those sections.

[[!If?   &subject=[[*body-class]]   &operator=EQ   &operand=home   &then=[[$banner]]   &else=[[$banner-sub]]]] – This is that If snippet we talked about earlier. What’s going here is that any page with a body class of “home” will have the main banner displayed. All other pages will display the subpage banner. Combined with Template Variables, If gives you lots of flexibility in working with a single template file.

Chunks, Snippets  and Template Variables

As I mentioned before, Chunks are blocks of reusable code. It could be a floating sub-menu, it could be a CTA. Now you might be asking about the chunks you saw in the template code. You might be wondering how I consider header, footer, and main-content to be reusable code. You would be right. I could have simply put the code right into the template file. I do it this way to give myself a little flexibility in case I have to make a major structure change to any given page.  Sometimes I do not need a side column on a certain page. I can easily accommodate this by using the If statement and a Template Variable. Remember  the “body-class” TV from above, and how we use it to differentiate between home and subpages?  Since elements can have multiple classes, we can actually introduce extra body-classes and have those pages styled accordingly.

I know this has been a lot of blabbing and explaining and not a lot of coding…… let’s get on with it.

Construct the following chunks (by clicking on the Elements tab near the top left of the page, and then click on the Chunk icon):

Header

<!–header–>

<div class=”hidden”>

<a href=”#nav”>Go to Navigation</a>

<a href=”#main-content”>Go to Content</a>

</div>

<div id=”header”>

<div id=”logo”><a href=”/” title=”home”><span class=”hidden”>[[++site_name]]</span></a></div>

<div id=”nav”>

[[Wayfinder?  &startId=0  &level=2  &excludeDocs=]]

</div>

</div>

<!– end header –>

Main Content

<!–main-content–>

<div id=”main-content”>

<div id=”content”>

<h1>[[*longtitle]]</h1>

[[*content]]

</div>

</div>

<!– end main-content –>

Side Content

<!–side-content–>

<div id=”side-content”>

[[*side-content]]

</div>

<!–end side-content–>

Footer

<!–footer–>

<div id=”footer”>

[[!time:date=%Y]]

</div>

<!–end footer–>

I’m sure you noticed that these are just empty blocks of HTML code.  Good observation, now let’s move on to Template Variables. Click the TV button to begin.

  1. meta-keywords – put this name in the name field on the General Info tab.Go to the Input Options tab and choose “text” for input type. Click on the the Template Access tab and then check the template you are using (“base template”, if you didn’t rename it), save.
  2. css – name=”css”, input type=textarea, check off template, save.
  3. scripts – name=”scripts”, input type=textarea, check off template, save.
  4. body-class – name=”body-class”, input type=text, default value=”default”,  check off template, save.
  5. side-content – name=”side-content”, input type=textarea, check off template, save.

Now for one more thing… This is optional. Most sites have a copyright notice in the footer. Most copyright notices have a year. If you build many sites you don’t want to have to go and update all those copyright dates every year. This snippet keeps the year current.

Click on the snippet button and name it “time”. Place this code inside and save;

<?php

return time();

?>

Remember that strange code in the footer chunk you just created earlier? That calls on the date that this snippet produces.

So now you have installed and configured MODx, as well as setting up the pieces that you will be using. Now you get to actually start building that website.

Getting Down To It

At this point, it is a good idea to go ahead and set up your “pages”. I put quotes around pages because there really aren’t any. All the content is stored in a database and MODx calls on it when needed. But as far as anyone else is concerned, your site is full of pages.

Click on the Resources tab  and then click the new page button that looks like a folder with a plus sign on it. Here’s what you need to fill out:

  1. Title –  this is the actual page title. Equivalent to <title></title>
  2. Long Title – This is the <h1>
  3. Description – not used in this example
  4. Summary (introtext) – SEO description goes here
  5. Uses Template – defaults to “base template”
  6. Resource Alias – the equivalent to a filename. Just leave off the extensions. Sao your filenames will look like this: index, about, gallery, etc…
  7. Menu Title – This is what gets displayed in the navigation menus on your site. Remember that little change we made earlier in the configurations where we changed pagetitle to menutitle? The reason for that was to keep the page names (in the file tree on the left) simple and short, just like in your navigation. If you use SEO-rich page titles then it would become very difficult to know what page was what at a glance. You would otherwise have to click on the page and see what the info is.
  8. Link Attributes – not needed for this example
  9. Published and Hide From Menus – check off or on to publish/unpublish a page. Clicking on Hide From Menu is useful for pages that you do not want to show up in your navigation. (assuming you are using WayFinder).

Two more things to note. First, click on the Settings tab. See Parent Resource? When you click on that and then click on a page in the menu tree, you are telling the page to live under that resource. That’s how you mimic directories. Second, click on the Template Variables tab. This is where you fill out any page-specific info using the TVs you created earlier. They should all be blank except for “body-class”, which should say “default”. Go to your home page and change this to “home”. So now you can distinguish between elements on the home page and elements on the subpages.

Say your home page banner is 960px X 75px and your subpage banner is 960px X 30px. In your CSS file you can distinguish between the two like this:

.home #banner {width:960px; height:75px;}

.default #banner {width:960px; height:30px;}

Go ahead and set up all the pages that your site will have. Now if you view the site you should see:

  1. A mostly white page
  2. A list of your pages (unstyled nav)
  3. The <h1> for that page
  4. 2012 (this is that date script in the footer)

You know what? You’ve just finished all the heavy MODx lifting. You pretty much have all the pieces in place for your site. All that remains is some serious CSS to make it all come to life. I would suggest you use the Web Developer Toolkit, or any live CSS editing software,  if you are not already using something like it. This allows you to work on your CSS while viewing the page you are working on. So you actually see every change you make when you make it.

The goal of this article is to show you how flexible MODx can really be. It might take you a few builds to realize it, but you will realize it. Everyone does. Everyone has their own way of building sites. This is how I roll. You may be on a whole other wave and would prefer to use a different structure or whatever. MODx has your back. Just understand how to use the chunks/TVs/plugins to your advantage.

Hit me up in the comments for questions, or if you just want to make fun of my code you can do that too!


3 Comments

  1. Martin 4 years ago

    Thank you for a stunning post. Being new to Modx, it’s explained a bunch of stuff. I may come back to you once I’ve digested it all. Thanks, Martin

  2. Lonnie Minter
    Lonnie Minter 4 years ago

    Thanks for the kind words, Martin. MODx is a great tool and very easy to use. Keep playing with it and I’m sure you’ll be off and running in no time. Be sure to check the MODx forums for any problems or road blocks that you may encounter. There is a very active, and supportive, community.

  3. Eric Wargo 4 years ago

    Nicely written.

Leave a reply

Your email address will not be published. Required fields are marked *

*