Bob's Guides

EZfaq Snippet Tutorial

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-premium extras with a clear conscience.

EZfaq creates a FAQ page with expanding and contracting answers like the one here.

(Jump to EZfaq Snippet Properties Table.)

EZfaq is one of the first MODX extras I wrote (~2011). I wrote this page for people like me who were new to MODX. If you are an experienced MODX user, you already know much of what's here.

EZfaq is now fully Compatible with MODX 3

Installing EZfaq for MODX Revolution 2.0.0 and Beyond

This couldn't be much easier:

1. go to Extras > Installer on the main menu in the MODX Manager. That will take you to Package Manager.
2. Click on the "Download Extras" button. That will take you to the Revolution Repository.
3. Put EZfaq in the search box and click "Enter."
4. Click on the "Download" button.
5. When the download has finished, click on the "Back to Package Manager" button. That should bring you back to your Package Management grid.
6. 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 (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.

If you only need one FAQ page, you can just modify the sample to meet your needs. See the following sections for selecting options, and creating other FAQ pages.

Creating an FAQ Page

Create a new resource in MODX. Note that this page won't hold any of the FAQ content, just the snippet tag that fetches it.

Fill in the fields on the Create/Edit Resource Panel, but leave the document unpublished until you've finished creating the second resource described below. Save the resource.

Put this minimal EZfaq snippet tag in the content field:

    [[!EZfaq? &ezfaqDocID=`12`]]

The exclamation point (!) means that the snippet is called "uncached," which means that the content will be regenerated on every page visit. This is desirable during development, so your changes will show up reliably. Once the page is finished, and you're satisfied with all the content, you can remove it so MODX will cache the page for faster page loads.

If this is a live site, you should check the "Hide From Menus" checkbox. Don't forget to come back later, uncheck it, and save the resource, so it will appear in your menus.

Creating the FAQ Content resource

Right-click on the resource you just created and select "Create->Document". Name this document after the one we created above, but add the word "Content" to the end of the page title.

This resource will hold the questions and answers, its content field should look like this:

This will be rendered above the first question (optional)

Q:How much is two plus two?

A:Four

Extra: This will always be rendered between questions. (optional)(Important: Be sure to use Extra:, not EXTRA:). You can have as many of these as you like.

Q:Who is the fifth avatar of Vishnu?

A:Vamana the Dwarf.

Q:What is Sigmund Freud's middle name?

A:Schlomo

(etc.)
Q:FAQ-END

Work in progress can go here and won't be displayed. (optional)

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 display. You can use the questions and answers above or create your own.

Save the page. Find the ID of the page you just saved in the tree (under the page with the snippet tag we created above) and note the ID (in parentheses next to the page title).

Now go back to the first page you created and edit the snippet tag. replace the "12" in the snippet tag with the ID of the FAQ Content page, and, if you like, change the page to published. Save that page.

At this point, you should be able to view the FAQ page (the one with the snippet tag) and see your questions and answers.

If you left the main FAQ page unpublished, go back now and publish it. 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.

You should now have a working 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="http://domain.com/assets/images/small-pic.jpg" rel="lightbox"><img src="http://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:

Copyright © 2011-2024
Bob Ray