Documentation > SearchG2 API

Search G2 API

CrownPeak Search G2 is based upon industry standard crawling, indexing & querying components maintained by Apache Software Federation. The CrownPeak service delivers these core capabilities within a very highly scalable, high-performance, fault tolerant cloud-based service.

Overview

Search G2 supports a wide variety of features, capabilities and use cases:

  • Single-byte, double-byte, and multi-byte character sets, including UTF-8 and UNICODE
  • Auto language detection for over 30 languages
  • Stemming, spell-checking and auto-suggestions
  • Auto-correct and did-you-mean
  • Faceting
  • HTML, XML, CSV, JSON output, fully-integrated with CrownPeak CMS templates
  • Basic, NTLM and digest authentication

In addition, CrownPeak Search G2 supports standard Lucene query language, which allows you to query the service and retrieve the results in virtually any format or structure. Search G2 also includes powerful SDKs to help developers deliver exceptionally sophisticated experiences in a matter of a few lines of code. The core SDKs are available in JavaScript for client-side applications and .NET for server-side and include examples for jQuery, Knockout, and standard JavaScript.

Setup & Configuration

There is a three step process to enable CrownPeak Search in your website.

Step 1 - Create a Collection

The first step is to create a CrownPeak Search Collection. The Collection contains the website index definition and corresponding crawling rules. Please submit a ticket to support@crownpeak.com. This step also can be completed in the CMS (in the upcoming 2015 November release) by creating a SearchG2 connector in your instance. Here is how:

    1. 1. Log into your instance with an account that has administrative privileges
    2. 2. Navigate to [Settings] / [Configuration] / [Connectors]
    3. 3. Click [Add an Account] and select the SearchG2 connector (Magnified Glass with the CrownPeak logo)
    4. 4. Provide an name for the collection that is similar to the website name (i.e.: developer.crownpeak.com)
    5. 5. Click the [Seeds] tab and enter the starting point URL for the website to be crawled (i.e.: http://developer.crownpeak.com/)
    6. 6. Click the [Extractors] tab and enter the crawling rules for the website. See the example below
    7. 7. Click [Save] button at the bottom of the page
Sample Crawling Rules
<config xmlns="http://bayan.ir" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xsi:schemaLocation="http://bayan.ir 
http://raw.github.com/BayanGroup/nutch-custom-search/master/zal.extractor/src/main/resources/extractors.xsd">
<fields>
<field name="url" />
....

Connector Page

Figure 1. Search G2 Collection Connector

Step 2 - Add a Search Request Control to Your Webpage 

The second step is to create a control on your website to capture the search requests. This is typically added to the header of your website in the top left of right side of the website. In the CMS, this is typically placed in the "Asset Wrapper" in one place and then all of the pages of the website will have the new search control. Here is how:

    1. 1. Log into your instance with an account that has administrative privileges
    2. 2. Click Search icon (Magnifying glass) at the top of the page
    3. 3. Type in the word "NavWrap" and press the [Search] button
    4. 4. Select the Asset Wrapper file that is associates with your website (i.e.: /System/Templates/MyWebsite/Shared/NavWrap)
    5. 5. Edit the Output template file by double clicking in the file named "Output.aspx"
    6. 6. Locate where you want to place the Search Request control and add the block of form code. See the example below
    7. 7. The form code will post the results to the results page (i.e. /MyWebSite/search) referenced in the GetLink() method
    8. 8. Press the [Save] button at the bottom of the page
    9. 9. Navigate to your website homepage in the CMS and verify the Search Request control is appearing as expected 

Search Request Control Sample Form (JavaScript)

<form action="<%=Asset.Load("/MyWebSite/search").GetLink()%>" 
method="GET" class="form-search" onsubmit="if (window.navigating) return false"> 
<fieldset>
<legend>form search</legend> 
<input type="submit" value="GO">
<span class="field"><input type="text" placeholder="Search..." title="Search" id="searchField" name="q"></span>
</fieldset>
</form>

Step 3 - Create the Search Results Page using the Search G2 API

The last step is to create a Search Results page where users will see the output of the search requests. This is a single page that can be configured with a number of advanced settings. CrownPeak provide a rich set of API calls to craft a search results page that meets your needs. Here is how:

    1. 1. Log into your instance with an account that has developer privileges
    2. 2. Click Search icon (Magnifying glass) at the top of the page
    3. 3. Type in the word "Search Results" and press the [Search] button
    4. 4. Select the Search Results sample page (i.e.: /System/Templates/SampleSite/Search Results)
    5. 5. Copy this asset and paste into your website home directory (i.e.: /System/Templates/MyWebsite/Search Results)
    6. 6. Open then new asset and edit the Output template file by double clicking in the file named "Output.aspx"
    7. 7. Update the new search results page based on your needs. The next section provides customization suggestions
    8. 8. Press the [Save] button at the bottom of the page
    9. 9. Navigate to your website homepage in the CMS and verify the Search Results page is appearing as expected 

Customizing the Search Results Page

Under the main HTML, you will see a new instance of the CrownPeakSearch class being created, and then the instance being configured. This is where you can make the changes that you need to the search functionality and results.

  • rows(integer)
    Set the number of rows to return in a page of data (defaults to 10)
  • timeout(integer)
    Sets the number of milliseconds allowed for the query to execute (defaults to 5000)
  • collection(collection-name”)
    Provide the collection name that was set up for you on the SearchG2 server
  • language(language”)
    Adds a filter query “language:your-language”to your query, to restrict the result set to those in your chosen language (defaults to “”–all languages)
  • spellcheck(true|false)
    Whether to spell-check your query and return suggestions or not (defaults to false)
  • highlight(true|false)
    Whether to provide highlighted snippets with content matching the query (defaults to false)
  • highlightSeparator(“separator”)
    Set the separator to render between individual highlights (defaults to “…“)
  • sort([sort-field asc|desc”,…])
    Set the desired sort order on the results (defaults to “score desc”)
  • facets([“facet-field”,…])
    Get counts of facets to go with the results (TODO: better description!)
  • maxFacets(n)
    Set the maximum number of facets to be returned for each field (defaults to 5)
  • resultProxy(url)
    Set a proxy url (returned in the proxy_url property on each result) which can be used for analytics purposes. The url of the search result will be appended to this value. Two macros can be used in this string: %%query%% will be replaced with the user’s query, and %%index%% will be replaced with the zero-based index of the result in the result set.
  • parameters(additional-parameters”)
    A way for you to include additional Solr parameters with your query. These will be appended to the query when it is executed. Multiple values can be provided; these should be URL-encoded and in the form “&field=value&field2=value2”.
  • handler(“handler-name”)
    Allows you to choose a different Solr hander for your query (defaults to select”)
  • geo(geospatial search parameters)
    Allows you to use geospatial search options, including distance calculations, and sorting and filtering by range. Pass in a JSON object like:
    {
      “location”: { “lat”: number, “lon”: number }, // or “lat,lon” string
      “field”: “Search G2 field containing your location data (default custom_p_location)”,
      “outputfield”: “field in which you want the distance returned (default _dist_)”,
      “range”: { “distance”: number, “unit”, “meter, km or mile” } // or number in km
    }
    Note: all parameters except for location are optional.
    Note: if no other sort order has been specified, providing valid geospatial search parameters will also sort your results into order of ascending distance from the location, beginning with the closest.

Formating the Search Results Page

There are also a number of different KnockoutJS bindings used in the sample search results, and you can remove those providing functionality that you do not require for example did you mean, faceting, etc.

This demonstrates many common requirements with each search result:

  • Show a number of stars to denote how relevant the result is to the users query
  • Show an icon denoting what type of content this result contains (i.e. pdf, doc, etc.)
  • Show the index of the result within the full result set
  • Show a default where the field was not present in the original document
  • Show highlighted content if highlights were available, or the original if not
  • Trim content to a particular maximum length
  • Show the last-modified date of the content (if the data is available)

In addition, a number of other useful features and functions are demonstrated:

  • Did you meanfunctionality, showing the number of matches this revised query would return
  • Simple pager, showing numeric links for each page in the results
  • Display of results facets, with click-through to add this facet as a filter to your query
  • Autocomplete, searching once you have typed at least 3 characters into the search field

Search Results

Figure 2. Search G2 Results Page

Sample Search Results - Java Script

You can find the complete example at: https://github.com/Crownpeak/Search-Results-Examples.git

Open the sample.html file directly using your favorite web browser, and it should make a connection to searchg2.crownpeak.net and query the contents of the www.crownpeak.com collection. Next, make a copy of the sample on your local development environment, and then open sample.html in a text editor. To learn more about KnockoutJS, visit: http://knockoutjs.com/
In the head of the page, you will see the various scripts that are used for this example:

  • crownpeak.searchg2-{version}.js is the CrownPeak Search G2 core, hosted on CrownPeak’s CloudFront CDN
  • crownpeak.searchg2.autocomplete-{version}.js contains supporting functionality to enable auto-complete on a search field. If you do not need autocomplete functionality, you can remove this line
  • KnockoutJS is used to perform data-binding for this sample script. This is not a requirement to use CrownPeak SearchG2, and you can remove this line and bind your data differently if you prefer

Sample Search Results - C#

You will need the CrownPeak.SearchG2.dll located in the /bin folder: https://github.com/Crownpeak/Search-Results-Examples/tree/master/SearchG2%20DLL

We have create two example projects: one for WebForms one and for MVC: https://github.com/Crownpeak/Search-Results-Examples/tree/master/ASP.NET

For either architecture, in order to implement your own search, first you should create a new class to hold each search result. This must inherit from CrownPeak.SearchG2.Result.ResultBase, and should implement the properties that you wish to retrieve from the index. The properties do not have to match exactly, and you can decorate your properties with attributes that describe exactly which field to use to populate it. For example:

public class MyResult : CrownPeak.SearchG2.Result.ResultBase
{
	[Field("url")]
	public string Url { get; set; }
	[Field("title")]
	public string Title { get; set; }
	[Field("content")]
	public string Content { get; set; }
	/// Match everything else and put it into a dictionary
	[Field("*")]
	public IDictionary<string, object> OtherFields { get; set; }
 }

In an MVC project, this class should go into the Models folder. For a Web Forms project, the class can go in any folder where it will be compiled; depending on your project type, this may be in App_Code or in the same folder as your search page. Next, if you are using a Web Forms project, make a new Web Form for your search interface and results. If you are using an MVC project, make a new Controller.

To execute the search operation against a CrownPeak SearchG2 collection, you should make a new instance of the CrownPeak.SearchG2.Search class, passing in the type of result that you want, and the collection name that you wish to query: var search = new Search<MyResult>(new Settings("www.crownpeak.com"));

You can then execute the search with a default set of options by using the Execute method: var results = search.Execute(queryString);

Connect with CrownPeak