.. You may want to use the usual include line. Uncomment and adjust the path. 
.. include:: ../Includes.txt


================
EXT: Elmar’s FAQ
================

:Author:
      Kasper Skårhøj

:Created:
      2002-11-01T00:32:00

:Changed:
      2007-07-07T01:12:43

:Author:
      Elmar Hinz

:Email:
      elmar.hinz@team-red.net

:Info 3:


:Info 4:


.. _EXT-Elmars-FAQ:

EXT: Elmar’s FAQ
================

Extension Key:  **efaq**

Copyright 2007-2007, Elmar Hinz, <elmar.hinz@team-red.net>

This document is published under the Open Content License

available from http://www.opencontent.org/opl.shtml

The content of this document is related to TYPO3

\- a GNU/GPL CMS/Framework available from www.typo3.com

.. _Table-of-Contents:

Table of Contents
-----------------

**EXT: eFAQ 1**

**Keywords 1**

**Abstract 1**

**Introduction 2**

Achived features 2

Roadmap of features 3

Screenshots 4

**Installation 9**

Overview 9

Simple FAQ 9

Dynamic Simple FAQ 9

Classical FAQ 9

Regular FAQ 10

Dynamic Regular FAQ 10

Text Search 10

**Administration 10**

Adding user defined translations 10

Adding user defined fields 10

The sources of the templates 10

**Addons 12**

**FAQ 13**

**Known Problems 13**

**TODO 13**

**ChangeLog 13**


.. _Keywords:

Keywords
--------

- Frequently asked questions (FAQ)

- Model view controlller (MVC)

- lib/div

- jQuery (DHTML)

- xajax (AJAX)

- accessibility

- XHTML


.. _Abstract:

Abstract
--------

The Elmar’s FAQis a TYPO3 extension to edit and to display questions
and answers. Technically it is founded upon the modern MVC library
lib/div. Depending on the state of the project, it will offer
everything between a single list of questions and answers up to a
multifunctional FAQ server.

The Elmar’s FAQproject is the dynamic process of this software
development. People are invited to join in the project. The first
principle is, that the project will provide a usefull product in every
state. The second principle is that questions and answers are the
leading patterns even if they will overlap with newsfeeds, forums,
wikis and blogs while the project is advancing.


.. _Introduction:

Introduction
------------

The Elmar’s FAQproject is a work in progress. It provides you in every
phase of it's proceeding with a valuable extension to maintain FAQ.
And the range of features is growing. See below which features are
already at your service and have a look into the roadmap to find out
what s additionally planned.

As soon as the basics are standing, I will define a sytem for user
contributed addon extensions, that can be incorporated into this basic
FAQ extension quickly, as soon as they prove to be of use and quality.
That will be the way to join in.

In comparism to the old tslib\_pibase based FAQ extensions the modern
lib/div based FAQ has multiple advantages. For example:

Adding userdefined fields is extremely easy. Just add new fields to
the table by the kickstarter and call them with the provided functions
in the Templates.

Adding translations is as simple. Define the translation in the
locallang files. Use them directly in the template.

Due to the clean separation of the components it is comparingly simple
to add new features, wich will soon be to your service.

If you are a developer it's possible to add your own features in a
clean way without the need to hack the extension or using XCLASS.

As soon as people start to use the planned system of user contributed
addons, the amount of features will get an additional push.

For more informations about the flexibility the new MVC architecture
see:

< `http://typo3.org/extensions/repository/view/lib/0.0.13/info/?tx\_terfe\_pi1%5BdownloadFile%5D=doc%252Flib-div-slideshow.pdf&cHash=1089a49c64 <http://typo3.org/extensions/repository/view/lib/0.0.13/info/?tx_terfe_pi1%5BdownloadFile%5D=doc%252Flib-div-slideshow.pdf&cHash=1089a49c64>`_ >If this complex link will be broken for any reason, here is the
filelist:

