CloudSh Widget Documentation

The Widget can be customized with options passed into the widget.

The Options

The Widget is configured with a CshConf object definded in the page. Here are the options and the defaults.

Option	Default	Description
token	null	The TOKEN from the CloudSh dashboard Required
resultsId	#results	The querySelector for the results container
queryInput	#q	The querySelector for the search input field
perPage	10	The number of results to return per page
showImages	false	Show results images or not
placeHolderImage	see below	The image to use for pages that didn't have an image when crawled
skipStyles	false	When true, don't use any widget styles
customStyles	empty string	Add some custom styles to the default widget styles
showSuggestions	true	Show search suggestions when typing in the queryInput field
spinnerCss	see below	The CSS used for the spinner while fetching results
spinnerTemplate	see below	The HTML template for the spinner
resultTemplate	see below	The HTML template for the results
notFoundTemplate	see below	The HTML template for no results found
pagingTemplate	see below	The HTML template for paging when multiple pages
resultSummaryTemplate	see below	The HTML template for the results summary
suggestTemplate	see below	The HTML template for the search suggestions

To set an option, add it to the CshConf object. This example turns showSuggestions off.

var CshConf = {
    token: "TOKEN",
    showSuggestions: false
  };

Option Details

token

This is the only required option. Create a new token in your CloudSh account.

resultsId

A querySelector to choose the container for the results container. The default is #results.

All templates except the suggestTemplate will be rendered in this container.

queryInput

A querySelector to choose the input field(s) for the query. The default is #q. This is how the Widget gets the query to search for. It also uses this to set the field value to a query passed by the q query string value.

perPage

The number of results to return on one page. The default is 10.

This can be set between 1 and 100.

showSuggestions

This turns on/off the search suggestions that appear as your typing in the query input.

showImages

This turns images on/off in the results. ClousdSh will try to find an image for the pages when crawling. Turning this option on will show thumbnails for the pages.

placeHolderImage

When showImages is on, you can provide a custom placeholder image for pages that don't have an image. The default is https://cloudsh.com/images/placeholder.png, a blank image.

skipStyles

If you want to provide all your own styles, you can enable this option. You will have to provide styles for everything, including the spinner.

When skipStyles is true, the Widget won't add any styles to the page, including customStyles.

customStyles

If you want to add some styles to the provided styles, you can provide a CSS string here that will be appended to the default styles.

If skipStyles is on, these custom styles also won't be added to the page.

var CshConf = {
  token: "TOKEN",
  customStyles: '#results { border: solid 1px black; }'
}

spinnerCss

If you change the spinnerTemplate, can update the CSS with this option. Or remove the CSS when it's not needed.

The default CSS:

.spinner{margin:100px auto;width:50px;height:40px;text-align:center;font-size:10px}.spinner > div{background-color:#333;height:100%;width:6px;display:inline-block;margin:0 4px 0 0;padding:0;-webkit-animation:sk-stretchdelay 1.2s infinite ease-in-out;animation:sk-stretchdelay 1.2s infinite ease-in-out}.spinner .rect2{-webkit-animation-delay:-1.1s;animation-delay:-1.1s}.spinner .rect3{-webkit-animation-delay:-1.0s;animation-delay:-1.0s}.spinner .rect4{-webkit-animation-delay:-0.9s;animation-delay:-0.9s}.spinner .rect5{-webkit-animation-delay:-0.8s;animation-delay:-0.8s}@-webkit-keyframes sk-stretchdelay{0%,100%,40%{-webkit-transform:scaleY(0.4)}20%{-webkit-transform:scaleY(1.0)}}@keyframes sk-stretchdelay{0%,100%,40%{transform:scaleY(0.4);-webkit-transform:scaleY(0.4)}20%{transform:scaleY(1.0);-webkit-transform:scaleY(1.0)}}

Templates

Templates are rendered using the Mustache template engine.

spinnerTemplate

<div class='spinner'><div class='rect1'></div><div class='rect2'></div><div class='rect3'></div><div class='rect4'></div><div class='rect5'></div></div>

resultTemplate

var resultTemplate = `
<div class="result">
{{#image}}
  <img src="{{ image }}" width="150" height="90" />
{{/image}}
<b><a class="csh-link" href="//{{ url }}" data-rank="{{ rank }}">{{ title }}</a></b>
<p>
  {{ description }}
</p>
</div>`

notFoundTemplate

<p>No results for {{ query}}.</p>

pagingTemplate

<div class="paging">
<ul>
  {{#prev}}
  <li><a href='?q={{ q }}&s={{ start }}'>Prev</a></li>
  {{/prev}}
  {{#next}}
  <li><a href='?q={{ q }}&s={{ start }}'>Next</a></li>
  {{/next}}
</ul>
</div>

resultSummaryTemplate

<h3>Results</h3><p>Found {{ hits }} results.</p>

suggestTemplate

<div id="csh-sg" class="csh-suggest">
{{#urls}}
  <div>
    <a class="csh-link" href="{{ url }}" data-rank="{{ index }}">{{ title }}</a>
  </div>
{{/urls}}
</div>

Query Strings

The Widget will look for a q query string value in the URL.

When it finds one it will perform the search using that value and set the queryInput field value. This allows refresh to work.

You can also have a form submit to the search page and perform the search. For example if you want a search box on all pages of the site you could add a form like this.

<form method="get" action="/my-search-page">
    <input name="q" id="q" placeholder="search" type="text"></input>
    <button>Search</button>
</form>

The important parts to notice, the form tag has method and action attributes. And the queryInput field has a name attribute. The name attribute must be q.

You can also link to a search result page by adding the q query string to the URL.

<a href="/my-search-page?q=cars">Cars</a>

Documentation

Generators