PubTools -------- Author: * Brad Neuberg Contributors: * Thibaud Lopez Schneider Introduction ------------ PubTools is a simple collection of JavaScript files that make it easy for content authors to work with Gears without having to delve into JavaScript themselves. PubTools includes two different libraries and features: * PubTools Offline - A simple JavaScript library that makes it easy to take static content offline using just basic HTML added to your page, along with a utility bookmarklet for developers to quickly generate Gears manifest files for a given web page. * PubTools Search - A JavaScript library that drops a client-side search engine into your page. You configure it with basic HTML + a list of URLs to index, and a search form that uses the local Gears full-text search abilities will appear in your page to quickly locally search over the documents in real time as a user types into the search field. A demo for PubTools Offline is in demos/offline/demo.html A demo for PubTools Search is in demos/search/demo.html. Please note that the demos must be run from a local web server (i.e. http://localhost) rather than the filesystem (ex: file://demos/offline/demo.html) for the code to function reliably on all browsers. If you are new to Gears, PubTools is also a great source of sample code for working with the Gears library, and since its open source under an Apache license you can freely use the code as a source of code snippets and solutions. Also see http://gears.google.com for more information and details on Gears itself. Using PubTools Offline ---------------------- PubTools Offline is a JavaScript library that makes it easy to take static content offline. It also acts as easy sample code for you to look at when creating your own Gears-based applications. 1) Use the PubTools bookmarklet to create a Gears manifest file. Go to src/manifest-bookmarklet.html and follow the directions. Save this to a file, such as manifest.js. 2) In the web page you want to offline-enable, pull in PubTools JavaScript file: 3) Point to your Gears manifest file: 4) If you want a desktop shortcut icon, add shortcut="true": You must provide at least one icon in PNG format; possible sizes are 16x16, 32x32, 48x48, 128x128. Providing all of them is best to allow OS to choose the best one. Specify them using a LINK tag: By default, PubTools chooses intelligent defaults for the shortcut icon. You can override these if you wish using META tags: Most of these have sensible defaults and can be left out: 'shortcut.name' defaults to the HTML TITLE element if not present. 'shortcut.url' defaults to the page's URL if not present. 'shortcut.description' is optional and defaults to the string "Offline Web Application" 5) PubTools provides a simple default, optional UI for the user. To get this UI, add an element with the magic ID "gears-pubtools-offline-widget" into your HTML: When the page loads, the user will see "Download Offline." When pressed, everything in the manifest is made offline and the shortcut icon is created if desired, with the user given feedback on the process. Now, the user will see "Delete Offline." By pressing this a user can delete the offline resources and start over at a later date. If you don't want the default UI, your custom UI can call PubTools.downloadOffline() to initiate the download of offline-resources, and can call PubTools.deleteOffline() to delete the offlined content. These can only be called after the page is loaded. 6) That's it! You're done. See demos/offline/demo.html for a demo and boilerplate you can copy. Quick note: Make sure _not_ to include the pubtools-offline.js file in your manifest. The manifest generator takes this into account to leave this out, but if you create it by hand leave it out. We do a trick where when you are offline we simply don't have the file, which doesn't display the default UI to the user since it makes no sense to show that when offline. Using PubTools Search --------------------- 1) Add the PubTools Search CSS and JavaScript to your web page: 2) Create a file named search.txt that is in the same directory as your HTML page. This file will contain a list of URLs that you want to index locally and search over. The URLs are relative to the HTML file. Example: version=0.6 ../resources/descartes.txt ../resources/goethe.txt ../resources/goldman.txt ../resources/machiavelli.txt ../resources/montaigne.txt ../resources/kafka.html ../resources/plato.html The first line must have a version, such as 'version=0.6'. When this version changes, such as if you add, modify, or remove a document, then PubTools Search will reindex the documents. Following the version string you must have a URL to index, one on each line. The client-side search can only index HTML, text, and XML files. A good tip is to make sure any HTML documents you want to index have a TITLE element in the HEAD; this will be the title of the document that is returned for search results. For XML and text files we use the URL as the title. 3) Add a DIV to your page with the following ID: When PubTools Search loads it will put the search UI box into this DIV. 4) That's it, you're done! Sample code and a demo can be seen at demos/search/demo.html. Optional configuration: You can over-ride the search filename and the ID that is filled in with a LINK and META tag in the HEAD part of your document. Examples: You can also control whether search happens automatically as a user types: This defaults to true. It is useful to turn this off when dealing with corpuses that are very large and might be slower to search over. Also, you can skip the filtering step and force the MIME type to a certain value. This can speed things up for very large corpuses as well if you know that all of your documents are HTML, for example: By default, PubTools Search will put the focus into the search field on page load. If you want to disable this behavior, use the following: Please note that PubTools Search and PubTools Offline can not currently be used on the same page, since PubTools Search does not work offline yet. Known Issues ------------ * PubTools Offline and PubTools Search can not be used on the same page currently, as PubTools Search has not been modified to work offline yet. * The markup for PubTools Offline is not XHTML compliant; it is on the TODO list to replace the custom attributes with LINK and META tags. PubTools Search _is_ XHTML compliant since it already uses LINK and META tags for configuration. * The ID to drop the PubTools Offline widget into the page is currently pretty long ('gears-pubtools-offline-widget'). I plan on shortening the ID name considerably.