• View
• Edit
• History
• Attach
• Print
• Backlinks

WbFAQ

Questions answered by this recipe

• How can I include a "traditional FAQ"?
• How can I automate the process of FAQ creation and maintenance?
• I'm looking for a most flexible solution!

Description

This recipe adds advanced FAQ maintenance features to your wiki. Key features are:

• Maintain independent FAQs by using (page) groups without losing the option to combine these FAQs on one page.
• Include/combine the FAQs of different (page) groups on any wiki page.
• Create categories to structure your FAQ.
• Reorder categories or FAQ entries with a click. (Comes with "admin backend")
• Highly configurable to fit your needs. (See below for configurable options.)
• JavaScript driven open/close features; if JavaScript is disabled, all FAQ entries are left "open".

Each FAQ entry is stored as a single wiki page, so you can include it using (:include:), for example, to show it on another page independently. Also, after uninstalling or deactivating this recipe, you can go on using the FAQ entries like any other wiki page - you lose facilities, not content.

Note: You should never use action=edit to edit a FAQ entry while using this recipe for editing! WbFAQ includes some extra fields into the page you will lose in this case. In other words: This will break the FAQ!

A note on the above: I changed line 780 in my local copy of WbFAQ.php from:
$_POST['text'] = "(:wbfaqform group=$group item=$new_page_name:)\n
to:
$_POST['text'] = "(:if auth {$wbFAQAuthLevel}:)\n(:wbfaqform group=$group item=$new_page_name:)\n(:else:)\n[[$new_page_name?action=login | Log In to Edit]]\n(:ifend:)\n
This way it will only show the edit form if user is authorized. There may be a cleaner way, and if so please advise. This allows hot-linking to a FAQ page from another part of the wiki or email without displaying the Edit Form to those who are not authorized to admin the FAQ. - TRhodes

Installation problem resolutions by Ian K. 2012-03-08

• new questions overwriting first question FAQ-000001
  • changed WbFAQ.php line 736 from $base = MakePageName( $group, 'FAQ-' ); to $base = $group . '.FAQ-' ;
• on FAQAdmin page, Edit Entries and Edit Categories tab links not working
  • changed WbFAQ.php lines 858,859 changing & to & yielding

The skin tmpl file needs a <!--HTMLFooter--> markup near the end above the </body> tag.

Installation

Download the WbFAQ.zipΔ

• Install WbFAQ.php into the Farm/cookbook folder
• Install the forms.php into the Farm/cookbook/WbFAQ subfolder
• Install the WbFAQ.InputForm wiki page into the local wiki.d folder
• Install all other files of WbFAQ.zipΔ into the farm/pub/ folder.
• Move the wbfaq.css into the farm/pub/css subfolder.

Your result should look like this:

    ../cookbook
      |- WbFAQ.php
      |-/WbFAQ
        |- forms.php
    ../pub
      |- 1downarrow.png      
      |- 1uparrow.png
      |- 2uparrow.png
      |- arrow_down.png
      |- arrow_up.png
      |- delete.png
      |- edit.png
      |- kedit.png
      |- move.png
      |- top.png
      |-/css
        |- wbfaq.css
    ../wiki.d
      |- WbFAQ.InputForm

As for the most recipes, you include this one by adding the following line to your config.php or farmconfig.php:

    include_once( "$FarmD/cookbook/WbFAQ.php" );

You will also have to include the togglelink.php which is included in the archive. (See Notes!)

    include_once("$FarmD/cookbook/togglelink.php");

Markup

Show the FAQ

Simply add the following markup:

     (:wbfaqshow:)

By default, the name of the current group (=the group the page belongs to) is used to constitute the FAQ. But you can also define one or more groups that should be shown:

     (:wbfaqshow groups=FAQ,Hints:)

Important: If you're using WikiWords in the groups list, mask the group name with "`"!

    (:wbfaqshow groups=`FAQ2,`FAQ3:)

Show the FAQ Input form

Use the following markup to include the FAQ input form:

    (:wbfaqform:)

As for the FAQ entries, you may add an optional group name here. Note: Only one single group name is allowed here!

    (:wbfaqform group=FAQ:)

Edit FAQ entries

To modify an entry, just click at the "edit" icon shown at the bottom of the entry (on the FAQ page). You may also use the "FAQ admin".

Layout options

You may modify the wbfaq.css to fit your needs, but be careful when doing so!

I18N

