diff --git a/docs/migration/2.6-to-3.0-paginator.adoc b/docs/migration/2.6-to-3.0-paginator.adoc new file mode 100644 index 0000000000..8ba796632e --- /dev/null +++ b/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 + + + +``` + +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 + +``` + +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 + + + +``` + +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 + +``` + +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 + +``` + +== 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.