EZfaq Snippet Tutorial

I could tell you how many hours it takes to develop a MODX extra Transport Package complete with a build script, properties, multiple MODX elements, internationalized strings, error checks, and then fully test it, but you wouldn't believe me. If you use this extra and like it, please consider donating. The suggested donation for this extra is $5.00, but any amount you want to give is fine (really). For a one-time donation of $50.00 you can use all of my non-commercial extras with a clear conscience.


PayPal

I've chosen this as one of the first snippet tutorials because EZfaq is one of the easiest snippets to use. EZfaq creates a slick, attractive, FAQ page with expanding and contracting answers like the one here.

Upgrade note: The property for specifying the CSS path (&cssPath) has been changed to &ezfaqCssPath and the &docID property has been changed to &ezfaqDocID. This was done to avoid potential conflicts with other components.

Installing EZfaq for MODX Revolution 2.0.0 and Beyond

This couldn't be much easier. Just go to System | Package Management on the main menu in the MODX Manager and click on the "Download Extras" button. That will take you to the Revolution Repository (AKA Web Transport Facility). Find the EZfaq snippet and put a check next to it (it should be under "Content," but the last time I looked it was misfiled in the Communication section). Check any other packages you might want to install and click on "Finish." That should bring you back to your Package Management grid. Click on the "Install"button next to the EZfaq Package and follow the steps. When you've finished, the EZfaq snippet should be installed.

If you chose to install the sample FAQ (highly recommended) you should see a Resource called FAQ and, under it, an unpublished resource called FAQ Content. You can follow along with the rest of this tutorial, but most of the work will have been done for you. You may want to change the Title, Longtitle, and alias of your FAQ document and, of course, you'll want to put your own content in the FAQ Content document (which you'll want to leave unpublished). Be sure to read the sections on Creating the FAQ Content Document, and Customizing the FAQ page.

Installing EZfaq for MODX Evolution and earlier

The first step is to go to the MODX Repository here and download EZfaq.zip to your computer.

Next, extract the contents of the EZfaq zip file to your assets/snippets directory. The files should end up in a directory called /assets/snippets/ezfaq.

Make sure all the files are there. You should see this structure:

  • Images (folder)
    • check.png
    • minus.png
    • minus2.png
    • plus.png
    • plus2.png
    • x.png
  • Lang (folder)
    • en.inc.php
  • ezfaq.css
  • ezfaq.inc.php
  • readme.txt
  • switchcontent.js

Creating the Main FAQ Page

Now let's create a page to display the FAQ items. Note that this page won't hold any of the FAQ content, just the snippet tag that fetches them.