`http://typo3.org/extensions/repository/view/lib/0.0.13/ <http://typo3.org/extensions/repository/view/lib/0.0.13/>`_ 
Achived features
^^^^^^^^^^^^^^^^


.. _PHP-Templates:

PHP Templates
"""""""""""""

Elmar’s FAQworks with the powerfull PHP template system, which gives
you the maximal freedom to design and controll the output of the
extension.


.. _Simple-FAQ:

Simple FAQ
""""""""""

An ordered list of questions with the answer directly below each
question.


.. _Dynamic-Simple-FAQ:

Dynamic Simple FAQ
""""""""""""""""""

Like "Simple FAQ" but the answers are dynamically unfolded on click
onto the question. A second click hides the answer again. Fallback to
Simple FAQ behaviour if JavaScript is disabled.


.. _Classical-FAQ:

Classical FAQ
"""""""""""""

This is the classical presentation of a FAQ on a single page. The
questions are a list on top while the answers are a list below. You
can navigate between questions and answers by links.


.. _Regular-FAQ:

Regular FAQ
"""""""""""

One page for the list of questions and an own page to display the
answer. This is especially usefull for FAQ with long answers or those
with user added fields.


.. _Dynamic-Regular-FAQ:

Dynamic Regular FAQ
"""""""""""""""""""

Much like Regular FAQ, but the Single answer replaces the list of
questions and vice versa by ajax technology, without reloading the
whole page. Falls back to Regular FAQ behaviour if JavaScript is
disabled.


.. _Fulltext-Search:

