Embeddable Javascript Widget

From DBSight Full-Text Search Engine/Platform Wiki

This is also covered in Easy Integration with existing systems Here is a more big-picture description.

Table of contents

Design Goal

The main idea is to make this very easy to customize, and easy to embed DBSight search to any page, with little coding effort.

What you need to do?

  1. Generate code via one of the Widget scaffold.
  2. Just copy either the whole generated example.html file, or a portion of it.

How it works?

The generated example.html file contains 3 parts.

  1. CSS
  2. layout via simple div
  3. the javascript configuration for DBSight

The javascript library will talk with DBSight, mostly via JSONP, and show results to the page.

How to customize it

You can customize all the generated content.

CSS

CSS is pretty simple and straight forward. Here you can customize the pagination's look and feel, the Suggest-As-You-Type, and almost anything that css can do.

Layout

Different from common javascript library, DBSight Embeddable Search library can present search results to several divs, instead of just one single div.

This allows great flexibility to render search results and integrate with your existing code.

Javascript

This javascript can almost do anything. And it's documented via Javadoc! Yes, that's right. Javadoc. Usually it's under

http://127.0.0.1:8080/dbsight/javadoc/com/dbsight/search/ui/client/Searcher.html

How to customize narrowBy search (facet search)?

Even facet search is customizable. With function

setStaticFacetHTML(String field, String html)

you can set html for any narrowBy search field.

What does the static facet html should look like?

It should look like this:

//one "all" entry with an input of empty value
<li><input type="checkbox" value=""/><label>All</label></li>
//several entries each with an input of non-empty value
<li><input type="checkbox" value="xxx"/><label>yyy</label></li>
<li><input type="checkbox" value="zzz"/><label>aaa</label></li>

There are minimum requirements for the html:

  1. Each entry is wrapped in <li>
  2. Each search value is stored in <input>
  3. Each displayed value is stored in <label>

That's all. You can have your own css applied to it and have different look and feels. DBSight by default have a "5stars" group-by facet defined. You can check it out also.

How to pass the html to setStaticFacetHTML() function?

There are many tricks. One of them is to put the html in hidden div, and use

setStaticFacetHTML("field_name_a", document.getElementById('some_hidden_div_id').innerHTML)

Common Customization Questions

How do I change text "show more" to "show a lot more"?

Almost all text used are customizable. For example,

 var s = new dbsight.Searcher();
 s.setText("show more", "show a lot more");

How to add/customize Suggest-As-You-Type?

Very simple:

 var s = new dbsight.Searcher();
 s.addSuggestion();

The look and feel may be different from what you need. You would need to adjust the css.

How to adjust the list of the results?

The list of results are still rendered via FreeMarker on server side. So you can just change documents.ftl file to get a different display.

How to redirect to this page?

A very common quesiton: If you have already setup this page, but the initial search comes from a different page, how to display search results when users are directed to this page?

The answer is, you can pass url paramters to this page also. The javascript will get the parameter value and display the search results.

Let's say your page is called search.php. When a user is redirected to this URL

search.php?q=dog

The browser will get everything generated from search.php, and DBSight javascript library will read the value "q", search on DBSight, and display the search results.

The "q" is just one of the parameter. The list of supported initial url parameter names are:

q
sortBy
start
length

As you can see, with these parameters, you can have bookmarkable searches.

If you need anything, just let us know! We do want it to work for you!