Beginner's Guide to MODx
From MODx Wiki
Unless you are one of the lucky ones who can intuit almost instantly how to use MODx, the first thing that happens after you get it installed is: “Great CMS! Now how do I use it?” Well, read on, and have a look at the overview video posted here: www.TipsFor.us
The idea with this tutorial is to give you some early success with MODx, answer some of your basic questions, and set you on the path to learn the rest of MODx yourself.
One caveat: Although this tutorial is about how to use MODx, it does get into several other areas of website building, so if you are an experienced website builder, please just skip those areas you are familiar with.
Everything in this tutorial template involving location and appearance on the webpage is done with a Cascading Style Sheet (CSS) file. If you don't know CSS - learn it. It is the future. This tutorial will introduce you to some CSS usage. Use caution when making changes to the CSS file – go slow and check to see what you did. Webpages can break in the browser very easily if you do the wrong thing with the css. Before you make any changes to the css file, make a backup copy of it while it still works.
If you have the template open in a browser, you can make changes in the CSS file in your editor, save the CSS, and then do an F5 in the browser to refresh the page and see the results of the CSS change immediately.
So, then—let's get into it.
Before you install MODx
Several prerequisites come to mind:
- It's best to have a functional webpage to create a template for MODx. Note: You do not need an entire site, just one page containing the layout of what your site will look like. Because MODx essentially relies on substitution to create dynamic pages, if you find a site you like, view the source. If you're able to see all the HTML and style sheets, chances are you'd be able to use the site's source code as a starting point for your own MODx template.
- You must have access to a web server, either local (localhost) or remote (A server you pay for access to from a hosting service).
- If you don't have a local server, you should get one as it greatly simplifies the constructing and testing of a website. You really don't have to know much about Apache (the preferred server among those who know), just go to Apache Friends and download and install XAMPP on your computer.
- You must have access to a MySQL database. The XAMPP install includes MySQL. Eventually you will need database access to the (remote) MySQL server. Discuss this with your hosting provider (ISP). See Create the modX database.
- Now you can install MODx. Be sure to take the option during install to install all the snippets – you will want them later.
Note for Mac OS X: OS X is a Unix system and it ships with Apache -- once you're in the Terminal, it is nearly identical to most Linux variants. You merely need to enable Web Sharing in the Sharing control panel. You can download the latest PHP module at http://www.entropy.ch/software/macosx/php/ and the Please configure your Apache setup securely! Download the MySQL module at http://www.entropy.ch/software/macosx/mysql/ A very convenient solution is MAMP. The abbreviation MAMP stands for: Macintosh, Apache, Mysql and PHP. With just a few mouse-clicks, you can install Apache, PHP and MySQL for Mac OS X! MAMP installs a local server environment in a matter of seconds on your Mac OS X computer, be it PowerBook or iMac. Like similar packages from the Windows- and Linux-world, MAMP comes free of charge. Download it here: http://mamp.info/en/home.php
Creating the Template
Start with a complete functional webpage
Now for the good stuff: stripping your web page. What you don't have a web page? Then;
- Get a web designer to create one for you, ($£¥€) or;
- get one you like from a CSS webpage site (CSSDrive comes to mind:http://www.cssdrive.com/ or any other website that has free templates – there are hundreds. Be sure to get the permission of the designer to use the webpage you download, unless it has a license with it that allows unrestricted use.
- or get a template from the MODx repository. Easier to use – but you won't learn as much in this tutorial.
- Or use the basic webpage I have included with this tutorial so you can get started right away.
It would also help for you to have at least a smattering of knowledge about; (X)HTML, CSS and Java script (and PHP if you want to create snippets.) If not, get ready to buy or borrow a bunch of books and refer to them when you get stuck. Cut-and-paste from other working xhtml & css markup is also a good learning tool seeing how someone else did it.
Hand coding vs Automated code generation
This tutorial assumes you are using an HTML editor – but if you don't have one, there are several fine coding editors that work great and are free.
For the Windows users there are:
- Crimson Editor ( http://www.crimsoneditor.com/) and
- Notepad++ (http://notepad-plus.sourceforge.net/uk/site.htm)
And for the Mac (and Win);
- Nvu (http://nvudev.com/)
- Textwrangler – Mac only (http://www.barebones.com/products/textwrangler/)
I would recommend that for this tutorial, that you do not use Dreamweaver or GoLive or similar web builder. Hand-coding will teach you more and it is not that hard nor arduous. In any case do not use MS Write or OOo Writer or Word Perfect as they will introduce disruptive formatting when you copy and paste from them to MODx.
What happened to my template?
One question a lot of newcomers to MODx keep asking is: Where are all the files? Most all of the documents end up living in the MySQL database where you can't see them (e.g. the templates, documents/pages, snippets, chunks, and TVs). Some additional files are on the server where you can see them (e.g. images, css files, audio files, movies, etc.).
The sample page
The sample page we are going to use for this tutorial is a page design that I started on, but never used. It is a plain, two column, fixed width, web page.
It has:
- a branding area, (used to be called header)
- two columns of content in a 2/3 – 1/3 ratio,
- a side menu and a top menu.
- a site info box (used to be called footer).
This page is a pure CSS creation! No tables. This tutorial uses as lean a page as possible so you can see better what you are accomplishing. The logo picture was taken at the Mexican resort of Mazatlan and the logo is from my website. If you have another image you would rather use that's fine as long as the dimensions are: 240 pixels high by at least 790 pixels wide. Keep the kilobytes of the image down for faster loading.
The Starting HTML markup
The page being created will look something like the image below when completed.
So let's start the conversion to MODx template by stripping out the unnecessary markup. To start off with, here is the complete markup (less the css script) used to display the page above in Firefox. For this tutorial, copy it out of this page and paste it into your editor.
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> <html> <head> <meta http-equiv="content-type" content="text/html; charset=iso-8859-1"> <title>CixDegrees.com</title> <link rel="stylesheet" type="text/css" href="[(base_url)]assets/templates/tutorial/css/style.css" /> </head> <body> <div id="branding"> </div> <!-- end of branding --> <div id="content-main"> <div id="content-text"><h2>Welcome to CixDegrees</h2> <p>Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Cras a nisi. Donec blandit, ipsum id bibendum posuere, neque magna tincidunt nisi, nec facilisis odio turpis sed odio. Donec nibh pede, tempor aliquet, vehicula eu, pellentesque vel, urna. Nullam at arcu eu eros pretium viverra. Aenean vel mi quis augue cursus viverra. Cras at quam. Pellentesque imperdiet nunc id lacus. Duis justo pede, tincidunt sed, accumsan sed, sollicitudin aliquet, dui. Aliquam sed tortor at enim volutpat convallis. Vestibulum feugiat blandit erat. Sed vel libero.</p> <p>Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Suspendisse nisi. Morbi elementum, diam ac pellentesque scelerisque, nulla nulla pharetra sapien, nec rutrum erat eros sed velit. Aenean dignissim blandit tortor. Nulla condimentum, ante quis volutpat blandit, ante lorem nonummy dui, eu fermentum nibh leo id magna. Nam tempus nisi eget orci ullamcorper venenatis. Sed in nisl. Ut vel tortor. Phasellus id diam semper enim congue tincidunt. Aenean dui neque, suscipit non, posuere ac, nonummy et, dolor.</p> <p>Aliquam elit. Aliquam quis enim. In fringilla lectus. Nullam orci justo, sagittis id, malesuada ac, cursus egestas, massa. Sed ipsum nulla, blandit quis, tempor a, hendrerit sed, libero. Nam non eros ut nisi malesuada malesuada. Aliquam mauris. In hac habitasse platea dictumst. Proin rhoncus volutpat ante. Ut consequat, nunc nec tempor vulputate, turpis neque nonummy nisl, quis iaculis ante mauris a tortor. Nulla facilisi. Sed lectus justo, laoreet non, elementum sit amet, laoreet et, augue. Ut odio velit, tristique pellentesque, luctus et, varius a, ante. Donec aliquam. Cras ipsum nunc, feugiat cursus, tincidunt eu, molestie et, diam.</p> </div> <!-- end content-text --> </div> <!-- end content-main --> <div id="content-sub"> <div id="content-sub-title"><h2>News</h2> <p>Lorem ipsum dolor sit amet, consectetuer adipiscing elit.</p> </div> <!-- end content-sub title --> <div id="navigation"> <ul> <li class="active"><a href="/home" title="Home" >Home</a></li> <li><a href="/blog" title="Blog" >Blog</a></li> <li><a href="/services" title="Services" >Services</a></li> <li><a href="/search" title="Search" >Search</a></li> <li><a href="/misc" title="Misc." >Misc.</a></li> <li><a href="/about" title="About" >About</a></li> <li class="last"><a href="/login" title="Login" >Login</a></li> </ul> </div><!-- end of navigation --> </div> <!-- end content-sub --> <div id="site-info"> <p>Copyright© 2007 CixDegrees.com - Powered by MODx - Hosted by (mt)MediaTemple</p> </div> <!-- end of --> </body> </html>
Note: The menu works, although it was not linked to anything, otherwise it is a functional webpage.
The Head Section modifications
First add one line to the head section right below any meta lines :
<base href="[(site_url)]"></base>
This sets the base URL for other use, like locating images, etc. It gets the URL from: MODx / Access / templates / from information you entered as you set up MODx.
Note: In order to avoid some serious Javascript issues in IE6, do not use the short form, i.e.
<base href="[(site_url)]" />
Second, strip out whatever was between the “title” tags and replace it with two MODx tags:
<title> [*pagetitle*] | [(site_name)]</title>
This will get the page title and site name respectively, from the “Title” you will input in the “Create/Edit' document screen, and “Site name” from the “Tools->System->Configuration" page. (Wait a bit and this will become more clear. I promise.)
Next, add the following line in the head of the template html to reference your CSS file:
<link rel="stylesheet" type="text/css" href="[(base_url)]assets/templates/tutorial/css/style.css" />
//...base url is NOT needed in your links if you have above base href="[(site_url)] in the head section.
The Navigation Modifications
Next delete all this code in the the "navigation" div:
<ul> <li class="active"><a href="/home" title="Home" >Home</a></li> <li><a href="/blog" title="Blog" >Blog</a></li> <li><a href="/services" title="Services" >Services</a></li> <li><a href="/search" title="Search" >Search</a></li> <li><a href="/misc" title="Misc." >Misc.</a></li> <li><a href="/about" title="About" >About</a></li> <li class="last"><a href="/login" title="Login" >Login</a></li> </ul>
and replace the markup with:
<div id="navigation"> [!Wayfinder?startId=`0`!] </div><!-- end of navigation -->
The Wayfinder call explained: it is a Snippet, and the parameters are: startid=`0` this tells Wayfinder to begin the menu with document ID 0 If there is no document ID0, then it defaults to the next higher doc ID and builds the menu buttons for however many documents are visible (Not grayed-out in the document tree.)
I know what you are thinking : "How is the menu going to look like it was before?" If the navigation menu(s) was styled and positioned with the css before the conversion, then the call to the Wayfinder snippet will take that css styling and build your menu as it was before, with the menu titles and links based on the "Menu title" entries for the documents (pages) it finds in the MODx Document Tree. (See below; #The MODx Manager.) The complete documentation with all possible parameters can be found here: Wayfinder homepage
More Complex Navigation Modifications
If all that seems pretty amazing, it is. There is a non-zero chance that it won't quite work when you wave your magic wand. What the Wayfinder code is doing is printing out a bit of text (often an unordered list) whose format is determined by some small templates that are stored as Chunks in your MODx admin control panel. If you are lucky, the default operation of this will work for you, but here are two possible scenarios that will force you to make a couple minor changes to the Chunks and to your Wayfinder call. Here a couple examples that should increase your understanding of how this snippet works:
What if your CSS class for the selected item is not class="active", but rather class="selected"?
This is a simple one. Simply change your call to the Wayfinder snippet to reference the new class:
[!Wayfinder?startId=`0` &hereClass=`selected`!]
What if your menu has a separate CSS class or id for the unordered list? Or what if you aren't using an unordered list at all? You'll want to head over to Resources-->Manage Resources-->Chunks and either duplicate existing menu related chunks or create your own that look something like this:
Chunk name: my.OuterTpl
<ul class="my_style"> [+wf.wrapper+] </ul>
Chunk name: my.InnerRowTpl
<li[+wf.classes+]> <a href="[+wf.link+]" title="[+wf.title+]"><em>[+wf.linktext+]</em> </a>[+wf.wrapper+] </li>
The names could be anything, but I'm keeping the names so they match up with the variables that Wayfinder expects. Just to explain what's going on here, the my.OuterTpl chunk has the [+wf.wrapper+] bit, which is replaced with instances of the my.InnerRowTpl chunk. It's a template inside of a template. The default operation of Wayfinder is that it uses its own templates for this menu generation, but you can tell Wayfinder to use your chunks instead:
[!Wayfinder?startId=`0` &hereClass=`selected` &outerTpl=`yui.OuterTpl` &rowTpl=`my.InnerRowTpl`!]
Notice that you specify the names of the chunks to use in the &outerTpl and &rowTpl parameters. At first, this organization may seem really weird, but after you've got it plugged in and working, you can see that this design provides a lot of flexibility. In this way you can create chunks for any number of menu styles (e.g. tables, other CSS classes, etc.) and you can still use Wayfinder to generate all of them.
Orientation of the Menu
Examine the CSS styling fragments below for the "menu" div and the "navigation" div in the CSS file "style.css";
LINK TO THE "STYLE.CSS" FILE IS LOCATED AT BOTTOM.
The Horizontal menu:
#menu ul li { display: inline; }
and the Vertical menu:
#navigation ul { display: block; }
Essentially the difference between a horizontal menu and a vertical menu is in the css styling of the ul tag. The horizontal menu "ul" is "display: inline;" and the vertical menu "ul" is "display: block;" (actually it defaults to the block display) I've commented the file "style.css" so you can play around with changing some of the styling to see what that will do to the menus. (please - only change number values, unless you are familiar with css.) You can play with the Wayfinder parameters also to see what they do beyond just the basic ones used here. This should get you started on menus. documentation on Wayfinder can be found here: http://wiki.modxcms.com/index.php/Wayfinder
If you look at the installed MODx demo site you will see a number of pages (you see them in the document/folder tree on the left hand side of the MODx Manager page. i.e.; "Home", "Blog", "Design", "Register with us" etc.)
Backing up
BACKUP,BACKUP,BACKUP,BACKUP,BACKUP!
Nothing will give you the 'OS' moment (if you don't know what a OS moment is PM me.) like discovering that the code you just over-wrote /erased / deleted was your best and only working copy that will take you days to recreate. (Did you try CTRL-Z to recover it?) This tutorial is not going to discuss all the nomenclature and syntax of the MODx tags used in this tutorial. You can do that later, with the on-line documentation at the MODx site.
The MODx Manager
Let's digress in the conversation for a moment.
This is a good time to explain several features of the MODx Manager's Document Tree that are not obvious at first glance.
The numbers in parenthesis along side of the document titles are the document ID's that are generated by MODx when a document is created, uniquely identifying those pages for future linking, reference,etc. By the way, the menu titles are going to be created by Wayfinder from the menu titles you input in the new document screen (unless you tell it otherwise.)
Note how some names are grayed out. This is by your choice when creating a document – there is a “Show In Menu” check box in the document “Create/Edit” screen – grayed out indicates you may have decided you don't want this document on the menu for various reasons. This “Create/Edit” screen is reached by a number of ways; when in the MODx Manager and you create a new document, ( MODx Manager->Site->New Document (which is also used to modify – edit existing documents) or by right clicking on a document name in the tree and bringing up a context menu – from which you would select “Edit Document” to also see the document screen
Now back to the modifications; Where were we? Oh yeah, we demolished the navigation. Now for the content!
The content modifications
Delete everything in the "content-text" div as shown. Don't worry about how we are going to re-fill it with content yet – that comes later. Then replace what you ripped out with the document-specific variable [*content*] as shown in the code fragment below:
<div id="content-main"> [*content*] </div> <!-- end content-main -->
There! That was easy and painless – wasn't it? CONTENT!!! “How do I get it back? Where is it? I knew I shouldn't have ripped out all that neat markup! Now if only the page had it. . . content that is.”
No worry mate, it's coming soon!
The Site-Info modifications
Now on to the Site Info (by the way, I have been trying my best to begin using Web 2.0 semantic markup. Semantic markup describes the parts of the markup in terms that best describe it's use. "Header" and "leftColumn" and "footer" are positional markup, while "branding" and "content-sub" and "site-info" are markup descriptive of what they do. It's all about access and screen readers. If you are interested in learning more about web 2.0 access, and semantic markup, read more at Andy Clarke's place: http://www.stuffandnonsense.co.uk/archives/whats_in_a_name_pt2.html
If you have to ask who Andy Clarke is – you haven't been paying attention to the web world around the globe. Next time you are in your bookseller's, look for Andy Clarke's "Transcending CSS" in the computer book section. It's the hottest selling computer book in the winter of 2006/2007
OK, now the site info (formerly the footer) – scalpel please:
<div id="site-info"> <p>Copyright© 2007 CixDegrees.com - Powered by MODx - Hosted by (mt)MediaTemple</p> </div> <!-- end of site-info --> </body> </html>
turns into:
<div id="site-info"> {{cixfooter}} </div> <!-- end of site-info --> </body> </html>
Wait where did all the actual information go? Well we transplanted some of it (the fixed information – and all of mine was fixed.) into a chunk. CHUNK? A chunk is a code/html markup fragment that we want to have MODx insert into our web page at some specific location and then to have the browser display it. Why? So that we can separate the code/markup of the webpage from content of the page. For example the cixfooter chunk consists of this markup:
Copyright © 2007 CixDegrees.com Design by hjd <a href="http://www.cixdegrees.com">cixdegrees.com</a> Powered by MODx Hosted by (mt) Media Temple</div>
Why not leave it in the template? You could and it would work fine – the only problem is that if you have a number of different sites and documents (pages), and you needed site info changes, you would have to change each individual document for any change in the site info. This way you only have to have one site-info chunk and call it in whatever document you need it in and if it needs a change, then you only have to do it one place. Neat. That's what MODx is all about.
Of course when you create your template, you are going to make all the variables to reflect your own site (i.e.{{cixfooter}} to {{yourfooter}})Do the following steps to create the chunk:
Resources->Manage Resources->Chunks->new Chunk
In the chunk name enter "cixfooter" (for this demo, without the quotes of course), enter a description, pick a category for the new chunk and copy it from the markup fragment above and, paste this markup into the "Chunk code (html):" window. Click on "Save". For now that is all the chunks we will need to enter.
The Results
Here is what we have for our complete MODx webpage template: (drum roll please.) The MODx calls are highlighted.
Not much to it is there? There is more we could add (and will later) but for now all you need is “proof of concept” - does it work and how does it look – then we'll talk about adding content back into it.
What it's all about Alfie? Placeholders.
Here is a partial list of placeholders used by MODx. For a more complete reference of what placeholders are used by MODx, please refer to Placeholders_used_by_MODx_Pages_and_Templates
- [(site_url)] - A “setting” which takes the URL as determined during the MODx installation and inserts it in the html at run-time.
- [*pagetitle*] - A “Template Variable” which takes the page title as entered in the “document setting” screen of the Manager, and inserts it in the html at run-time.
- [(site_name)] - A “setting” which takes the site name as determined during the MODx installation and inserts it in the html at run-time.
- [(base_url)] - A “setting” which is based on the URL as determined during the MODx installation and inserts it in the html at run-time.
- [!Wayfinder? &startId=`0` &level=`1`!] - Explained above.
- [*content*] - A “Template Variable” which enables a rich text editor (TinyMCE or FCKEditor) to allow the entry of content to the document (page). Content can be a wide combination of text, html markup, images, various media, etc. (See- I told you I'd tell you all about adding "content".)
- [!Wayfinder? &startId=`0`!] - Wayfinder is a snippet which builds a menu for the website navigation as described above.
- {{cixfooter}} - This is a chunk, which inserts pre-formatted text and html markup into the page at it's location.
Getting ready to see it Work
Take the modified html, and put it into MODx to become a template. Here is how:
Login in to the MODx Manager screen. Once the manager is open, on the top set of tabs,
- click on "Resources" to open that screen. Once it is open,
- click on "Manage Resources" and then, on the lower tab set,
- click on "Templates" and then,
- click on "New Template".
In all subsequent directions I will just show it this way: Resources->Manage Resources->Templates->New Template.
From your coding editor, copy the template and paste it into the window marked: "Template code (html)" Don't hit save yet. Go up to the input box "Template name:" and enter a name for your template. I used "tutorial". You can use whatever you want. In the next box - "Description:" enter whatever description you like. I entered: "A tutorial template to play with". Then pick a category to classify the template – I didn't find one I liked, so I entered a "New Category:" which I call "Template Tryout" Now click on a "Save" button. Next, you need to navigate to your MODx root folder on your server (on a remote server it is often: domains->HTML, while on a local server it might be: xampp->htdocs->modx-0.9.5). Then navigate as follows: MODx-0.9.5->assets->templates and, inside the templates folder, create a folder (call it "tutorial" for example) and then, enter that folder and, create two folders inside of the tutorial folder; "css" folder and "images" folder.
Place the logo image, cixlogo-tropic.png into the image folder (assets/templates/tutorial/images)Get it here: Media:cixlogo-tropic.png Copy the css script file: style.css in to your code editor. Get it here: Media:style.css You may have to make a change to the css file so MODx can find the logo image. If you use the folder name suggested and the supplied image, you won't need to make any changes. The css file call for the logo image has to reflect that the css file only looks outwards from the css folder for it's URLs so it only needs this:
/* ===== BRANDING ===== */ div#branding{ height:250px; background: url(../images/cixlogo-tropic.png) no-repeat 0 0; }
(two directory dots because it is first up from css one directory (.) into tutorial and then back down into the images directory (.) for a total of 2 dots preceding the slash.)
Copy and paste the file "style.css", into the assets/templates/tutorial/css as "style.css" .
The css script could use a lot of work to clean it up and refine it – but it works as is.
Running the Pre-Flight Check-List:
Where we are: OK, now we have the template in MODx.
- We checked to be sure the link for style.css in the template html was;
[(base_url)]assets/templates/tutorial/css/style.css
- We checked to be sure we put style.css in the tutorial/css folder.
- We checked to be sure we put cixlogo-tropic.png in the tutorial/images folder.
- We for sure entered the site-info chunk in MODx and named it cixfooter.
Now go to Manager->Tools->Configuration and enter the following information;
- In Site Name at the top of the screen: enter a name for the site.
- Then scroll down to Default template and using the drop-down list select the Tutorial template.
- Then check the Reset all pages to use the Default Template radio button.
- Scroll to the top of the page and click on Save.
Then click on the Site tab and,
Run the Template
- Now jump up, hop over your monitor and twirl three times and click your heels!
- Then click the Preview button.
TA DA! IT LIVES AND BREATHES! IT'S WONDER SITE!
There is is in all it's ragged glory, with nothing in the content area yet, but look at that menu! Click on it and notice how it takes you to all the MODx demo pages. Not much to look at yet – but it's a start. Play with the menu – note how some documents break the page. The css file will have to be refined for those pages – or perhaps there is no styling info for them yet in style.css – but it is fixable. The main thing is: we now have a working template and we know how we did it.
A Primer on the MODx Manager
Go to the MODx Manager (I'm just going to call it manager from now on) and in the document tree, right click on the “Home” page and select “Edit Document” from the pop-up menu. Look at the information on this page – You can change all or any of the text in the boxes. For now leave is as is.
There are several items to note on the page;
One is “Uses Template” Which ever template is selected in this box will be the template for this page. You could in fact select different templates for each page if you wish, but that would destroy any visual cohesiveness to the site. For now “tutorial” is the template for all pages, because if you remember (you do remember don't you?) back on the Tools->Configuration page you selected “Reset all pages to use Default template ” After a while you might have quite a few templates to choose from.
“Menu title” The text you place in this box will become the title on the menu button for this page.
“Menu Index” This number sets the document position on the menu. By visiting each document and changing this number you can re-arrange the menu sequence. Home of course usually is #1.
“Show in menu ” Determines if the document will show in the menu. There are some documents you may not want to show in the menu such as; a Thank you page or a 404 Not found page. Then just make certain the box is not checked.
“Document parent” Where in the tree do you want the document to be? For organizational reasons you will probably need to change the “Parent” document for this document and you do it here. There are two ways to select the parent doc, just accept the default parent or click on the button and then in the tree click on the doc you want to be this doc's parent. Simple. You can later change the parent if it suits your needs.
Now drop down below the text entry box to “Editor to use” On a default install of MODx you will probably only find “None” and “Tiny MCE” . What the MODx install documentation neglects to tell you is that you should download and install the powerful FCKEditor (all one word – looks slightly obscene doesn't it?) Get it here: http://www.fckeditor.net/ (it's free)
After it is installed you will find the FCKEditor in the drop-down list as well. It is a nice editor, with very nice content insertion features. It can take a while to learn all the ins and outs of it. The TinyMCE editor has some nice features to use during site development; it allows you to edit content from the web. For this tutorial select the FCKEditor editor.
Now for the Pièce de résistance! While you have the document edit screen open, note the tabs at the top of the page. We have been working in the “General” tab. Go to the “Preview” tab and note how Quick Edit has placed small gray buttons at various places on the page view. When you click on them, they allow you to edit content directly. For example click on the gray button labeled “content”. (there are two places you could do that; at the top of the page in the QE button bar, and lower down on the page note the button place at the end of the current content text labeled “<< edit content”.
Clicking on the top button will present you with a list of options you could want to edit, while the button near the text will directly open a pop-up window with a rich text editor. Just in-case you are wondering on how to get the Quickedit menu off your page – go to the Quickedit bar and click on the right side “Go” and take the “logout” item from the menu. Good bye Quickedit. Start entering your content. Type, type, type. Come on you wanted “content”! - keep typing.
How to get your content looking like you want it: In the document tree, right click on the document you want to work on the content of an select “edit” from the context menu. Use the formatting features of FCKeditor to enter text, images, media and some html markup. You will have to read up on the editor tool bar and then experiment with it. Later additions to the tutorial will include demonstrations of content entry.
CSS
I will also do some elementary css stuff; showing how to change the space around paragraphs, images, position menus etc. by adjusting the margins and padding. The css file is heavily commented for your edification and enjoyment.
Wisdom and Learning
Now is a good time to pause from our labors in the fields of Webdom and go to the MODx site and look up, and read some of the relevant documentation on what we have done so far.
Now that you can see it work, the docs will make more sense. Here is your homework:
- Research what [(site_url)] is for and what kind of MODx tag & it's syntax is. (a Setting)
- Research what [*pagetitle*] is for and what kind of MODx tag & it's syntax is.
- Research what [(site_name)] is for and what kind of MODx tag & it's syntax is.
- Research what [*content*] is for and what kind of MODx tag & it's syntax is.
- Research what [!Wayfinder? &startId=`0`!] is for and how it works & what it's syntax is. Look up the options we could have used. Experiment.
- Research what {{footer}} is for and what kind of MODx tag & it's syntax is.
For additional study (and you thought you were done!) look up, and read the documentation on the following subjects:
- Wayfinder (the menu snippet)
- Ditto (used for part of blogging)
- NewsPublisher (same)
- Jot (keeps blog comments in order.)
- AJAX Search (duh!)
- Breadcrumbs (track present page location and show it for your user.)
- Maxi Gallery (images on your site)
- Maxi gallery Solo (same)
- SmoothGallery (same)
- Sitemap (search in the forum) (for Google spider help)
- See Friendly URLs Guide (same)
- See Basic Blog (just to know how)
Adding Features
OK on with the show! How about adding some breadcrumbs (are we there yet?). Simple. Copy some code from the Breadcrumbs documentation and there we are.
<div id="breadcrumb">[!Breadcrumbs? &maxCrumbs=`2` &showCrumbsAtHome=`0`!]</div>
and paste it into the template.html so it will show up some place, for example, up high on the page. Looking at the page in the browser, it looks like there is room at the top of the branding div above the logo image. Here is what I mean by that; if you look in style.css at the “branding” div:
div#branding{ height:250px; background: url(../images/cixlogo-tropic.png) no-repeat bottom; }
You will note that the height is 250 pixels but the logo image is only 240 pixels high giving us 10 px at the top to play with.
If you are not yet familiar with css, what this div (think of it as a box) tells us is: it has a height of 250 pixels and since the image it contains is 770px wide, it is by default 770px wide also. The background of this div, is set to an image ( cixlogo-tropic.png), it doesn't repeat, and is placed at the bottom of the div box.
Let's put the breadcrumbs there and see if it works.
<div id="branding"> [!Breadcrumbs? &maxCrumbs=`2` &showCrumbsAtHome=`0`!] </div> <!-- end of branding -->
It is a snippet, and the call is to build a breadcrumbs trail for a maximum of two levels deep (a page and it's first child level) and do not show crumbs when on the home page. OK? There are plenty more breadcrumbs parameters for you to play with in the breadcrumbs documentation. Click on Preview and . . . Hmmmmm! That's ugly!.
The font is too large, and it pushed everything down when it displayed. We can cure that. Let's surround the breadcrumbs call with a div so that we can style it with css. First add the following markup (breadcrumbs div) in bold to tutorial.html:
<div id="branding">
<div id="breadcrumbs">
[!Breadcrumbs? &maxCrumbs=`2` &showCrumbsAtHome=`0`!]
</div> <!-- end of breadcrumbs -->
<div id="menu">
we will copy some styling script from another document that works and append it onto the end of the style.css file.
/* ===== Breadcrumb ===== */ #breadcrumbs { width: auto; /* makes the div the entire width of the surrounding container.*/ height: 0.6em; font-size: .6em; color: Black; }
Save the css file and then do an F5 to reload the page in the browser and – It works! Quickedit is in the way but you can see the breadcrumbs behind it. The css needs to be tweaked for position and font size and perhaps color – but it works. Now go read the Breadcrumbs docs and see what else you can do with it.
Still more additions
We are beginning to dress out the page now. Let us add something into the content-sub div under the navigation. Perhaps some blog summaries, or news headlines. Copy the code below.
<h3>Stuff</h3> <p>[[Ditto? &summarize=`3` &total=`3` &startID=`2` &tpl=`news`]] </p> </div> <!-- end of content-extra -->
And paste it in the template just under the end of the "navigation" div.
What do you know? I works! The text that shows up for "summarize" in the Ditto call is whatever you typed into the "Summary (introtext)" box of the create/edit document->general screen.
Now we are on the way to finishing this page. Obviously there are some warts to be taken care of and I hope to show how to fix most of them.
Conclusion
This should answer most of your questions about how to get started with MODx and further enhancing the page is left for an exercise for you.
Enjoy MODx.
Categories: Misc | HOWTO | Beginners