Fulltext Search
"""""""""""""""

Filtering questions and answers be sending searchwords with a form.
Works as addon in combination with the different types of question
lists. Highlights the searchwords in the questions and in the answers.


.. _Roadmap-of-features:

Roadmap of features
^^^^^^^^^^^^^^^^^^^

- PHP Templates: Basical system setup with PHP templates (DONE)

- Simple FAQ Questions and Answers in one list (DONE)

- Dynamic Simple FAQ: Simple FAQ with jQuery (DONE)

- Classical FAQ: All on one page (DONE)

- Regular FAQ: Question list page and single view page (DONE)

- Dynamic Regular FAQ: Query list and single views with xaJax (DONE)

- Fulltext Search: Fulltext Search in all questions and answers (DONE)

- Dynamic Fulltext Search: Fulltext Search with xaJax support

- FAQ Types: Selection out of different sets of fieldtypes to combine
  the answer.

- Tags: Tagging the FAQ with keywords.

- Advanced Search: Fulltext search combined with selections out of types
  and tags

- Multiple Languages: Providing translations for each question.

- Newest FAQ Contextbox: Contentbox with a limited list of the latest
  FAQ.

- Newest FAQ List: Listview of FAQ ordered by date.

- RSS Feeds: RSS feeds of different configurable selections

- Party Framework Connector: Storing editors with the party extension.

- Multiple Categories: categories related to the pagetree to allow
  navigation by frontend menu

- Comment Addon: Adding Comments to an answer

- TOP FAQ Contextbox: Contentbox with a limited list of the most visited
  FAQ.

- TOP FAQ Listview: Listview of FAQ ordered by visit count.

- Question Submit: Sending in new questions.

- Anwsers Submit: Sending in answers (multiple answers)

- Unanswerd Questions List

- Answer Administration


.. _Screenshots:

Screenshots
^^^^^^^^^^^

|img-1|

Simple FAQ: Questions and answers in one list.

|img-2|

Simple FAQ with Text Search: Questions and answers in one list with
textfilter and highlighting.

|img-3|

Dynamic Simple FAQ: Questions and answers in one list with dynamic
foldout and foldin.

|img-4|

Dynamic Simple FAQ with Text Search: Questions and answers in one list
with dynamic foldout, foldin and highlighting textsearch.

|img-5|

Classical FAQ: A list of questions above and a list of answers below,
with links to navigate between.

|img-6|

Classical FAQ: A list of questions above and a list of answers below,
with links to navigate between, combined with the highlighting text
search plugin.

|img-7|

Regular FAQ questions: A list of questions with a link to the details
page.

|img-8|

Regular FAQ answer: A single answer on the details page.

|img-9|

Regular FAQ questions: A list of questions with a link to the details
page combined with the highlighting text search.

|img-10|

Regular FAQ answer: A single answer on the details page with
highlighted searchwords..


.. _Installation:

Installation
------------


HINT: Currently the extension is developed for UTF-8 setups.
   With other encodings it may not produce the expected results. Other encodings may be supported in future releases.


.. _Overview:

Overview
^^^^^^^^

Install the extension with the extension manager.

Create a sysfolder to store the FAQ entries

In this folder create some entries.

Create the page(s) where the FAQ will be shown.

Insert as many content elements as necessary. Each time select the
plugin Elmar’s FAQand choose the appropriate sub-plugin.

Select the FAQ storage folder in the flexform.

Make specific settings for the view you have choosen.

Include the static templateElmar’s FAQ.

Clear the cache and visit the result in the frontend.


.. _Simple-FAQ:

Simple FAQ
^^^^^^^^^^

Insert one plugin. The sub-plugin is Simple FAQ.


.. _Dynamic-Simple-FAQ:

Dynamic Simple FAQ
^^^^^^^^^^^^^^^^^^

Insert one plugin. The sub-plugin is Dynamic Simple FAQ. This feature
depends on the extension jQuery(jquery).


.. _Classical-FAQ:

Classical FAQ
^^^^^^^^^^^^^

Insert two plugins Classical FAQ Questionsand Classical FAQ Answers.


.. _Regular-FAQ:

Regular FAQ
^^^^^^^^^^^

Create two pages, one for the questions and one for the answers. The
sub-plugins are Regular FAQ questionsand Regular FAQ answer.


.. _Dynamic-Regular-FAQ:

Dynamic Regular FAQ
^^^^^^^^^^^^^^^^^^^

Just like Regular FAQ, but the sub-plugins have the names Dynamic
Regular FAQ questionsand Dynamic Regular FAQ answer. The single page
is required as fallback solution to the Regular FAQbehaviour, if
javascript is disabled. This feature depends on the extension
xaJax(xajax).


.. _Text-Search:

Text Search
^^^^^^^^^^^

Place the sub-plugin Text Searchabove one of the list of questions you
have selected.


.. _Administration:

Administration
--------------


.. _Adding-user-defined-translations:

Adding user defined translations
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

You can add as many translation markers as you like in the form of
%%%xyz%%%. Logically you need to define the translations in the
typical locations of TS or locallang files.


.. _Adding-user-defined-fields:

Adding user defined fields
^^^^^^^^^^^^^^^^^^^^^^^^^^

Build an extension with the kickstarterand choose to extend an
existing table. Your fields extend the table tx\_efaq\_faqs. Add
simple content fields like RTE, text, email, integer, date, money. In
your PHP template you can print them with the appropriate printer
functions (printAsRte(), printAsText, printAsFloat, ...). Please see
the manual with the extension key libfor details.


.. _The-sources-of-the-templates:

The sources of the templates
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Here we display the templates. If you have already some experience
with PHP it is obvious for you how to adapt the templates to your
needs. If not we recomment the tutorial for template developers
included in the manual of the extension lib.


.. _simpleFaqs-php:

simpleFaqs.php
""""""""""""""

::

    <?php $entryList = $this->get('entryList'); ?>
   
    <?php if($entryList->isNotEmpty()): ?>
    <ol class="faq">
    <?php endif; ?>
   
    <?php for($entryList->rewind(); $entryList->valid(); $entryList->next()): $entry = $entryList->current();?>
   
    <li>
    <h3><?php $entry->printAsHtml('question'); ?></h3>
    <?php if($entry->has('author')): ?>
    <p>%%%by%%%
    <strong> <?php $entry->printAsEmail('email', 'author'); ?> </strong>
    <em> <?php $entry->printAsUrl('url'); ?> </em>
    </p>
    <?php endif; ?>
    <div><?php $entry->printAsRte('answer'); ?></div>
    </li>
   
    <?php endfor; ?>
   
    <?php if($entryList->isNotEmpty()): ?>
    </ol>
    <?php endif; ?>


.. _dynamicSimpleFaqs-php:

dynamicSimpleFaqs.php
"""""""""""""""""""""

