Add 2.6-to-3.0 migration docs for Paginator.

docs/migration/2.6-to-3.0-paginator.adoc

@@ -0,0 +1,161 @@
+:idprefix:
+:idseparator: -
+:toc: right
+:toclevels: 2
+
+= Migrating `Paginator` from Lift 2.6 to Lift 3.0
+
+The 2.x series of Lift brought a lot of change and innovation. In particular,
+while it started with an approach based on the `bind` helper that transformed
+namespaced XHTML elements into the values that the developer wanted to display,
+it progressed to an HTML5-based approach built around CSS selector transforms.
+As of Lift 3.0, CSS selector transforms are the only supported transforms, so
+as to keep the core of the framework relatively lean and encourage proper HTML
+usage.
+
+One of the Lift components that leveraged the `bind`-style transforms heavily
+was `Paginator`. As of Lift 3.0, it's been reworked to use CSS selector
+transforms instead, which means you'll be moving from placeholder elements that
+use XML namespaces to regular HTML elements with appropriate classes.
+
+== Bind Points
+
+In the old `Paginator`, bind points were elements with the namespace `navPrefix`
+and various names, e.g. `nav:first` for the link pointing to the first page.
+Lift 3.0 instead looks for certain CSS classes in elements. Here's a mapping
+from old `nav:*` elements to CSS classes:
+
+.Lift 2.6 wizard element to Lift 3.0 CSS class mapping
+|=========================
+| Lift 2.6 Element                | Lift 3.0 CSS Class
+
+| `nav:first`                     | `first`
+
+| `nav:prev`                      | `prev`
+
+| `nav:allpages`                  | `all-pages`
+
+| `nav:zoomedpages`               | `zoomed-pages`
+
+| `nav:next`                      | `next`
+
+| `nav:last`                      | `last`
+
+| `nav:records`                   | `records`
+
+| `nav:recordsFrom`               | `records-start`
+
+| `nav:recordsTo`                 | `records-end`
+
+| `nav:recordsCount`              | `records-count`
+|=========================
+
+Generally speaking, you can annotate the container element or the element that
+will have a given value directly with the class of the content it should
+contain, rather than needing an extra container with the class like the old
+`nav:*` elements. For example, where before you had:
+
+[.lift-26]
+.Lift 2.6 simple pagination example
+```html
+<lift:MyPaginatorSnippet.paginate>
+  <ul>
+    <li class="first"><nav:first /></li>
+    <li class="prev"><nav:prev /></li>
+    <li class="next"><nav:next /></li>
+    <li class="last"><nav:last /></li>
+  </ul>
+</lift:MyPaginatorSnippet.paginate>
+```
+
+In Lift 3.0, you can remove all the `nav:*` elements and instead use the classes
+to mark the appropriate elements:
+
+[.lift-30]
+.Lift 3.0 simple pagination example
+```html
+<ul data-lift="MyPaginatorSnippet.paginate">
+  <li class="first">First</li>
+  <li class="prev">Previous</li>
+  <li class="next">Next</li>
+  <li class="last">Last</li>
+</ul>
+```
+
+There are a couple of special cases, however, due to the way that the paginator
+snippet is structured.
+
+=== `all-pages` and `zoomed-pages`
+
+The `all-pages` element is meant to contain a link to each available page, with
+some delimiter between them. For example, you might want pages to look like this:
+
+.Simple pagination layout
+```
+  << <  1 | 2 | 3 | 4 | 5  > >>
+```
+
+Where `3` is the current page and each page number except for 3 is a link. In
+Lift 2.6, you might write this:
+
+[.lift-26]
+.Lift 2.6 pagination example with all pages
+```html
+<lift:MyPaginatorSnippet.paginate>
+  <ul>
+    <li class="first"><nav:first /></li>
+    <li class="prev"><nav:prev /></li>
+    <li class="all-pages">
+      <nav:allpages> | </nav:allpages>
+    </li>
+    <li class="next"><nav:next /></li>
+    <li class="last"><nav:last /></li>
+  </ul>
+</lift:MyPaginatorSnippet.paginate>
+```
+
+The content of the `nav:allpages` is then used as the delimiter.
+
+In Lift 3.0, the content of the element marked with class `all-pages` is
+similarly used as the delimiter, so you would write:
+
+[.lift-30]
+.Lift 3.0 pagination example with all pages
+```html
+<ul data-lift="MyPaginatorSnippet.paginate">
+  <li class="first">First</li>
+  <li class="prev">Previous</li>
+  <li class="all-pages"> | </li>
+  <li class="next">Next</li>
+  <li class="last">Last</li>
+</ul>
+```
+
+In your paginator snippet, you can override the way any individual page number
+link is created by overriding the `pageXml` method---this is the same in Lift
+3.0 as in 2.6.
+
+`zoomed-pages` works the same way, except zoomed pages doesn't show all pages,
+instead showing a subset that is scaled (e.g., it might show 1, 2, 3, 4, 5, 6,
+7, 8, 9, 10, 20 if 50 pages are available) to give access deeper in the page.
+The content of that element is also the delimiter, so in Lift 3.0 you might use
+it as such:
+
+[.lift-30]
+.Lift 3.0 pagination example with zoomed pages
+```html
+<ul data-lift="MyPaginatorSnippet.paginate">
+  <li class="first">First</li>
+  <li class="prev">Previous</li>
+  <li class="zoomed-pages"> | </li>
+  <li class="next">Next</li>
+  <li class="last">Last</li>
+</ul>
+```
+
+== Further Help
+
+That's it! All the other elements work as they did in 2.6, except you don't need
+weird XML elements in your containers; the CSS classes are enough. If you run
+into any issues porting your screen over to Lift 3.0's `Paginator`, please ask
+on the Lift mailing list and you should find willing helpers.