From 5eb71dd1d461c2a583cc7b89a81ee02d2431ce56 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Grzegorz=20T=C4=99=C5=BCycki?= <grzegorz.tezycki@gmail.com>
Date: Sun, 26 Feb 2017 20:17:32 +0100
Subject: [PATCH] Documentation for pinned rows

---
 docs/pages/customizing.rst |  1 +
 docs/pages/pinned-rows.rst | 67 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 68 insertions(+)
 create mode 100644 docs/pages/pinned-rows.rst

diff --git a/docs/pages/customizing.rst b/docs/pages/customizing.rst
index fae75f6e..fb219953 100644
--- a/docs/pages/customizing.rst
+++ b/docs/pages/customizing.rst
@@ -13,3 +13,4 @@ Customizing the table
     query-string-fields
     localization-control
     generic-mixins
+    pinned-rows
diff --git a/docs/pages/pinned-rows.rst b/docs/pages/pinned-rows.rst
new file mode 100644
index 00000000..8d302c87
--- /dev/null
+++ b/docs/pages/pinned-rows.rst
@@ -0,0 +1,67 @@
+.. _pinned_rows:
+
+Pinned rows
+===========
+
+By using Pinned Rows, you can pin particular rows to the top or bottom of your table.
+To add pinned rows to your table, you must overridden `get_top_pinned_data` and/or `get_bottom_pinned_data`
+methods in your `.Table` class.
+
+* `get_top_pinned_data(self)` - Display the pinned rows on top.
+* `get_bottom_pinned_data(self)` - Display the pinned rows on bottom.
+
+By default both methods return `None` value and pinned rows aren't visible.
+Return data for pinned rows should be iterable type like: queryset, list of dicts, list of objects.
+
+
+Example::
+
+    class Table(tables.Table):
+
+        def get_top_pinned_data(self):
+            return [
+                # First top pinned row
+                {
+                    'column_a' : 'value for A column',
+                    'column_b' : 'value for B column'
+                },
+                # Second top pinned row
+                {
+                    'column_a' : 'extra value for A column'
+                    'column_b' : None
+                }
+            ]
+
+        def get_top_pinned_data(self):
+            return [{
+                'column_c' : 'value for C column',
+                'column_d' : 'value for D column'
+            }]
+
+
+.. note:: Sorting and pagination for pined rows not working.
+
+Value for cell in pinned row will be shown only when **key** in object has the same name as column.
+You can decide which columns for pinned rows will visible or not.
+If you want show value for only one column, use only one column name as key.
+Non existing keys won't be shown in pinned rows.
+
+
+.. warning:: Pinned rows not exist in ``table.rows``. If table has some pinned rows and
+   one normal row then length of ``table.rows`` is 1.
+
+
+.. _pinned_row_attributes:
+
+Pinned rows attributes
+========================
+If you wont override HTML attributes for pinned rows you can use: ``pinned_row_attrs``.
+Pined row attributes can be specified using a `dict` defining the HTML attributes for
+the ``<tr>`` element on each row. See more: :ref:`row-attributes`.
+
+.. note:: By default pinned rows have ``pinned-row`` css class.
+
+    .. sourcecode:: django
+
+        <tr class="odd pinned-row" ...> [...] </tr>
+        <tr class="even pinned-row" ...> [...] </tr>