::

    <script type="text/javascript">
    // <![CDATA[ 
    $(document).ready(function(){
    $("ol.faq > li > div").hide();
    $("ol.faq > li > h3").toggle( function(){ 
    $(this).parent().children("div").show("medium"); 
    }, function(){ 
    $(this).parent().children("div").hide(); 
    }
    );
    });
    // ]]>
    </script>
   
    <?php $entryList = $this->get('entryList'); ?>
   
    <?php if($entryList->isNotEmpty()): ?>
    <ol class="faq">
    <?php endif; ?>
   
    <?php for($entryList->rewind(); $entryList->valid(); $entryList->next()): $entry = $entryList->current();?>
   
    <li>
    <h3><a href="#"><?php $entry->printAsHtml('question'); ?></a></h3>
    <?php if($entry->has('author')): ?>
    <p>%%%by%%%
    <strong> <?php $entry->printAsEmail('email', 'author'); ?> </strong>
    <em> <?php print $entry->printAsUrl('url'); ?> </em>
    </p>
    <?php endif; ?>
    <div><?php $entry->printAsRte('answer'); ?></div>
    </li>
   
    <?php endfor; ?>
   
    <?php if($entryList->isNotEmpty()): ?>
    </ol>
    <?php endif; ?>


.. _classicalFaqQuestions-php:

classicalFaqQuestions.php
"""""""""""""""""""""""""

::

    <?php if (!defined ('TYPO3_MODE')) die ('Access denied.'); ?>
    <?php $entryList = $this->get('entryList'); ?>
   
    <?php if($entryList->isNotEmpty()): ?>
    <ol class="questions">
    <?php endif; ?>
   
    <?php for($entryList->rewind(); $entryList->valid(); $entryList->next()): $entry = $entryList->current();?>
    <li> <?php $entry->printLinkedQuestionTitle(); ?> </li>
    <?php endfor; ?>
   
    <?php if($entryList->isNotEmpty()): ?>
    </ol>
    <?php endif; ?>


.. _classicalFaqAnswers-php:

classicalFaqAnswers.php
"""""""""""""""""""""""

::

    <?php if (!defined ('TYPO3_MODE')) die ('Access denied.'); ?>
   
    <?php $entryList = $this->get('entryList'); ?>
   
    <?php if($entryList->isNotEmpty()): ?>
    <ol class="answers">
    <?php endif; ?>
    <?php for($entryList->rewind(); $entryList->valid(); $entryList->next()): $entry = $entryList->current();?>
    <li>
    <h3><?php $entry->printLinkedAnswerTitle(); ?></h3>
    <?php if($entry->has('author')): ?>
    <p>%%%by%%%
    <strong> <?php $entry->printAsEmail('email', 'author'); ?> </strong>
    <em> <?php print $entry->printAsUrl('url'); ?> </em>
    </p>
    <?php endif; ?>
    <div><?php $entry->printAsRte('answer'); ?></div>
    <p><?php $entry->printUpLink('%%%up%%%'); ?></p>
    </li>
    <?php endfor; ?>
    <?php if($entryList->isNotEmpty()): ?>
    </ol>
    <?php endif; ?>


.. _regularFaqQuestions-php:

regularFaqQuestions.php
"""""""""""""""""""""""

