Integration with existing systems

From DBSight Full-Text Search Engine/Platform Wiki

Table of contents

JSONP based integration

The problem

  1. Many sites already have quite some page with a consistent UI Look and Feel. It's kind of hard to mimic existing UI in DBSight templates.
  2. Many sites are not coded in Java, and dealing with XML/JSON seems easy, but can get complicated.
  3. It takes a lot of effort to re-invent all the complicated widgets, like narrowBy, pagination, sorting, etc.

See a demo first

For a real example, Please see the dbsight.net's "Search Forum" feature, which is on top of each page. The css is pretty basic. I am sure you can do much better.

The Super Easy Solution

Use javascript to search on DBSight, and render results. It only change via javascript, and doesn't affect your site's layout.

The communication between your page and DBSight server is via JSONP. So your page, the DBSight javascript, and the DBSight server does not even need to be on the same web server.

Step 1 Add a Search Input Box on existing page

In your existing page, add an input box

<input type="text" id="dbsight_input">

You can put it anywhere.

Step 2 Add javascripts

   <script type="text/javascript" language="javascript" src="http://www.dbsight.net/search/search.nocache.js"></script>
   <script language="javascript">
   	function dbsightOnLoad(){
   		new dbsight.Searcher().server("http://dbsight-server:8080/dbsight")
               .indexName("foxsaver")
   		.setup();
   	}
   </script>

Remember to change the "dbsight-server" part to your own location.

And change the javascript location from official site to your own server's location, like

http://dbsight-server:8080/dbsight/search/search.nocache.js

This is because the official release will always be the latest release, and will have changes you may not be ready for.

Step 3 Add Basic Style SheetLayout HTML

Of course, here you can get very fancy here. But let's do the basics first.

<style>
.pagination {
   font-size: 80%;
}
.pagination a {
    text-decoration: none;
    border: solid 1px #AAE;
    color: #15B;
}
.pagination a, .pagination span {
    display: block;
    float: left;
    padding: 0.3em 0.5em;
    margin-right: 5px;
    margin-bottom: 5px;
}
.pagination .current {
    background: #26B;
    color: #fff;
    border: solid 1px #AAE;
}
.pagination .disabled{
    color:#999;
    border-color:#999;
    background:#fff;
}
</style>

Step 4 Add Layout HTML

You can organize your layout anyway you want. All of the "dbsight_..._div" div ids are optional, except "dbsight_results_div".

Here is one example you can start with:

   <table align="center" width="100%">
     <tr>
       <td valign="top" width="15%">
         <div id="dbsight_narrowBy_div"></div>
       </td>
       <td valign="top" width="85%">
         <div>
   	   <div style="float:right">
           <strong id="dbsight_results_count_div"></strong> results 
           in <strong id="dbsight_searchTime_div"></strong> seconds.
          </div>
          <div style="float:right" id="dbsight_sort_div"></div>
         </div>
         <div style="clear:both"></div>
         <div id="dbsight_pagination_div"></div>
         <div style="clear:both"></div>
         <div id="dbsight_results_div"></div>
       </td>
     </tr>
   </table>

Step 5 Add Result Template on DBSight

Oh, of course, you need to create a default template on DBSight. Currently, only "documents.ftl" file are actually used by the DBSight JSONP javascript library.

The documents.ftl rendered HTML text are sent over to your page and displayed directly.

That's it. Simple enough?

Customization

You would think, hmm, fine, seems good, but how to customize?

The javascript actually is generated via Java. (GWT, if you want to know more details). There are APIs to adjust all the knobs. Please check the Java doc that comes with DBSight installation. Usually it is:

http://localhost:8080/dbsight/javadoc

and check javadoc for com.dbsight.search.ui.client.Searcher

Customize Static NarrowBy Search

A static NarrowBy section always shows up and does not adjust the list of values. For example, a 5-star rating narrowBy section does not add/remove/re-order each stars.

Set Static HTML for a narrowBy search field

var searcher = new dbsight.Searcher();
searcher.server("...");
...
searcher.setStaticFacetHTML(any_html_text);

The any_html_text can come from anywhere. There are many ways to store this kind of large html text. A very common way is to store it in a hidden div, and use innerHTML() method to get it.

searcher.setStaticFacetHTML(document.getElementById("a_hidden_div_id").innerHTML);

Specs for Static HTML

The static HTML NarrowBy Search are very flexible to customize, as long as some basic HTML elements are used following this basic structure.

<li><input value=""><label>All</label></li>
<li><input value="search_filter_1"><label>Text for search filter 1</label></li>
<li><input value="search_filter_2"><label>Text for search filter 2</label></li>
...
<li><input value="search_filter_n"><label>Text for search filter n</label></li>

search_filter_n is the search filter for each category. For range filter, it should be either right-inclusive (x,y] or left-inclusive [x,y) format. Also, use float numbers in the search filter, even for integer range facet search. For example, (2,4], the search_filter should be (2.0,4.0].

CSS customization

Please check the run time structure for customizing the look and feel.

Set Style Name for a narrowBy search field

var searcher = new dbsight.Searcher();
searcher.server("...");
...
searcher.setFacetStyleName(field, any_css_style_name);

With the special css style name, you can adjust renderings freely by including your own css styles.

How to show the page?

All the layout, javascript, css are in a sort of static page without any content.

When users visit website, they usually search on some input box on an existing page. They should not visit this empty search page then start to search. How can the user see the results when they type in something on another page?

You can redirect the user to the search page appending a parameter, like this:

 http://yoursite.com/search.html?q=some_query

The parameter name "q" is customizable, to avoid any existing parameter name conflict.

Size of the javascript

The non compressed javascript right now is at 100KB, but gzipped version is only at 34.7KB. It's fairly small. And what's more, they are perfectly cache friendly, only need to be fetched once.

Proxy Based Solution

The question from a user

Is there an easy and fast way to integrate Search Results and related Templates on my own application context?

Because I would like to use you app way to show results and related templates (with freemarker and velocity) but If I do and integration like sending requests with your API, then it seems like I have to rewrite all code refering of processing view on my own app.

The possible solution

I think it'll be easier to write a proxy controller.

All the default DBSight templates generates relative URL like:

?q=...

without search.do

So you can write a controller in your own context, like dbsightProxy.do and send all the parameters to dbsight search.do, get the html results, and put it on the screen or mix it with your own html.

There is a special case, suggest-as-you-type feature, which is hard coded in javascript to suggest.do. But it should not be that difficult to adjust it.