Quick Access (QA) is a simple, sliding navigation menu jQuery Plugin combined with a custom jquery plugin that can be integrated with your search. It allows your LiveWhale CMS site to have manager-curated links that get suggested to visitors as they type into the search bar.
These are generally used for your main search box. (For LiveWhale 1.6+) Your QA search box should have the class “lw_qa” attached like the following:
<input type="text" class="lw_qa"/>
This will automatically enable QA for that input, pulling results from the curated list of results managed by an admin at /livewhale/?quickaccess on your installation.
This will let you search over all LiveWhale content, including static web pages and dynamic content such as news, events, etc. The results are grouped by the content type. Your QA search box should have the class “lw_qa_content”:
<input type="text" class="lw_qa_content"/>
This will automatically return results from the database as you enter search terms. All content types are returned and organized into categories. If you wish to limit the results to specific types, you can use the data-qa-types attribute:
<input type="text" class="lw_qa_content" data-qa-types="news,events"/>
This can be used if you want to curate your own set of results for specific contexts, such as a particular department.
Your QA search box should have the class “lw_qawidget“ followed by the ID of a saved widget. Example (for widget id=1):
<input type="text" class="lw_qa_widget_1"/>
This will cause your QA search box to return results returned by the widget with the specified ID. If you use a news widget, for example, it will return results from just the news stories returned by that widget.
For a curated set of results that combines the results of several widgets, you can use a blurbs widget, and edit the blurb returned by that widget to create your own curated set of links for QA results.
This can be used if you want to quickly filter links already within the page you are currently on. Your QA search box should have the class “lw_qa_filter” as well as an attribute indicating the element that contains the A tags that you want to filter:
<input type="text" class="lw_qa_filter" data-qa-target=".my-class a"/>
This can be used if you want to set up a simple web page containing all possible QuickAccess search results. This may include hardcoded links, widget results, etc.
Your QA search box should have an ID and the class “.lw_qa_page” as well as an attribute indicating the url to the page containing QuickAccess results:
<input type="text" id="quickaccess" class="lw_qa_page" data-qa-url="/includes/quickaccess.html"/>
An example of a page containing hardcoded results and widget results combined:
All of the approaches above permit the following additional attributes to further customize the behavior of QuickAccess:
|data-qa-max-results||This is the maximum number of results to show at any one time. The default is 10.|
|data-qa-max-results-per-category||This is the maximum number of results per category, if the results support category groupings.|
|data-qa-force-select||When true, an autocomplete option will always be selected; disable this, for instance, if you’d like the quickaccess box to also function as a typical search box. The default is true.|
|data-qa-show-none-found||Whether or not to show the none found message if there are no results.|
|data-qa-none-found||This is the message shown when no results are found. The default is ‘No matches found.’.|
|data-qa-too-many||This is the message shown when there are more matching results than data-qa-max-results. The default is ‘Keep typing…’.|
|data-qa-more-results-msg||Directs the user to the full search results page. Permanently displayed at the bottom of the Quick Access results dropdown. e.g., “View all results »”|
|data-qa-more-results-url||The path to the full search results page with the query string. e.g., “/search/index.php?q=”|
|data-qa-min-characters||How many character must be typed before the script starts searching. The default is 2. (LiveWhale 1.7+)|
When customizing your LiveWhale search results page, you may want to display QuickAccess results on that page, too, rather than only as auto-suggest links in the search bar. To do so, LiveWhale 2.0+ has a QuickAccess widget:
|links||The selector for the links that are to be searched (i.e. ‘#linkslist a’ or ‘a.quickaccess’). To organize results into categories, selector may be an array of objects (i.e.
|results||The container in which the results will be placed. The default is to place them in a div.qa_results element created immediately after the search
|forceSelect||When true, an autocomplete option will always be selected; disable this, for instance, if you’d like the quickaccess box to also function as a typical search box. The default is true.|
|onSubmit||This is the callback function for when the user hits the enter/return key; by default, this will take them to the selected link. The arguments are the keypress event and the currently selected result.|
|maxResults||This is the maximum number of results to show at any one time. The default is 10.|
|placeholder||This sets the HTML5 placeholder attribute on the
|tooMany||This is the message shown when there are more matching results than maxResults. The default is ‘Keep typing…’.|
|noneFound||This is the message shown when no results are found. The default is ‘No matches found.’.|
|focus||Should the search element assume focus upon page initialization? The default is false.|
|removeDuplicates||Should duplicate URLs be allowed in the results? The default is false.|
|mouseControls||Should mouse scroll events move you up/down the results? The default is true.|
|showScore||Should the relevance score be appended to the individual results? When true, the score is appended to the result wrapped by. The default is false.|
|options (formerly combOptions)||Should you want to tweak the response/weighting of results provided by QA, you may alter its settings through an options object.|
A few of the options for the
options argument are listed below, and you can find more by exploring jquery.quick-access.js.
|delay||The amount of time, in milliseconds, between a new character being pressed and the QA search being run. (default : 200)|
|sortByScore||Sorts QA resu lts by their relevance score, which is calculated based on how well the search query matches each link, how many words, how many par tial words, etc. (default: true)|
|groupByCategory||Groups QA res ults by category. (default: true)|
|loadFrom||Load QA resul ts from an HTML or PHP file (see example below)|
|remoteDataType||Set to “HTML” (default: JSON) to load QA res ults from an external file (see example below)|
Here is an example of a custom QA implementation that compares search queries to all links from includes/quickaccess.php. That pages includes multiple widgets for people and navigations, plus “Top Links” curated using the QuickAccess superpower in the back-end.
Note: /livewhale/content/quickaccess/quickaccess.html is a LiveWhale system page that automatically lists all the links you’ve created using the QuickAccess superpower in the back-end. In this example, showByScore is set to “false” in the options so that Top Links will always display first in the QA results, regardless of score.
Thanks Jon Wilcox at Angelo State University for sharing this code!
In LiveWhale 1.7+, you can use an external data file (static, or generated by LW widgets) and, rather than using the
links array above to set your category titles, you can set up titles right in the file using
links: "auto" in your script and
data-label="" in your data file.
<div id="qa-top-links" data-label="Top Links">