examples/htdocs/mkws-widget-ru.readme

   1 # Embedding Reference Universe with MKWS
   2
   3 ## Quick start
   4 Simply paste this inline with the markup on any page:
   5
   6     <script src="//mkws.indexdata.com/mkws-complete.js"></script>
   7     <script>var mkws_config = { sp_auth_credentials: "paratext/paratext_mkc" }</script>
   8     <link rel="stylesheet" type="text/css" href="//mkws.indexdata.com/mkws-widget-ru.css" />
   9     <div class="mkws-reference-universe" autosearch="!param!q"></div>
  10
  11 ## A bit more detail
  12
  13 The MasterKey Widget Set ([MKWS](http://mkws.indexdata.com/)) lets you easily embed search-enabled widgets which run in the client browser and display results from a web service. In this case, it searches Reference Universe.
  14
  15 You need to include the main MKWS scripts. This can be inline as above or you can include it in the header or aggregate it with your application's scripts.
  16
  17     <script src="//mkws.indexdata.com/mkws-complete.js"></script>
  18
  19 You also need to tell the widget how to authenticate onto the searching service:
  20
  21     <script>var mkws_config = { sp_auth_credentials: "paratext/paratext_mkc" }</script>
  22
  23 The provided stylesheet is generic and you're encouraged to replace it entirely by styling the new elements to fit seamlessly with your content.
  24
  25     <link rel="stylesheet" type="text/css" href="//mkws.indexdata.com/mkws-widget-ru.css" />
  26
  27 Any element you give the class `mkws-reference-universe` will have is contents replaced by the top results from a search against the Reference Universe service for the current query.
  28
  29     <div class="mkws-reference-universe" autosearch="!param!q"></div>
  30
  31 ### Finding the query
  32
  33 The `autosearch` attribute of the widget container lets it know where to find the query. There are three places it might look to find that you're searching for *water*:
  34
  35 * `!param!foo` indicates a GET parameter and would match `http://site.tld/search?foo=water`
  36 * `!path!2` will take the 2nd path component from the end of the url and would find the query in `http://site.tld/apps/search/water/mobile`
  37 * `!var!foo` will look for the query in a JavaScript variable named `foo` in the `window` context (ie. a top level variable)