Data Management

SolutionBase: Setting up a FAQ with phpMyFAQ

Setting up and maintaining a FAQ page on a Web site can be a chore. In this article, Jack Wallen shows how to make it easier using phpMyFAQ.

As technology becomes more complex and end users become less informed, the need for company-wide FAQs is more critical than ever. Typically, the company-wide FAQ is one of the last things thought of when the intra-net sites are created.

Fortunately for all those in need of a well-executed FAQ, phpMyFAQ is exactly what is needed. The phpMyFAQ system is a fully open source, multi-lingual, database-driven FAQ system. Currently available in thirty-four different languages, phpMyFAQ is in version 1.6, and has a team of developers any software company would be proud to boast about. In this article, I'll show you how it works.

Requirements and installation

The requirements for phpMyFAQ are straight forward:

PHP

  • >= 4.1.0 (although 4.4-5.2 is recommended)
  • register_globals turned off
  • safe_mode off

Webserver

  • Apache 1.3, 2.0, or 2.2
  • lighttpd 1.0+
  • IIS 5.0+

Database server

  • MySQL 3.23.23+, 4.x, 5.x with the PHP4 MySQL extension
  • MySQL 4.1.x, 5.x with the PHP5 MySQLi extension
  • PostgreSQL 7.2+ or 8.1.x
  • SyBase
  • MS SQL server 2000 or 2005
  • IBM DB2 Universal Database 8.2.x, 9.1.x, IBM Cloudscape, or Apache Derby
  • SQLite with PHP5
  • MaxDB >= 7.5

You'll also need to have access to the Apache document root, as well as ability to change permissions.

Installing phpMyFAQ is fairly straight-forward. The first thing you'll need to do is download the latest, stable version of phpMyFAQ. I would not recommend installing the development version, especially for a production environment.

Once you download the file, move it to your Web servers' document root. For the purposes of this article, I'll be working with Apache, so my document root will be /var/www/html. Move the file -- in my instance, phpmyfaq-1.6.11.tar.gz -- into the document root and unpack it. Once the file is unpacked, I would highly recommend renaming the directory from phpmyfaq-1.6.11 to something like faq. If you don't rename the directory, your users will have to go to www.yourdomain.com/phpmyfaq-1.6.11/ every time they want to access the FAQ. Having to type out www.yourdomain.com/faq is quite a bit easier.

Once the file is unpacked, you'll want to change the permissions of the entire directory for installation purposes. From the document root, run the command chmod -R 777. Once installation is finished, you can change the permissions settings on the directories. Depending on your environment, you might have to keep the following directories with the 777 permissions:

  • attachments
  • data
  • images
  • pdf
  • xml
  • the files data.php and config.php in the directory inc/

Once you have permissions set, you'll need to create the database to use. I happen to prefer the phpMyAdmin tool for database creation/modification. For this article, I've created a database named FAQ for my installation.

With the database in place, it's time to run the installation. Point your browser to http://location.of.server/faq/install/installer.php to begin the process of installation. At that point, you'll be greeted with a screen similar to Figure A.

Figure A

If you have questions about any of the configuration options, just press [?].

The information required is very simple. The only possible gotcha would be trying to set up LDAP if LDAP is not available. By default, the administrator login name is set to admin. The password you set will be the password used to log into the administration tool.

Once you press the Install phpMyFAQ button, the installation is quick, and you'll be given links to go to either your FAQ main page or the administrator's page. Let's take a look at what the administrator's page has to offer.

PhpMyFAQ administration

The administration page, seen in Figure B, offers quite a bit of configuration. On the left-side navigation are all of the links to the various tools you'll need. The very first link, Startpage, should actually be titled "Statpage" because that's all it really is. This page gives a quick glimpse to system information, visits, articles, comments, open questions, and online version information. Although not nearly as useful as many of the other tools in the system, it's a good place to check for any open issues.

Figure B

You administer phpMyFAQ here.

