538 lines
20 KiB
HTML
Executable File
538 lines
20 KiB
HTML
Executable File
<!DOCTYPE HTML>
|
|
<html>
|
|
<head>
|
|
<meta http-equiv="content-type" content="text/html;charset=UTF-8" />
|
|
<meta http-equiv="X-UA-Compatible" content="chrome=1">
|
|
<title>DocumentCloud's VisualSearch.js</title>
|
|
<style>
|
|
body {
|
|
font-size: 16px;
|
|
line-height: 24px;
|
|
background: #FEF3CA;
|
|
height: 100%;
|
|
color: #022;
|
|
font-family: Arial;
|
|
font-family: "Palatino Linotype", "Book Antiqua", Palatino, FreeSerif, serif;
|
|
}
|
|
div.container {
|
|
width: 720px;
|
|
margin: 50px 0 50px 50px;
|
|
}
|
|
p, li {
|
|
margin: 16px 0 16px 0;
|
|
width: 550px;
|
|
}
|
|
p.break {
|
|
margin-top: 35px;
|
|
}
|
|
ol {
|
|
padding-left: 24px;
|
|
}
|
|
ol li {
|
|
font-weight: bold;
|
|
margin-left: 0;
|
|
}
|
|
a, a:visited {
|
|
padding: 0 2px;
|
|
text-decoration: none;
|
|
background: #f0c095;
|
|
color: #252519;
|
|
}
|
|
a:active, a:hover {
|
|
color: #000;
|
|
background: #e0a070;
|
|
}
|
|
h1, h2, h3, h4, h5, h6 {
|
|
margin-top: 40px;
|
|
}
|
|
b.header {
|
|
font-size: 18px;
|
|
}
|
|
span.alias {
|
|
font-size: 14px;
|
|
font-style: italic;
|
|
margin-left: 20px;
|
|
}
|
|
table {
|
|
margin: 16px 0; padding: 0;
|
|
}
|
|
tr, td, th {
|
|
margin: 0; padding: 0;
|
|
text-align: left;
|
|
}
|
|
th {
|
|
padding: 24px 0 0;
|
|
}
|
|
tr:first-child th {
|
|
padding-top: 0;
|
|
}
|
|
td {
|
|
padding: 6px 15px 6px 0;
|
|
}
|
|
td.definition {
|
|
line-height: 18px;
|
|
font-size: 14px;
|
|
}
|
|
table.downloads td {
|
|
padding-left: 18px;
|
|
}
|
|
.demo-hint {
|
|
font-size: 13px;
|
|
margin: 0 0 12px 12px;
|
|
font-weight: normal;
|
|
}
|
|
#VS code, #VS pre, #VS tt {
|
|
font-family: Monaco, Consolas, "Lucida Console", monospace;
|
|
font-size: 12px;
|
|
line-height: 18px;
|
|
color: #444;
|
|
background: none;
|
|
}
|
|
#VS code {
|
|
margin-left: 8px;
|
|
padding: 0 0 0 12px;
|
|
font-weight: normal;
|
|
}
|
|
#VS pre {
|
|
font-size: 12px;
|
|
padding: 2px 0 2px 0;
|
|
border-left: 6px solid #829C37;
|
|
margin: 12px 0;
|
|
}
|
|
#search_query {
|
|
margin: 18px 0 -24px;
|
|
opacity: 0;
|
|
}
|
|
#search_query .raquo {
|
|
font-size: 18px;
|
|
line-height: 12px;
|
|
font-weight: bold;
|
|
margin-right: 4px;
|
|
}
|
|
.attribution {
|
|
margin: -12px 0 24px;
|
|
font-size: 14px;
|
|
}
|
|
</style>
|
|
|
|
<link rel="stylesheet" href="build-min/visualsearch-datauri.css" type="text/css" media="screen" charset="utf-8">
|
|
<link rel="stylesheet" href="docs/assets/github.css" type="text/css" media="screen" charset="utf-8">
|
|
|
|
<script src="build-min/dependencies.js" type="text/javascript" charset="utf-8"></script>
|
|
<script src="build-min/visualsearch.js" type="text/javascript" charset="utf-8"></script>
|
|
<script src="docs/assets/highlight.js" type="text/javascript" charset="utf-8"></script>
|
|
<script src="docs/assets/javascript.js" type="text/javascript" charset="utf-8"></script>
|
|
<script src="docs/assets/xml.js" type="text/javascript" charset="utf-8"></script>
|
|
<script>
|
|
hljs.initHighlightingOnLoad();
|
|
</script>
|
|
|
|
</head>
|
|
<body>
|
|
|
|
<div class="container" id="VS">
|
|
|
|
<h1>VisualSearch.js</h1>
|
|
|
|
<p class="attribution">
|
|
<i>
|
|
Created by <a href="http://github.com/samuelclay">Samuel Clay</a>,
|
|
<a href="http://twitter.com/samuelclay">@samuelclay</a>.
|
|
</i>
|
|
</p>
|
|
|
|
<p>
|
|
<a href="http://github.com/documentcloud/visualsearch">VisualSearch.js</a>
|
|
enhances ordinary search boxes with the ability to autocomplete
|
|
faceted search queries. Specify the facets for completion, along with the
|
|
completable values for any facet. You can retrieve the search query as a
|
|
structured object, so you don't have to parse the query string yourself.
|
|
</p>
|
|
|
|
<p>
|
|
<a href="https://www.documentcloud.org/public/#search/group%3A%20dcloud%20chair%3A%20%22Christopher%20Dodd%22%20TARP">Here's an example of a search on DocumentCloud.org that uses facets.</a>
|
|
</p>
|
|
|
|
<p>
|
|
The project is
|
|
<a href="http://github.com/documentcloud/visualsearch/">hosted on GitHub</a>.
|
|
You can report bugs and discuss features on the
|
|
<a href="http://github.com/documentcloud/visualsearch/issues">issues page</a>,
|
|
on Freenode in the <tt>#documentcloud</tt> channel,
|
|
or send tweets to <a href="http://twitter.com/documentcloud">@documentcloud</a>.
|
|
</p>
|
|
|
|
<p>
|
|
<i>VisualSearch.js is an open-source component of <a href="http://documentcloud.org/">DocumentCloud</a>.
|
|
<br />
|
|
<a href="docs/visualsearch.html">The complete annotated source code</a>
|
|
is also available.</i>
|
|
</p>
|
|
|
|
<h2>Table of Contents</h2>
|
|
|
|
<a href="#demo">Demo</a> | <a href="#downloads">Downloads</a> | <a href="#usage">Usage</a> | <a href="#changelog">Change Log</a>
|
|
|
|
|
|
<h2 id="demo">Demo <span class="demo-hint"><i>Try searching for: <b>account</b>, <b>filter</b>, <b>access</b>, <b>title</b>, <b>city</b>, <b>state</b>, or <b>country</b>.</i></span></h2>
|
|
|
|
|
|
|
|
<div id="search_box_container"></div>
|
|
<div id="search_query"> </div>
|
|
|
|
<script type="text/javascript" charset="utf-8">
|
|
$(document).ready(function() {
|
|
var visualSearch = VS.init({
|
|
container : $('#search_box_container'),
|
|
query : 'country: "United States" state: "New York" account: 5-samuel title: "Pentagon Papers"',
|
|
unquotable : [
|
|
'text',
|
|
'account',
|
|
'filter',
|
|
'access'
|
|
],
|
|
callbacks : {
|
|
search : function(query, searchCollection) {
|
|
var $query = $('#search_query');
|
|
var count = searchCollection.size();
|
|
$query.stop().animate({opacity : 1}, {duration: 300, queue: false});
|
|
$query.html('<span class="raquo">»</span> You searched for: ' +
|
|
'<b>' + (query || '<i>nothing</i>') + '</b>. ' +
|
|
'(' + count + ' facet' + (count==1 ? '' : 's') + ')');
|
|
clearTimeout(window.queryHideDelay);
|
|
window.queryHideDelay = setTimeout(function() {
|
|
$query.animate({
|
|
opacity : 0
|
|
}, {
|
|
duration: 1000,
|
|
queue: false
|
|
});
|
|
}, 2000);
|
|
},
|
|
facetMatches : function(callback) {
|
|
callback([
|
|
'account', 'filter', 'access', 'title',
|
|
{ label: 'city', category: 'location' },
|
|
{ label: 'country', category: 'location' },
|
|
{ label: 'state', category: 'location' },
|
|
]);
|
|
},
|
|
valueMatches : function(facet, searchTerm, callback) {
|
|
switch (facet) {
|
|
case 'account':
|
|
callback([
|
|
{ value: '1-amanda', label: 'Amanda' },
|
|
{ value: '2-aron', label: 'Aron' },
|
|
{ value: '3-eric', label: 'Eric' },
|
|
{ value: '4-jeremy', label: 'Jeremy' },
|
|
{ value: '5-samuel', label: 'Samuel' },
|
|
{ value: '6-scott', label: 'Scott' }
|
|
]);
|
|
break;
|
|
case 'filter':
|
|
callback(['published', 'unpublished', 'draft']);
|
|
break;
|
|
case 'access':
|
|
callback(['public', 'private', 'protected']);
|
|
break;
|
|
case 'title':
|
|
callback([
|
|
'Pentagon Papers',
|
|
'CoffeeScript Manual',
|
|
'Laboratory for Object Oriented Thinking',
|
|
'A Repository Grows in Brooklyn'
|
|
]);
|
|
break;
|
|
case 'city':
|
|
callback([
|
|
'Cleveland',
|
|
'New York City',
|
|
'Brooklyn',
|
|
'Manhattan',
|
|
'Queens',
|
|
'The Bronx',
|
|
'Staten Island',
|
|
'San Francisco',
|
|
'Los Angeles',
|
|
'Seattle',
|
|
'London',
|
|
'Portland',
|
|
'Chicago',
|
|
'Boston'
|
|
]);
|
|
break;
|
|
case 'state':
|
|
callback([
|
|
"Alabama", "Alaska", "Arizona", "Arkansas", "California",
|
|
"Colorado", "Connecticut", "Delaware", "District of Columbia", "Florida",
|
|
"Georgia", "Guam", "Hawaii", "Idaho", "Illinois",
|
|
"Indiana", "Iowa", "Kansas", "Kentucky", "Louisiana",
|
|
"Maine", "Maryland", "Massachusetts", "Michigan", "Minnesota",
|
|
"Mississippi", "Missouri", "Montana", "Nebraska", "Nevada",
|
|
"New Hampshire", "New Jersey", "New Mexico", "New York", "North Carolina",
|
|
"North Dakota", "Ohio", "Oklahoma", "Oregon", "Pennsylvania",
|
|
"Puerto Rico", "Rhode Island", "South Carolina", "South Dakota", "Tennessee",
|
|
"Texas", "Utah", "Vermont", "Virginia", "Virgin Islands",
|
|
"Washington", "West Virginia", "Wisconsin", "Wyoming"
|
|
]);
|
|
break;
|
|
case 'country':
|
|
callback([
|
|
"China", "India", "United States", "Indonesia", "Brazil",
|
|
"Pakistan", "Bangladesh", "Nigeria", "Russia", "Japan",
|
|
"Mexico", "Philippines", "Vietnam", "Ethiopia", "Egypt",
|
|
"Germany", "Turkey", "Iran", "Thailand", "D. R. of Congo",
|
|
"France", "United Kingdom", "Italy", "Myanmar", "South Africa",
|
|
"South Korea", "Colombia", "Ukraine", "Spain", "Tanzania",
|
|
"Sudan", "Kenya", "Argentina", "Poland", "Algeria",
|
|
"Canada", "Uganda", "Morocco", "Iraq", "Nepal",
|
|
"Peru", "Afghanistan", "Venezuela", "Malaysia", "Uzbekistan",
|
|
"Saudi Arabia", "Ghana", "Yemen", "North Korea", "Mozambique",
|
|
"Taiwan", "Syria", "Ivory Coast", "Australia", "Romania",
|
|
"Sri Lanka", "Madagascar", "Cameroon", "Angola", "Chile",
|
|
"Netherlands", "Burkina Faso", "Niger", "Kazakhstan", "Malawi",
|
|
"Cambodia", "Guatemala", "Ecuador", "Mali", "Zambia",
|
|
"Senegal", "Zimbabwe", "Chad", "Cuba", "Greece",
|
|
"Portugal", "Belgium", "Czech Republic", "Tunisia", "Guinea",
|
|
"Rwanda", "Dominican Republic", "Haiti", "Bolivia", "Hungary",
|
|
"Belarus", "Somalia", "Sweden", "Benin", "Azerbaijan",
|
|
"Burundi", "Austria", "Honduras", "Switzerland", "Bulgaria",
|
|
"Serbia", "Israel", "Tajikistan", "Hong Kong", "Papua New Guinea",
|
|
"Togo", "Libya", "Jordan", "Paraguay", "Laos",
|
|
"El Salvador", "Sierra Leone", "Nicaragua", "Kyrgyzstan", "Denmark",
|
|
"Slovakia", "Finland", "Eritrea", "Turkmenistan"
|
|
], {preserveOrder: true});
|
|
break;
|
|
}
|
|
}
|
|
}
|
|
});
|
|
});
|
|
</script>
|
|
|
|
<h2 id="downloads">Downloads <i style="padding-left: 12px; font-size:12px;">(Right-click, and use "Save As")</i></h2>
|
|
|
|
<table class="downloads">
|
|
|
|
<tr>
|
|
<th colspan="2">0. Everything (<tt>visualsearch.zip</tt>)</th>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="https://github.com/documentcloud/visualsearch/zipball/master">Download everything</a></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<th colspan="2">1. VisualSearch JavaScript (<tt>visualsearch.js</tt>)</th>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="build-min/visualsearch.js">Production Version (0.2.2)</a></td>
|
|
<td><i>8kb, Minified and Gzipped</i></td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="build/visualsearch.js">Development Version (0.2.2)</a></td>
|
|
<td><i>45kb, Uncompressed with Comments</i></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<th colspan="2">2. VisualSearch Stylesheets (<tt>visualsearch.css</tt>)</th>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="2"><i>You should include both the datauri and image urls versions. <a href="#css">See how to include both</a></i></td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="build-min/visualsearch-datauri.css">Production Version - datauri</a></td>
|
|
<td><i>4kb, Minified and Gzipped</i></td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="build-min/visualsearch.css">Production Version - image urls</a></td>
|
|
<td><i>4kb, Minified and Gzipped</i></td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="build/visualsearch.css">Development Version</a></td>
|
|
<td><i>8kb, Uncompressed with Comments</i></td>
|
|
</tr>
|
|
<tr>
|
|
<th colspan="2">3. VisualSearch Images</th>
|
|
</tr>
|
|
<tr>
|
|
<td><img src="lib/images/embed/icons/search_glyph.png"> <a href="lib/images/embed/icons/search_glyph.png">Search Glyph</a></td>
|
|
<td><i>4kb, embedded in visualsearch-datauri.css</i></td>
|
|
</tr>
|
|
<tr>
|
|
<td><img src="lib/images/embed/icons/cancel_search.png"> <a href="lib/images/embed/icons/cancel_search.png">Cancel Button</a></td>
|
|
<td><i>4kb, embedded in visualsearch-datauri.css</i></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<th colspan="2">4. VisualSearch Dependencies (<tt>jQuery 1.4+, jQuery UI, Underscore.js, Backbone.js</tt>)</th>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="2"><i>You should only include the dependencies you don't already have.</i></td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="build-min/dependencies.js">Production Version - All</a></td>
|
|
<td><i>49kb, Minified and Gzipped</i></td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="build/dependencies.js">Development Version - All</a></td>
|
|
<td><i>340kb, Uncompressed with Comments</i></td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="vendor/jquery-1.6.1.js">jQuery 1.6.1</a></td>
|
|
<td><i>238kb, Uncompressed with Comments</i></td>
|
|
</tr>
|
|
<tr>
|
|
<td>jQuery UI 1.8.13: <br /><a href="vendor/jquery.ui.core.js">Core</a> <a href="vendor/jquery.ui.position.js">Position</a> <a href="vendor/jquery.ui.widget.js">Widget</a> <a href="vendor/jquery.ui.autocomplete.js">Autocomplete</a></td>
|
|
<td><i>48kb, Uncompressed with Comments</i></td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="vendor/underscore-1.1.5.js">Underscore 1.1.5</a></td>
|
|
<td><i>29kb, Uncompressed with Comments</i></td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="vendor/backbone-0.5.0.js">Backbone 0.5.0</a></td>
|
|
<td><i>41kb, Uncompressed with Comments</i></td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<h2 id="usage">Usage</h2>
|
|
|
|
<p>To use VisualSearch.js on your site, follow these instructions on installation, configuration, and customization.</p>
|
|
|
|
<ol>
|
|
<li class="xml" id="css">Insert the JavaScript and CSS into your page:<br />
|
|
<pre><code><script src="visualsearch.js" type="text/javascript"></script>
|
|
<!--[if (!IE)|(gte IE 8)]><!-->
|
|
<link href="visualsearch-datauri.css" media="screen" rel="stylesheet" type="text/css" />
|
|
<!--<![endif]-->
|
|
<!--[if lte IE 7]><!-->
|
|
<link href="visualsearch.css" media="screen" rel="stylesheet" type="text/css" />
|
|
<!--<![endif]--></code></pre>
|
|
</li>
|
|
<li>Initialize the Visual Search box:<br />
|
|
<pre class="javascript"><code><div class="visual_search"></div>
|
|
|
|
<script type="text/javascript" charset="utf-8">
|
|
$(document).ready(function() {
|
|
var visualSearch = VS.init({
|
|
container : $('.visual_search'),
|
|
query : '',
|
|
callbacks : {
|
|
search : function(query, searchCollection) {},
|
|
facetMatches : function(callback) {},
|
|
valueMatches : function(facet, searchTerm, callback) {}
|
|
}
|
|
});
|
|
});
|
|
</script></code></pre>
|
|
</li>
|
|
<li class="javascript">Customize the autocompleted facets and values:
|
|
<pre><code>callbacks : {
|
|
...
|
|
// These are the facets that will be autocompleted in an empty input.
|
|
facetMatches : function(callback) {
|
|
callback([
|
|
'account', 'filter', 'access', 'title',
|
|
{ label: 'city', category: 'location' },
|
|
{ label: 'address', category: 'location' },
|
|
{ label: 'country', category: 'location' },
|
|
{ label: 'state', category: 'location' },
|
|
]);
|
|
}
|
|
...
|
|
// These are the values that match specific categories, autocompleted
|
|
// in a category's input field. searchTerm can be used to filter the
|
|
// list on the server-side, prior to providing a list to the widget.
|
|
valueMatches : function(facet, searchTerm, callback) {
|
|
switch (facet) {
|
|
case 'account':
|
|
callback([
|
|
{ value: '1-amanda', label: 'Amanda' },
|
|
{ value: '2-aron', label: 'Aron' },
|
|
{ value: '3-eric', label: 'Eric' },
|
|
{ value: '4-jeremy', label: 'Jeremy' },
|
|
{ value: '5-samuel', label: 'Samuel' },
|
|
{ value: '6-scott', label: 'Scott' }
|
|
]);
|
|
break;
|
|
case 'filter':
|
|
callback(['published', 'unpublished', 'draft']);
|
|
break;
|
|
case 'access':
|
|
callback(['public', 'private', 'protected']);
|
|
break;
|
|
case 'title':
|
|
callback([
|
|
'Pentagon Papers',
|
|
'CoffeeScript Manual',
|
|
'Laboratory for Object Oriented Thinking',
|
|
'A Repository Grows in Brooklyn'
|
|
]);
|
|
break;
|
|
}
|
|
}
|
|
...
|
|
}</code></pre>
|
|
</li>
|
|
<li class="javascript">Inspect the Visual Search box
|
|
<pre><code>// Returns the unstructured search query
|
|
visualSearch.searchBox.value()
|
|
// "country: "South Africa" account: 5-samuel title: "Pentagon Papers""
|
|
|
|
// Returns an array of Facet model instances
|
|
visualSearch.searchQuery.facets()
|
|
// [FacetModel<country:"South Africa">,
|
|
// FacetModel<account:5-samuel>,
|
|
// FacetModel<title:"Pentagon Papers">]
|
|
|
|
// Set the search query with raw text
|
|
visualSearch.searchBox.value("Country: US State: \"New York\" Key: Value")
|
|
|
|
</code></pre>
|
|
</li>
|
|
</ol>
|
|
|
|
|
|
<h2 id="changelog">Change Log</h2>
|
|
|
|
<p>
|
|
<b class="header">0.2.2</b> <i>March 10th, 2012</i><br />
|
|
If you do not want to automatically filter the value matches, you can pass an
|
|
options hash with <tt>preserveMatches: true</tt> as the second argument to the callback.
|
|
<a href="https://github.com/documentcloud/visualsearch/pull/44">See pull request #44</a> for details.
|
|
</p>
|
|
<p>
|
|
<b class="header">0.2.1</b> <i>November 14th, 2011</i><br />
|
|
The autocompleted facets and values that are provided by your callbacks <tt>facetMatches</tt>
|
|
and <tt>valueMatches</tt> can now preserve the order of items you give them. Simply pass an
|
|
options hash with <tt>preserveOrder: true</tt> as the second argument to the callback. See
|
|
<a href="demo.html">the demo page</a> for an example.
|
|
</p>
|
|
<p>
|
|
<b class="header">0.2.0</b> <i>August 10th, 2011</i><br />
|
|
Multiple instances of VisualSearch on a single page. <tt>VS.init</tt> now returns
|
|
a reference to the instance. The <tt>search</tt> callback now contains both the
|
|
serialized search query and a reference to the search query collection (as a
|
|
<a href="http://documentcloud.github.com/backbone/#Collection">Backbone.Collection</a>),
|
|
which can be used to manipulate each facet directly. See
|
|
<a href="docs/search_query.html">the source code for search_query.js</a> for available
|
|
methods on the collection.
|
|
</p>
|
|
<p>
|
|
<b class="header">0.1.0</b> <i>June 23rd, 2011</i><br />
|
|
Initial release of VisualSearch.js.
|
|
</p>
|
|
|
|
<p>
|
|
<a href="http://documentcloud.org/" title="A DocumentCloud Project" style="background:none;">
|
|
<img src="http://jashkenas.s3.amazonaws.com/images/a_documentcloud_project.png" alt="A DocumentCloud Project" />
|
|
</a>
|
|
</p>
|
|
|
|
</div>
|
|
|
|
</body>
|
|
</html>
|