::

    <?php $entryList = $this->get('entryList'); ?>
   
    <?php if($entryList->isNotEmpty()): ?>
    <ol class="questions">
    <?php endif; ?>
   
    <?php for($entryList->rewind(); $entryList->valid(); $entryList->next()): $entry = $entryList->current();?>
    <li> <?php $entry->printLinkedQuestionTitle(); ?> </li>
    <?php endfor; ?>
   
    <?php if($entryList->isNotEmpty()): ?>
    </ol>
    <?php endif; ?>


.. _regularFaqAnswer-php:

regularFaqAnswer.php
""""""""""""""""""""

::

    <p class="backlink"><?php $this->printBacklink('%%%back%%%'); ?></p>
    <h3><?php $this->printAsHtml('question'); ?></h3>
    <?php if($this->has('author')): ?>
    <p>%%%by%%%
    <strong> <?php $this->printAsEmail('email', 'author'); ?> </strong>
    <em> <?php print $this->printAsUrl('url'); ?> </em>
    </p>
    <?php endif; ?>
    <div><?php $this->printAsRte('answer'); ?></div>
    <p class="backlink"><?php $this->printBacklink('%%%back%%%'); ?></p>


.. _dynamicRegularFaqQuestions-php:

dynamicRegularFaqQuestions.php
""""""""""""""""""""""""""""""

::

    <?php $entryList = $this->get('entryList'); ?>
   
    <?php if($entryList->isNotEmpty()): ?>
    <ol class="questions">
    <?php endif; ?>
   
    <?php for($entryList->rewind(); $entryList->valid(); $entryList->next()): $entry = $entryList->current();?>
    <li> <?php $entry->printLinkedQuestionTitle(); ?> </li>
    <?php endfor; ?>
   
    <?php if($entryList->isNotEmpty()): ?>
    </ol>
    <?php endif; ?>


.. _dynamicRegularFaqAnswer-php:

dynamicRegularFaqAnswer.php
"""""""""""""""""""""""""""

::

    <p class="backlink"><?php $this->printBacklink('%%%back%%%'); ?></p>
    <h3><?php $this->printAsHtml('question'); ?></h3>
    <?php if($this->has('author')): ?>
    <p>%%%by%%%
    <strong><?php $this->printAsEmail('email', 'author'); ?></strong>
    <em> <?php print $this->printAsUrl('url'); ?> </em>
    </p>
    <?php endif; ?>
    <div><?php $this->printAsRte('answer'); ?></div>
    <p class="backlink"><?php $this->printBacklink('%%%back%%%'); ?></p>

To adapt the templates please copy the whole template directory into
another location that is accessible for the server but not for other
users like the editors. Set the TS setup
plugin.tx\_efaq.configuration.phpTemplatePathto the new location.


.. _Addons:

Addons
------

Addons to Elmar’s FAQare independent extensions. Addons should be done
in a way, that it will be possible to also incorporate into the
Elmar’s FAQextension as new features by simply copying the files into.
We will reflect how namings should be handled that this is possible
without a lot of renaming.


.. _FAQ:

FAQ
---

FAQs about the FAQ.


.. _Known-Problems:

Known Problems
--------------

It has been developed and tested with utf-8 only. Problems may occur
with other encodings.


.. _TODO:

TODO
----

- Some refinements and configurations of the text search

- Implementing the storage folder selection into the query.

- Configuration for non utf-8 for xajax.


.. _ChangeLog:

ChangeLog
---------

::

    07-01-11 Elmar Hinz  <elmar.hinz@team-red.net>
   
    * release 0.1.3
    * implementation of the text search
   
    07-01-11 Elmar Hinz  <elmar.hinz@team-red.net>
   
    * release 0.1.2
    * synchronization with alterations of lib
   
    07-01-11 Elmar Hinz  <elmar.hinz@team-red.net>
   
    * release 0.1.1
    * featuture: Dynamic Regular FAQ
   
    07-01-08 Elmar Hinz  <elmar.hinz@team-red.net>
   
    * release 0.1.0
    * feature: Regular FAQ 
    * documentation: update
      * status change: beta
   
    07-01-05 Elmar Hinz  <elmar.hinz@team-red.net>
   
    * release 0.0.5
    * documentation update
   
    07-01-05 Elmar Hinz  <elmar.hinz@team-red.net>
   
    * release 0.0.4
    * feature: Simple FAQ
    * feature: Dynamic Simple FAQ
   
    07-01-03 Elmar Hinz  <elmar.hinz@team-red.net>
   
    * release 0.0.3
    * more documentations 
   
    07-01-02 Elmar Hinz  <elmar.hinz@team-red.net>
   
    * release 0.0.2
    * first documentations
   
    06-12-29 Elmar Hinz  <elmar.hinz@team-red.net>
   
    * release 0.0.1
     * feature: Classical FAQ

|img-11| EXT: Elmar’s FAQ - 14


.. ######CUTTER_MARK_IMAGES######

.. |img-1| image:: img-1.png
   :alt: A screenshot of a FAQ with questions and answers in one list.
.. :align: bottom
.. :border: 0
.. :height: 486
.. :id: Grafik9
.. :name: Grafik9
.. :width: 608

.. |img-2| image:: img-2.png
   :alt: A screenshot of a FAQ with questions and answers in one list with text filter above and highlighted searchwords in the texts.
.. :align: bottom
.. :border: 0
.. :height: 335
.. :id: Grafik10
.. :name: Grafik10
.. :width: 571

.. |img-3| image:: img-3.png
   :alt: A screenshot of a FAQ with questions with one answer folded out below a question.
.. :align: bottom
.. :border: 0
.. :height: 537
.. :id: Grafik11
.. :name: Grafik11
.. :width: 594

.. |img-4| image:: img-4.png
   :alt: A screenshot of a FAQ with questions with one answer folded out below a question with textfilter and highlighted searchwords in the texts.
.. :align: bottom
.. :border: 0
.. :height: 323
.. :id: Grafik12
.. :name: Grafik12
.. :width: 580

.. |img-5| image:: img-5.png
   :alt: A screenshot of a FAQ with a list of questions above and a list of answers below.
.. :align: bottom
.. :border: 0
.. :height: 550
.. :id: Grafik13
.. :name: Grafik13
.. :width: 574

.. |img-6| image:: img-6.png
   :alt: A screenshot of a FAQ with a list of questions above and a list of answers below. Above is form of a textsearch. Some searchwords are highlighted.
.. :align: bottom
.. :border: 0
.. :height: 408
.. :id: Grafik14
.. :name: Grafik14
.. :width: 562

.. |img-7| image:: img-7.png
   :alt: A screenshot of a FAQ with a list of questions.
.. :align: bottom
.. :border: 0
.. :height: 229
.. :id: Grafik15
.. :name: Grafik15
.. :width: 576

.. |img-8| image:: img-8.png
   :alt: A screenshot of a single FAQ answer.
.. :align: bottom
.. :border: 0
.. :height: 531
.. :id: Grafik16
.. :name: Grafik16
.. :width: 570

.. |img-9| image:: img-9.png
   :alt: A screenshot of a FAQ with a list of questions, text search form and highlighting.
.. :align: bottom
.. :border: 0
.. :height: 410
.. :id: Grafik17
.. :name: Grafik17
.. :width: 563

.. |img-10| image:: img-10.png
   :alt: A screenshot of a single FAQ answer with highlighted searchword in the text.
.. :align: bottom
.. :border: 0
.. :height: 266
.. :id: Grafik18
.. :name: Grafik18
.. :width: 572

.. |img-11| image:: img-11.png
.. :align: left
.. :border: 0
.. :height: 32
.. :id: Graphic1
.. :name: Graphic1
.. :width: 102