To translate your FAQ (admin backend) to another language, you will have to add the strings to your PmWiki<lang>.XLPage. Here's an example for German language:

  ### wbFAQ
  'Category' => 'Kategorie',
  'Categories' => 'Kategorien',
  'Question' => 'Frage',
  'Answer' => 'Antwort',
  'show table of contents' => 'Inhaltsverzeichnis aufklappen',
  'hide table of contents' => 'Inhaltsverzeichnis zuklappen',
  'Edit Categories' => 'Kategorien bearbeiten',
  'Edit Entries' => 'Einträge bearbeiten',
  'Add category' => 'Kategorie hinzufügen',

Configuration

Most of the configuration options can be left 'as is', as I tried to set them to comprehensible defaults.

To change an option, include it to your (farm)config.php before including the WbFAQ.php.

$wbFAQCategoryToggle

Default: off

By default, only the FAQ answers are hidden, but the questions are shown below the category header with arrow icons near them. If you wish to "close" the categories, also, set this to one of '1', 'on' or 'y'.

    $wbFAQCategoryToggle = 1;

$wbFAQAutoHide

Default: 1 (=on)

Leave this to '1' if you wish to "close" all FAQ entries (and categories, if $wbFAQCategoryToggle is set to 'on') when the FAQ is shown. Note: If JavaScript is disabled, Categories and FAQ entries are always "open". To disable autohide, set this to '0' or any other value <> 1.

    $wbFAQAutoHide = false;

$wbFAQQuestListShow

Default: show

You may like to have a list of questions on top of your page. To disable this additional list, set this value to something like 'hide' or 'off'.

$wbFAQQuestListInitState

Default: hide

Close list of questions automatically if $wbFAQQuestListShow is set to 'show'. To have the list opened when loading the page, set this to 'show'.

$wbFAQEditForm

Default: WbFAQ.InputForm

$wbFAQAuthLevel

Default: admin

Can be used to change the authorization level necessary for FAQ administration. The level set here overrides settings made in (farm)config.php or GroupAttributes page.

Available settings: read, edit, attr, upload, admin

(Not all make sense...)

    Example: $wbFAQAuthLevel = 'edit';

$wbFAQCatFile

Default: $WorkDir/.wbFAQcategories

File to store category list. All categories for all page groups are stored in one single category file, which is hidden by default (on UNIX/LINUX systems).

$wbFAQIndexFile

Default: $WorkDir/.wbFAQ

File to store faq index. All faq entries* for all page groups are stored in one single file, which is hidden by default (on UNIX/LINUX systems).
(*this means "entry information" is stored there. the entry itself is stored in a wiki page!

$wbFAQGraphicURL

Default: $FarmPubDirUrl || $PubDirUrl

Base URL for FAQ icons. Useful for Farm environments. Uses $FarmPubDirUrl if set, $PubDirUrl otherwise.

Set this explicitly if you don't want to copy the icon images into all your fields in a Farm environment and/or if neither $FarmPubDirUrl nor $PubDirUrl is set in your config.

Notes

I included a forms.php to enable some advanced form field features added to PmWiki 2.2x to work with older versions, so this recipe will work with pmwiki-2.1.27, too.

I also included a patched togglelink.php to allow the usage of images as "toggle text". If you are using the ShowHide anywhere else this may cause problems. In this case, restore the original togglelink.php and store the one included in the WbFAQ.zipΔ with another name, f. e. wb_togglelink.php. Open the (farm)config.php and modify the following line:

    include_once("cookbook/wb_togglelink.php");

Why another "toggled FAQ"? Why not use FAQToggleList?

I wanted a solution that stores the FAQ questions and answers into separate files. This way, each FAQ entry can be included or referred to anywhere else in the Wiki, using the (:include:) markup, for example.

Also, in my opinion, a large(r) FAQ is much easier to maintain and reorganize if the entries are stored separately.

Anyway, maybe FAQToggleList is exactly what you are looking for. Look and see!

Known Issues

• [Cancel] button does nothing when editing a FAQ entry, so it was removed. FAQ input form opens in new window instead.

ToDo

• Add option to move or duplicate categories to another page group
• Titles for "Go to top" and "Go to category top" icons are hardcoded at the moment (=cannot be translated)

Release Notes

2009-11-02

Fixed $EnableGUIButtons issue reported by TRhodes (see below)

2009-05-12

New Variable $wbFAQGraphicURL
Some minor improvements

2009-03-17

Corrected some layout problems with $wbFAQCategoryToggle = 'on';
Made this recipe work with PmWiki 2.2.0

2009-02-20

Some new icons for page navigation
Some minor fixes

2009-02-11

First release.

• This recipe was last tested on PmWiki version: 2.2.1

See Also

FAQToggleList, PublishFAQ

Contributors

Webbird

Comments