simple-faq v1.0.0

jquerySimpleFAQ

Simple jQuery plugin for creating FAQ interfaces

Features

• Simple to use. Use existing HTML data (ul > li) for source or use a JSON data array
• Lots of options, but none required.
• Fast live searching using Quicksilver, including relevancy sorting (optionally).
• Add tags to FAQs to increase relevancy of searching.
• Events triggered for extra preocess handling if necessary.

Basic Usage

With an HTML data source:

<ul id='faqs'>
  <li>
    <!-- Note that you MUST have the "question", "answer", and "tags" classes on these nodes -->
    <p class='question'>This is a question?</p>
    <div class='answer'>This is the answer.</div>
    <p class='tags'>tags, help, searching</p>
  </li>
  ...
</ul>

$('#faqs').simpleFAQ(); // Most simple form (all default options)

When using the 'data' option (JSON) and searching:

<div><input type='text' id='faqSearch' /></div>
<ul id='faqs'></ul>

$('#faqs').simpleFAQ({
  data: [
    {
      question: "This is a question?",
      answer: "This is the answer.",
      tags: "tags, help, searching" // OPTIONAL, useful for search scoring (and displaying if you wish)
    },
    ...
  ],
  allowSearch: true,
  searchNode: '#faqSearch'
});

See more examples at: http://jordankasper.com/jquery/faq/examples

Events

• init.simpleFAQ: The basic UI container and event handlers have been added to the document (or have been updated). You should only ever receive ONE of these events per page load. (Arguments: event, $.jk.SimpleFAQ object)
• show.simpleFAQ: Fired when an individual FAQ answer is shown. (Note: when searching for results, this will NOT fire when the FAQ is shown, only when the ANSWER is shown.) (Arguments: event, HTMLElement faq)
• hide.simpleFAQ: Fired when an individual FAQ answer is hidden (either explicitly by the user, or because another FAQ was shown and the showOnlyOne option is true. (Note: when searching for results, this will NOT fire when the FAQ is hidden because it is not in the result set, only when the ANSWER is hidden after being shown.) (Arguments: event, HTMLElement faq)
• searchStart.simpleFAQ: Fires when the user initiates a search. (Arguments: event)
• searchEnd.simpleFAQ: Fired after a search sction is complete (all results will be showing at this point). (Arguments: event, array scores (NOTE: format will be: [ score, faqNode, ...] ))
• sort.simpleFAQ: Fired when the results of a search are sorted. (Arguments: event, array scores (NOTE: format will be: [ score, faqNode, ...] ))

Event Example

$('#faqs').bind('searchEnd.simpleFAQ', function(jQEvent, results) {
  if (results.length < 1) {
    // do something when there are no results?
  }
});

Options

• node: selector | HTMLElement | jQuery object The node (or selector) to use for the FAQ UI. If not set, the current node selected by $(...).simpleFAQ(); will be used. (default: null)
• data: array The JSON data to use for the FAQs (will be added to any HTML FAQs). Format: [ { question: "...", answer: "...", tags: "multiple, tags" /* OPTIONAL */ } ] (default: null)
• ns: string Used before all assigned classes and as an event namespace. (default: "simpleFAQ")
• nodeType: string The type of node to look for (or use with JSON data) for FAQs. (default: "li")
• questionClass: string The class that all questions will have (either you have to give them this class, or use the plugin to build the list). (default: "question")
• answerClass: string The class that all answers will have (either you have to give them this class, or use the plugin to build the list). (default: "answer")
• tagClass: string The class for a node in the answer that contains tags specific to each answer. If this exists, it boosts the score for search terms that are in the tags. (default: "tags")
• showOnlyOne: boolean If true, only one answer will be visible at a time (accordion style). (default: false)
• changeHash: boolean If true, the URL hash will be changed on each FAQ toggle, thus allowing for linking directly to a specific FAQ. (default: true)
• slideSpeed: number | string The speed to open and close FAQ answers. String values must be one of the three predefined speeds: "slow", "normal", or "fast"; numeric values are the number of milliseconds to run the animation (e.g. 1000). (default: 500)

Search Options

• allowSearch: boolean If true, adds searching ability (must provide searchNode) (default: false)
• searchNode: selector | HTMLElement | jQuery object Only required if allowSearch is true; it is the element used for search input. NOTE: we use the keyup event, so this should be something that will emit that event correctly and can have a value! (Can be a node, jQuery object, or selector.) (default: null)
• minSearchScore: number The minimum score a FAQ must have in order to appear in search results. Depends on what search function youa re using, but quicksilver returns scores between 0 and 1 (although the final score can be more than 1 based on tag scoring). (default: 0.5)
• sortSearch: boolean Whether or not to sort search results by score (descending). (default: false)
• showAllOnEmpty: boolean Should the plugin show all FAQs when there is no search input? (default: true)
• caseSensitive: boolean Whether or not the search is case sensitive. (default: false)
• keyTimeout: number A number of milliseconds to wait after a keyup event before initiating a search. Allows for better efficiency as a person is typing (live search principle). (default: 400)
• partialTagScore: number What to increase the match score by when partial tags are matched (such as "sim" -> "simple") (default: 0.1)
• exactTagScore: number What to increase the match score by when an exact tag is matched (such as "simple" -> "simple") (default: 0.2)
• score: function A function used to score FAQ question and answer text (not tags). Should accept the full text and a single search token and return the score (generally a decimal number between 0 and 1, but this is up to you). (default: $.score (Quicksilver scoring function))