Launch the MODX Manager, (log on with https://yoursite.com/manager).

Select the Site tab near the top of the page and click on New Document.

Fill in the fields on the document editing screen as follows:

ezfaq-image1

The Menu index number tells MODX where to show this document in the menu. If you'd like your FAQ to be at the end of your menu, for example, you can put 99 in the Menu index box. If you're not sure, don't worry, you can come back to this page and change it later.

Look at the top of the Create/edit document window (scroll up if you have to). You should see three tabs like the ones below:

ezfaqtutorial-image2

Click on the Page Settings tab.

This tab allows you to set some of the characteristics of the document we're creating. Check the Container checkbox. We're going to put the FAQ Content Document below this one in the tree. It could go anywhere, but putting it below this document will make it easy to find.

The Published checkbox determines whether visitors to your site will see the document or not. You might want to leave it unchecked until you're done creating the FAQ content. If you leave it unchecked, you'll have to come back here and check it to make the page visible to visitors. If you don't care if people see the unfinished page, you can check it now.

Notice also, the Published date and Unpublished date boxes. If you'd like to have a page appear and/or disappear from the site, you can put dates in these boxes by clicking on the little calendar icon next to each box. You can try these now if you like. You can remove the date by clicking on the other calendar icon (the one with the red circle and slash over it).

Make sure the Show in menu checkbox is checked.

Next, scroll down to the Document content window and paste in the following line:

[[EZfaq? &ezfaqDocID=`##`]]

The "##" is just temporary. We'll replace it with the actual document ID of the FAQ contents document, once we know what it is.

Now, scroll up to the top of the page and click on Save.

Creating the EZfaq Snippet

Now we'll create the actual snippet that displays the FAQ by creating a new snippet in the Manager and pasting in the EZfaq code.

In the MODX Manager, create a new snippet (Resources | Manage Resources | Snippets | New Snippet). Use EZfaq for the name of the snippet. Be careful how you spell it, snippet names are case-sensitive and must be spelled exactly the same way in the snippet name and the snippet tag you place in a MODX document.

To fill the content of the snippet, there are two ways to go. The first is the most foolproof:

  1. Find the ezfaq.inc.php file (in the /assets/snippets/ezfaq directory). Highlight the code in that file and copy it into the body of the snippet you just created. Click on "Save."
  2. Put the following in the body of the new snippet and save it:
    <?php
    return include 'assets/snippets/ezfaq/ezfaq.inc.php';
    ?>

Creating the FAQ Content Document

If we looked at our FAQ page now, there would be nothing to see because we haven't created any content for it yet. We just created a document using one method. In MODX, there are often several ways to accomplish the same thing. Now we'll create a new document using another method.

Find the FAQ page you just created in the Resource tree at the left of the screen. Right-click on it and select Create new document here. This will take you to a new Create/edit Document screen. This new document we're creating will hold the actual content of the FAQ.

Fill in the fields to match the screen shot below:

ezfaqtutorial image3

Be sure that the Show in menu checkbox is not checked. You don't want to show people the raw FAQ, you want to have it displayed by the EZfaq snippet we put on the other page.

Now scroll up and select the Page Settings tab as you did before and make sure the Published checkbox is unchecked so this page can't be viewed directly. Uncheck the Searchable checkbox — you don't want this page to show in site maps of site searches.

Scroll back down so you can enter the content of the FAQ. EZfaq makes this really easy. All you have to do is enter a series of questions and answers like these:

ezfaqtutorial-image4

Make sure that the list starts with Q: and that there is an A: for every Q:. Use capital letters for the Q: and A: and don't forget the colons, they're important. Notice that there is no space after the colon, EZfaq will take care of the spacing. Be sure your list ends with Q:FAQ-END with no spaces and all caps. That tells EZfaq that it's the end of the part you want to dispay. You can use the questions and answers above or create your own, but don't try to paste the ones above into your new page because the ones here are an image rather than text, so they can't be cut and pasted.

When you're finished adding your questions and answers, scroll up to the top of the page and click on Save. Take a look at the Resource tree at the left. You should see your main FAQ page and, under it, the FAQ content page we just created. The FAQ content page should be grayed out because it's not published. Make a note of the document ID of the FAQ content page (the number in parentheses next to the page name). We'll be using it in just a minute.

If you left the main FAQ page unpublished, go back now and publish it and correct the &ezfaqDocID property in the snippet tag. Be sure you're publishing the main FAQ page (the one with the snippet tag on it) not the FAQ content document we just created. To publish the main FAQ page, right-click on it in the Resource tree and select Edit document from the list that appears.

On the Create/edit document screen on the right, scroll down and replace the "##" in the snippet tag with the document ID of the FAQ content page. Scroll up and select the Page Settings tab and make sure the Published checkbox is checked. Notice the radio buttons at the top of the Create/edit document screen:

ezfaqtutorial-image5

These determine what happens after you click on the save button. Click on the Continue editing button. This will save us a step by keeping us at the Create/edit document screen after we save the document.

Click on Save. You should now have a working FAQ page. You should also see a new tab at the top of the Create/edit document screen: Preview. Click on the Preview tab now and you should see your FAQ page. Notice that when you put the mouse over a question, it turns into a hand cursor. If you click on the question, the answer automatically appears. You can also show or hide all the answers by clicking on one of the boxes at the top of the screen.

Using Flash Videos and Lightbox

An answer in EZfaq can be in the form of a Flash video using the swfObject Snippet (get it here) and the following format:

Q:How do I play Flash in here?

A:[[swfObject? &swfid=`0` &swfFile=`assets/flash/playback.swf` &swfWidth=`325` &swfHeight=`155`]]

For a lightbox image, use:

Q:How do I work with lightbox?

A:<a href="https://domain.com/assets/images/small-pic.jpg" rel="lightbox"><img src="https://domain .com/assets/images/large-pic .jpg" alt="" width="120" height="120" border="0" /></a>

Customizing the FAQ page

There are some things you can change on the FAQ page by editing the EZfaq.css file or by adding properties to the EZfaq snippet tag.

The .CSS file is called ezfaq.css and you can find it in the assets/snippets/ezfaq directory of your site. The main changes to be made here are to the colors of the elements on the page. Comments in the .CSS file will let you know what the foreground and background colors refer to. Making changes to the spacing and margins of the FAQ is difficult and may not work the way you expect because the effects are created with Javascript so many of the .css directives are ignored.

If you want to change the CSS, make a copy of the ezfaq.css file (with a different name) and use the &ezfaqCssPath property in the snippet tag to point to it.

You can also change the look of the page with properties in the snippet tag. Here is a list of the EZfaq properties and what they do:

PropertyEffectDefault
&lang Language for error messages/prompts `en`
&showHideAllOption display the show/hide all buttons `true`
&statusOpenHTML symbol to put next to open topics (can be an image URL) `[-]`
&statusClosedHTML symbol to put next to closed topics (can be an image URL) `[+]`
Note: To use a URL replace the "=" sign with "EQUALS" in the snippet tag
Example: &statusOpenHTML=`<img srcEQUALS"assets/snippets/ezfaq/images/minus.png">`
Example: &statusClosedHTML=`<img srcEQUALS"assets/snippets/ezfaq/images/plus.png">
&openColor color for open questions (name or hex value #ffffff) `red`
&closedColor color for closed questions (name or hex value #ffffff) `black`
&setPersist does open state persist across visits/reloads `true`
Note: setPersist doesn't seem to work when all answers are expanded, only when one is.
&collapsePrevious If set, only one answer can be open at a time `true`
&defaultExpanded expand answers n1 through n2 when page is opened `none`
Example: &defaultExpanded=`0,1` expands items 1 and 2; &SetPersist and &collapsePrevious must be off

 

My book, MODX: The Official Guide - Digital Edition is now available here. The paper version of the book is available from Amazon.

If you have the book and would like to download the code, you can find it here.

If you have the book and would like to see the updates and corrections page, you can find it here.

MODX: The Official Guide is 772 pages long and goes far beyond this web site in explaining beginning and advanced MODX techniques. It includes detailed information on:

  • Installing MODX
  • How MODX Works
  • Working with MODX resources and Elements
  • Using Git with MODX
  • Using common MODX add-on components like SPForm, Login, getResources, and FormIt
  • MODX security Permissions
  • Customizing the MODX Manager
  • Using Form Customization
  • Creating Transport Packages
  • MODX and xPDO object methods
  • MODX System Events
  • Using PHP with MODX

Go here for more information about the book.

Thank you for visiting BobsGuides.com

  —  Bob Ray