Quick Access

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.

Instructions

2. Choose the type of results to search over:

• Curated site wide results

​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.

• Search LiveWhale pages and content

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"/>

• Searching over the results of a particular widget

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.

• Searching over the results of links within the same page

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"/>

• Searching your own custom page of results​

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:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
<html>
<body>
<h2>Departments:</h2>
<ul>
  <li>
    <a href="/academics/accelerated_programs" title="accelerated, programs">Accelerated Programs</a>
  </li>
  <li>
    <a href="/academics/programs/afam/" title="african, american, studies">African American Studies</a>
  </li>
  <li>
    <a href="/academics/programs/amer/" title="american, studies">American Studies</a>
  </li>
  <li> 
    <a href="/academics/programs/area/" title="countries, foreign, services">Area Studies</a>
  </li>
</ul>

<h2>Stories</h2>
<widget type="news">
  <arg id="group">Communications</arg>
  <arg id="max">100</arg>
  <arg id="paginate">false</arg>
</widget>

</body>
</html>

3. Add css styling for results formatting if needed

If your requirements are not covered by these suggestions, contact support@livewhale.com and we can assist in creating custom Javascript to perform the exact QA search you require.

Available options

All of the approaches above permit the following additional attributes to further customize the behavior of QuickAccess:

Option Description
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+)

4. Optional: Include QuickAccess results on your main search page

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:

1
2
3
4
<widget type="quickaccess">
  <arg id="header">Top Links</arg>
  <arg id="search"><xphp var="q" type="GET"/></arg>
</widget>

Advanced: Manually writing custom QuickAccess javascript

Users who wish to write custom javascript to deploy the QuickAccess plugin can use any of the following options to control the plugin’s behavior. If you are not writing your own javascript to deploy the QuickAccess jQuery plugin manually, you should consult the steps above only.

Argument Description
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. [{selector:'#mammals a',title:'Mammals',className: 'mammals'},{selector:'#reptile s a',title:'Reptiles',className: 'reptiles'}]). The default is .qa_links a.
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 <input>.
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 <input>. The default is null or no placeholder.
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.

Option Description
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.

scripts.js

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
$('input#search').quickAccess({
    maxResults: 10,
    focus: false,
    noneFound: 'Press Enter to search.',
    forceSelect: false,
    'links': [
        {selector: '.lw_qa_curated_results a',title: 'Top Links'},
        {selector: '.lw_qa_academic_departments a',title:'Academic Departments'},
        {selector: '.lw_qa_people a',title:'Faculty/Staff'},
        {selector: '.lw_qa_offices a',title:'Offices'}
    ],
    options: {
        remoteDataType: 'html',
        sortByScore: false,
        loadFrom: function() {
            return '/includes/quickaccess.php';
        }
    }
});

includes/quickaccess.php

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.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
<?php require $_SERVER['DOCUMENT_ROOT'].'/livewhale/frontend.php';?>

<div class="lw_qa_curated_results">
<widget type="file"><arg id="path">/livewhale/content/quickaccess/quickaccess.html</arg></widget>
</div>

​<div class="lw_qa_academic_departments">
<widget type="navigation">
<arg id="id">1</arg>
</widget>
</div>

​<div class="lw_qa_people">
<widget type="profiles">
<arg id="type">Faculty</arg>
<arg id="type">Staff</arg>
<arg id="format">{name}</arg>
</widget>
</div>

​<div class="lw_qa_offices">
<widget type="navigation">
<arg id="id">3</arg>
</widget>
</div>

Thanks Jon Wilcox at Angelo State University for sharing this code!

Setting QA category titles within external data file

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.

scripts.js

1
2
3
4
5
6
7
8
9
$('#search').quickAccess({
  links: "auto",
  combOptions: {
    remoteDataType: 'html',
    loadFrom: function () {
      return 'includes/quickaccess.php';
    }
  }
});

includes/quickaccess.php

1
2
3
4
5
6
7
8
9
<div id="qa-top-links" data-label="Top Links">
  <a href="#test1" data-keywords="events,schedule,happening,calander,dates">Calendar</a>
  <a href="#test2" data-keywords="people,faculty,staff,phone,contact">Directory</a>
  <a href="#test3" data-keywords="donate,gift,giving,donation,class gift,planned giving">Give</a>
</div>
<div id="qa-departments" data-label="Departments">
  <a href="#test20" data-keywords="africa">Department of Africana Studies</a>
  <a href="#test21" data-keywords="sculpture,painting,drawing,photography">Department of Visual Arts</a>
</div>
Edit

Still have questions?

Try searching on the left menu, or email support@livewhale.com and we'll be happy to help.