Although it's not the first link in the navigation, the first link you'll want to take care of is the Edit Configuration link. It's here that you can change various aspects of your FAQ page. There are a lot of details on this page to take care of. Here's the list of information you'll want to take care of:

  • Language-file: The language your site will use.
  • Enable automatic content negotiation: Enable this to enhance the search function of the site.
  • Title of the FAQ: The title of your FAQ site.
  • FAQ version: The version of phpMyFAQ you're using.
  • Description of the page: Describe your FAQ for your users.
  • Keywords for spiders: You may or may not want to use this depending on whether your FAQ is for an intranet or the Internet.
  • Name of the publisher: Could be a single user or a company.
  • E-mail address of the admin: Self explanatory.
  • Contact information: Contact information for your company.
  • Copyright text for the Startpage: This will be the copyright information displayed on the homepage of the FAQ site.
  • Text for the send2friend page: This will be the text that will be sent via messages to other users from the site.
  • Maximum size for attachments in bytes (max. 2048MByte): Self-explanatory.
  • Link the attachments below the entries?: Do you want attachments linked below the FAQ entry?
  • Use tracking?: Track what users are doing.
  • Use adminlog?: Record events to a log file.
  • Do you want the IP to be checked when checking the UINs in admin.php?: This is an added security feature.
  • Number of displayed topics per page: How many topics do you want to appear on the front page?
  • Number of news articles: How many news articles do you want to allow per page?
  • Ban these IPs: A list of IP addresses you want to block.
  • Should the template engine parse PHP code? (default: disabled): If this is enabled it will put a big hit on your server.
  • Activate mod_rewrite support? (default: disabled): Use this if you want to have your FAQ to be housed directly in the document root instead of in the FAQ directory.
  • Do you want to enable LDAP support? (default: disabled): Self explanatory.
  • Print user e-mail in a safe way (default: enabled): Spam control.
  • Check public form content against banned words (default: enabled): More spam control.
  • Use a catpcha code to allow public form submission (default: enabled): Even more spam control.

As you can see, there's an extensive amount of initial configuration to handle.

The next section will be the user administration page. The creation/editing of users really only serves one purpose. Anyone can view the FAQ page, but only the administrator can approve entries, add/edit entries, and so on. So you might want to create a "team" of users that will be able to handle the day-to-day functions of the FAQ site. Creating the users is simple. Once you have created the user, click on the edit button in the user listing to get to the user Rights administration screen as seen in Figure C.

Figure C

Make sure you choose user rights wisely.

When dealing with user permissions, I ran into a snag that took me a while to figure out. I had set up a user to aid in the administration of the FAQ, but the user wasn't able to add entries. It wasn't until I gave that user permission to edit entries that the user was able to completely add entries. In the world of phpMyFAQ, a user must be able to edit an entry before it can be added. This holds true with news and category as well.

Content is king

The next step will be to add a category. Without categories present, no records can be entered. So let's begin the content phase of your FAQ set up with the creation of categories. Categories are created from the Category Administration page. Once you are there, you'll see an Add Category link. Select that to create your first category.

I start my process by adding a Linux category. Once the category is entered, it's possible to create an entry. Select the Create Entry link and you'll see a page broken into three sections. The first section, FAQ record, will be the actual content of the FAQ entry. Here you'll choose a category, write a Theme (the actual question the FAQ will answer), and create the Content, shown in Figure D below.

Figure D

This first section is the meat of the individual record.

In the Record section of the Create Entry window, you'll have to enter and format all of your text. It's here you'll want to spend the most time on your entries. You can format text, add images and links, strip formatting from copied document text, and give the entry keywords and authorship.

Your next step is to fill out the Record administration section, as shown in Figure E. This is one of the key ingredients to getting a record online. See the Active toggle buttons? In order to actually have the record appear online, you have to toggle the Yes button. Only users who have edit permissions can do this.

Figure E

From this section you can also choose to allow user comments.

The last section is the ChangeLog section. The only thing the ChangeLog allows you to do is add text describing any changes made to an entry.

Once you finish entering all the necessary data, select Preview to see what the entry will look like; or, just press Save to save the entry to the database. When a user views the entry, the user will be able to print the record, send the record to a friend, export the record to PDF, export the file to XML, or rate the record.

Submitting questions

One of the nicest features of this system is that it allows viewers to submit questions. As you can see in Figure F, the question submittal form is simple and includes spam prevention.

Figure F

The user can submit questions to specific categories, which will make the administrator's life easier.

Once the question has been submitted, it will be mailed to the administrator and appear in the Edit Open Questions screen from the administration window, as shown in Figure G.

Figure G

The authorname link is just a mailto link.

By selecting the Take Question And Edit link, you are opening up the edit screen. Once you've opened the question for editing, just fill in the missing blanks. If you don't think the question is worthy of being on the FAQ page, simply delete it.

Final thoughts

The phpMyFAQ system is an amazing tool to use to set up your companies FAQ page. By employing this system, you'll have a robust FAQ system and an efficient means of adopting a company-wide online Q&A system. The developers of phpMyFAQ should be commended for creating such a nice, user-friendly tool.

About

Jack Wallen is an award-winning writer for TechRepublic and Linux.com. He’s an avid promoter of open source and the voice of The Android Expert. For more news about Jack Wallen, visit his website getjackd.net.

2 comments