updated manifest, renamed when_and_where

guide/when_and_where.rst → guide/choosing_pages.rst

@@ -1,28 +1,16 @@
-Managing when and where to launch addons
-========================================
-
-You can manage where (on what domains and pages) and when (on what special events) to launch your addon logic.
-
-Target domain
--------------
-Target domain is required for any addon. It should be defined in the **siteRegexp** field of the addon manifest.
-
-Use an regular expression to match target host name
-
-* ``google.com`` will fire on ``google.com`` and any subdomain
-* ``.google.com`` will fire on any subdomain of ``google.com``
-* ``^(?!www\.).*google.com`` will fire on any subdomain of ``google.com`` except ``www.google.com``
-
-Dots in samples above mean 'any character' if you want to use read dot symbol just escape it ``\.google\.com``
+Choosing specific pages to launch addons on
+===========================================
+You can limit addons launch to specific pages of a website.
 
 Important: when are addons launched
 -----------------------------------
-**Addons are launched on every DOM load** - it means, after user navigates to new page or reloads current one, or navigates back/forward in history to other page, or reopens previously closed page.
+**Addons are launched on every DOM load** - it means, after the user navigates to a new page or reloads the current one, or navigates back/forward in history to other page, or reopens a previously closed page. In all these cases a fresh new page is loaded in the browser and every addon that fits it is relaunched on it.
 
-**Addons are not launched on**:
+After an addon is launched on the page it will not be launched again (its ``start`` function will not be called).
+So **addons are not launched on**:
 
 * *hash change* - when just hash changes, page's DOM is not reloaded; if addon was already launched on this page it remains active, so no need in injecting and launching it again.
-* *programmatic manipulation with history* - if ``history`` object is modified programmatically without actual page change, previous addons also remain on the page so no need to launch them again.
+* *programmatic manipulation with history* - if ``window.history`` object is modified programmatically without actual page change, previous addons also remain on the page so no need to launch them again.
 
 So there are different approaches on managing addons for :ref:`sites-reloading-pages` and :ref:`fully-dynamic-sites` (usually single-page applications)
 
@@ -88,7 +76,6 @@ Entry points are contained in object ``pages`` - there are two records with fiel
 * ``path`` - a string representation of a Regexp
 * ``entryPoint`` - a string name of current entryPoint
 
-
 On a new page load, entryPoints are iterated in the order they are given in config:
 
 * the first entryPoint with ``path`` that fits ``location.pathname`` is chosen as resulting entryPoint and addon is applied - it's ``start`` function receives resulting entryPoint name as a second parameter.

guide/guide_index.rst

@@ -6,7 +6,7 @@ Developer's Guide
 
   manifest
   writing_js
-  when_and_where
+  choosing_pages
   debugging_and_troubleshooting
   writing_css
   storing_data

guide/manifest.rst

@@ -29,22 +29,26 @@ A manifest example:
 
 Manifest description (**mandatory** fields are in bold):
 
-* **id** - Unique name of an addon. Should consist of lowercase letters, digits and hyphens. Usually contains target application's name and addon purpose.
+* **id** - unique name of an addon. Should consist of lowercase letters, digits and hyphens. Usually contains target application's name and addon purpose.
 
-* **js** - Relative path to addon's Javascript file from the folder that contains the manifest
+* **js** - relative path to addon's Javascript file from the folder that contains the manifest
 
-* **title** - Addon title
+* **title** - addon title
 
-* **siteName** - Name of the target application or website. It is also used to group addons for the same applications in `addons list <http://tai.st/app#/addons>`_
+* **siteName** - name of the target application or website. It is also used to group addons for the same applications in `addons list <http://tai.st/app#/addons>`_
 
-* **siteRegexp** - Regular expression to match :doc:`target domain name </guide/when_and_where>`.
+* **siteRegexp** - regular expression to match the domain name of a target website. Typical use cases:
+
+  * **a single common domain** is used for all the customers of the application - just use plain text like ``drive.google.com``
+  * **a separate subdomain for every customer** is used - just add ``.`` in the beginning: ``.someapp.com`` will run on ``customer1.someapp.com`` and ``customer2.someapp.com`` but will skip the marketing website `someapp.com`
+  * **in other cases** just use an appropriate regular expression
 
 * **shortDescription** - Short addon description in plain text
 
 * ``css`` - relative path to addon's CSS file
 
 * ``description`` - relative path to a file with detailed addon's description. `Markdown <https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet>`_ can be used in it.
 
-* ``pages`` - array of entry points to :doc:`limit a set of pages to launch an addon on </guide/when_and_where>`. Is not set in the example above as it can be used only for non-single page applications.
+* ``pages`` - array of entry points to :doc:`limit a set of pages to launch an addon on </guide/choosing_pages>`. It is not set in the example above as it can be used only for non-single page applications.
 
 .. toctree::

guide/writing_js.rst

@@ -22,4 +22,4 @@ Arguments of ``start`` function:
 * ``taistApi`` is an object that provides access to all Taist features. All the features are described in other chapters of this guide.
   In ``doWork`` we see use of ``log`` function - it's a preferred way of :doc:`Debug output </guide/debugging_and_troubleshooting>`.
 
-* ``entryPoint`` is used for :doc:`fine-tuning </guide/when_and_where>` of what addon parts to launch on what pages of target site.
+* ``entryPoint`` is used for :doc:`fine-tuning </guide/choosing_pages>` of what addon parts to launch on what pages of target site.