feat(nav/pagination): nav, items, previous & next (and variations) ma…

…cros + demos + docs

README.md

@@ -29,6 +29,7 @@ You can [view the demos of all available modules](https://jbmoelker.github.io/nu
   * [nav](https://jbmoelker.github.io/nunjucks-bootstrap/#nav/nav/nav.demo.html)
   * [navbar](https://jbmoelker.github.io/nunjucks-bootstrap/#nav/navbar/navbar.demo.html)
   * [pager](https://jbmoelker.github.io/nunjucks-bootstrap/#nav/pager/pager.demo.html)
+  * [pagination](https://jbmoelker.github.io/nunjucks-bootstrap/#nav/pagination/pagination.demo.html)
   * [tabs](https://jbmoelker.github.io/nunjucks-bootstrap/#nav/tabs/tabs.demo.html)
 
 The source files of all modules can be found in `src/`. Each module has its own readme with instructions on how to use its macros.

src/nav/pagination/README.md

@@ -0,0 +1,64 @@
+# Pagination
+
+## Functionality
+
+> Provide pagination links for your site or app with the multi-page pagination component,
+> or the simpler [pager alternative](../pager/README.md).
+>
+> -- [Bootstrap > Pagination](http://v4-alpha.getbootstrap.com/components/pagination/)
+
+## Usage
+
+Import the macros:
+
+```html
+{% import "nav/pagination/pagination.html" as pagination %}
+```
+
+Create pagination. E.g. for pages 1 to 10 with active and disabled link:
+
+```
+{% call pagination.nav() %}
+    {{ pagination.disabledPrevious() }}
+    {{ pagination.activeItem(1) }}
+    {% for page in range(2, 11) -%}
+    {{ pagination.item(page, '#/path/to/?page=' + page) }}
+    {%- endfor %}
+    {{ pagination.next(url = '#/path/to/next-page') }}
+{% endcall %}
+```
+
+### `.nav()`, `.largeNav()`, `smallNav()`.
+
+Creates a (normal, large, small) pagination element.
+
+Use as [`call` block](http://mozilla.github.io/nunjucks/templating.html#call).
+Content inside block is displayed inside the pagination element.
+
+index | parameter | type | description
+--- | --- | --- | ---
+0 | classes | string[] *optional* | List of classes to apply to the pagination element.
+
+### `.item()`, `.activeItem()`, `.disabledItem()`
+
+Creates a (normal, active, disabled) pagination item.
+
+index | parameter | type | description
+--- | --- | --- | ---
+0 | text | string *optional* | Text displayed inside item. Defaults to `Previous` / `Next`.
+1 | url | string *optional* | Url item links to. Not needed for `activeItem()`, `disabledItem()`.
+
+### `.previous()`, `.next()`, `disabledPrevious()`, `disabledNext()`
+
+Creates a (previous, next) pagination link.
+
+index | parameter | type | description
+--- | --- | --- | ---
+0 | text | string *optional* | Text displayed inside item. Defaults to `Previous` / `Next`.
+1 | url | string *optional* | Url item links to. Not needed for `disabledItem()`.
+
+
+## Notes
+
+* Previous and next links are decorated with `rel="prev"` / `rel="next"` to [indicate paginated content](https://support.google.com/webmasters/answer/1663744).
+* Disabled links are formatted as `<span>` instead of `<a>` as there is no such thing as a "disabled link" in HTML.

src/nav/pagination/pagination.demo.html

@@ -0,0 +1,46 @@
+{% extends "demo/module/module.html" %}
+{% import "./pagination.html" as pagination %}
+
+{% block content %}
+    <demo aria-label="Default pagination">
+        {% call pagination.nav() %}
+            {{ pagination.previous(url = '#/path/to/previous-page') }}
+            {% for page in range(1, 11) -%}
+            {{ pagination.item(page, '#/path/to/?page=' + page) }}
+            {%- endfor %}
+            {{ pagination.next(url = '#/path/to/next-page') }}
+        {% endcall %}
+    </demo>
+
+    <demo aria-label="Pagination with active and disabled links">
+        {% call pagination.nav() %}
+            {{ pagination.disabledPrevious() }}
+            {{ pagination.activeItem(1) }}
+            {% for page in range(2, 11) -%}
+            {{ pagination.item(page, '#/path/to/?page=' + page) }}
+            {%- endfor %}
+            {{ pagination.next(url = '#/path/to/next-page') }}
+        {% endcall %}
+    </demo>
+
+    <demo aria-label="Large pagination">
+        {% call pagination.largeNav() %}
+        {{ demoPaginationItems() }}
+        {% endcall %}
+    </demo>
+
+    <demo aria-label="Small pagination">
+        {% call pagination.smallNav() %}
+        {{ demoPaginationItems() }}
+        {% endcall %}
+    </demo>
+{% endblock %}
+
+{% macro demoPaginationItems() %}
+    {{ pagination.previous(url = '#/path/to/previous-page') }}
+    {% for page in range(1, 5) -%}
+    {{ pagination.item(page, '#/path/to/?page=' + page) }}
+    {%- endfor %}
+    {{ pagination.activeItem(5) }}
+    {{ pagination.disabledNext() }}
+{% endmacro %}

src/nav/pagination/pagination.html

@@ -0,0 +1,59 @@
+{%- macro nav(classes = []) -%}
+    <nav><ul class="pagination {{ classes | join(' ') }}">{{ caller() }}</ul></nav>
+{%- endmacro -%}
+
+{%- macro largeNav(classes = []) -%}
+    <nav><ul class="pagination pagination-lg {{ classes | join(' ') }}">{{ caller() }}</ul></nav>
+{%- endmacro -%}
+
+{%- macro smallNav(classes = []) -%}
+    <nav><ul class="pagination pagination-sm {{ classes | join(' ') }}">{{ caller() }}</ul></nav>
+{%- endmacro -%}
+
+{%- macro item(text, url) -%}
+    <li class="page-item"><a class="page-link" href="{{ url }}">{{ text }}</a></li>
+{%- endmacro -%}
+
+{%- macro activeItem(text) -%}
+    <li class="page-item active"><span class="page-link">{{ text }}</span></li>
+{%- endmacro -%}
+
+{%- macro disabledItem(text, url) -%}
+    <li class="page-item disabled"><span class="page-link">{{ text }}</span></li>
+{%- endmacro -%}
+
+{%- macro previous(text = 'Previous', url) -%}
+    <li class="page-item">
+        <a class="page-link" rel="prev" href="{{ url }}" aria-label="{{ text }}">
+            <span aria-hidden="true">&laquo;</span>
+            <span class="sr-only">{{ text }}</span>
+        </a>
+    </li>
+{%- endmacro -%}
+
+{%- macro next(text = 'Next', url) -%}
+    <li class="page-item">
+        <a class="page-link" rel="next" href="{{ url }}" aria-label="{{ text }}">
+            <span aria-hidden="true">&raquo;</span>
+            <span class="sr-only">{{ text }}</span>
+        </a>
+    </li>
+{%- endmacro -%}
+
+{%- macro disabledPrevious(text = 'Previous') -%}
+    <li class="page-item disabled">
+        <span class="page-link">
+            <span aria-hidden="true">&laquo;</span>
+            <span class="sr-only">{{ text }}</span>
+        </span>
+    </li>
+{%- endmacro -%}
+
+{%- macro disabledNext(text = 'Next') -%}
+    <li class="page-item disabled">
+        <span class="page-link">
+            <span aria-hidden="true">&raquo;</span>
+            <span class="sr-only">{{ text }}</span>
+        </span>
+    </li>
+{%- endmacro -%}