search/product_search_python/static/instrs.html

   1 <?xml version="1.0" encoding="UTF-8" ?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1 plus MathML 2.0//EN"
   3 "http://www.w3.org/TR/2001/REC-MathML2-20010221/dtd/xhtml-math11-f.dtd">
   4
   5 <html xmlns="http://www.w3.org/1999/xhtml">
   6 <head>
   7   <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
   8   <link rel="stylesheet" type="text/css" href="./css/byword.css"/>
   9   <title>README</title>
  10 </head>
  11
  12 <body>
  13   <div id="wrapper">
  14     <div id="content">
  15 <h1>Full-Text Search Demo App: Product Search</h1>
  16
  17 <h2>Introduction</h2>
  18
  19 <p>This Python App Engine application illustrates the use of the <a href="https://developers.google.com/appengine/docs/python/search">Full-Text Search
  20 API</a> in a &#8220;Product
  21 Search&#8221; domain with two categories of sample products: <em>books</em> and
  22 <em>hd televisions</em>. This README assumes that you are already familiar with how to
  23 configure and deploy an App Engine app. If not, first see the App Engine
  24 <a href="https://developers.google.com/appengine/docs/python/overview">documentation</a>
  25 and <a href="https://developers.google.com/appengine/docs/python/gettingstarted">Getting Started guide</a>.</p>
  26
  27 <p>This demo app allows users to search product information using full-text search,
  28 and to add reviews with ratings to the products. Search results can be sorted
  29 according to several criteria. In conjunction with listed search results, a
  30 sidebar allows the user to further filter the search results on product rating.
  31 (A product&#8217;s rating is the average of its reviews, so if a product has no
  32 reviews yet, its rating will be 0).</p>
  33
  34 <p>A user does not need to be logged in to search the products, or to add reviews.
  35 A user must be logged in <strong>as an admin of the app to add or modify product
  36 data</strong>. The sidebar admin links are not displayed for non-admin users.</p>
  37
  38 <h2>Configuration</h2>
  39
  40 <p>Before you deploy the application, edit <code>app.yaml</code> to specify your own app id and version.</p>
  41
  42 <p>In <code>templates/product.html</code>, the Google Maps API is accessed. It does not require an API key, but you are encouraged to use one to monitor your maps usage. In the <head> element, look for:</p>
  43
  44 <pre><code>src=&quot;https://maps.googleapis.com/maps/api/js?sensor=false&quot;
  45 </code></pre>
  46
  47 <p>and replace it with something like the following, where <code>replaceWithYourAPIKey</code> is your own API key:</p>
  48
  49 <pre><code>  src=&quot;https://maps.googleapis.com/maps/api/js?sensor=false&amp;amp;key=replaceWithYourAPIKey&quot;
  50 </code></pre>
  51
  52 <p>as described <a href="https://developers.google.com/maps/documentation/javascript/tutorial#api_key">here</a>.</p>
  53
  54 <h2>Information About Running the App Locally</h2>
  55
  56 <p>Log in as an app admin to add and modify the app&#8217;s product data.</p>
  57
  58 <p>The app uses XG (cross-group) transactions, which requires the dev_appserver to
  59 be run with the <code>--high_replication</code> flag. E.g., to start up the dev_appserver
  60 from the command line in the project directory (this directory), assuming the
  61 GAE SDK is in your path, do:</p>
  62
  63 <pre><code>dev_appserver.py --high_replication .
  64 </code></pre>
  65
  66 <p>The app is configured to use Python 2.7. On some platforms, it may also be
  67 necessary to have Python 2.7 installed locally when running the dev_appserver.
  68 The app&#8217;s unit tests also require Python 2.7.</p>
  69
  70 <p>When running the app locally, not all features of the search API are supported.
  71 So, not all search queries may give the same results during local testing as
  72 when run with the deployed app.
  73 Be sure to test on a deployed version of your app as well as locally.</p>
  74
  75 <h2>Administering the deployed app</h2>
  76
  77 <p>You will need to be logged in as an administrator of the app to add and modify
  78 product data, though not to search products or add reviews. If you want to
  79 remove this restriction, you can edit the <code>login: admin</code> specification in
  80 <code>app.yaml</code>, and remove the <code>@BaseHandler.admin</code> decorators in
  81 <code>admin_handlers.py</code>.</p>
  82
  83 <h2>Loading Sample Data</h2>
  84
  85 <p>When you first start up your app, you will want to add sample data to it.
  86 </p>
  87
  88 <p>Sample product data can be added in two ways. First, sample product data in CSV
  89 format can be added in batch via a link on the app&#8217;s admin page. Batch indexing
  90 of documents is more efficient than adding the documents one at a time. For consistency,
  91 <strong>the batch addition of sample data first removes all
  92 existing index and datastore product data</strong>.</p>
  93
  94 <p>The second way to add sample data is via the admin&#8217;s &#8220;Create new product&#8221; link
  95 in the sidebar, which lets an admin add sample products (either &#8220;books&#8221; or
  96 &#8220;hd televisions&#8221;) one at a time.</p>
  97
  98 <h2>Updating product documents with a new average rating</h2>
  99
 100 <p>When a user creates a new review, the average rating for that product is
 101 updated in the datastore. The app may be configured to update the associated
 102 product <code>search.Document</code> at the same time (the default), or do this at a
 103 later time in batch (which is more efficient). See <code>cron.yaml</code> for an example
 104 of how to do this update periodically in batch.</p>
 105
 106 <h2>Searches</h2>
 107
 108 <p>Any valid queries can be typed into the search box. This includes simple word
 109 and phrase queries, but you may also submit queries that include references to
 110 specific document fields and use numeric comparators on numeric fields. See the
 111 Search API&#8217;s
 112 <a href="https://developers.google.com/appengine/docs/python/search">documentation</a> for
 113 a description of the query syntax. </p>
 114
 115 <p>Thus, for explanatory purposes, the &#8220;product details&#8221; show all actual
 116 field names of the given product document; you can use this information to
 117 construct queries against those fields. In the same spirit, the raw
 118 query string used for the query is displayed with the search results.</p>
 119
 120 <p>Only product information is searched; product review text is not included in the
 121 search.</p>
 122
 123 <h3>Some example searches</h3>
 124
 125 <p>Below are some example product queries, which assume the sample data has been loaded.
 126 As discussed above, not all of these queries are supported by the dev_appserver.</p>
 127
 128 <p><code>stories price &lt; 10</code><br/>
 129 <code>price &gt; 10 price &lt; 15</code><br/>
 130 <code>publisher:Vintage</code><br/>
 131 <code>Mega TVs</code><br/>
 132 <code>name:tv1</code><br/>
 133 <code>size &gt; 30</code></p>
 134
 135 <h2>Geosearch</h2>
 136
 137 <p>This application includes an example of using the Search API to perform
 138 location-based queries. Sample store location data is defined in <code>stores.py</code>,
 139 and is loaded along with the product data. The product details page for a
 140 product allows a search for stores within a given radius of the user&#8217;s current
 141 location. The user&#8217;s location is obtained from the browser.</p>
 142     </div>
 143   </div> <!-- End wrapper -->
 144 </body>
 145 </html>