Implemented basic variants of list group as includable template

texperience · Jul 3, 2015 · 36b91a8 · 36b91a8
1 parent 76ba08d
commit 36b91a8
Show file tree

Hide file tree

Showing 9 changed files with 171 additions and 12 deletions.
diff --git a/README.rst b/README.rst
@@ -32,6 +32,7 @@ Features
 
 * Full-featured Bootstrap 3 template (3.3.5)
 * Latest Font Awesome integration (4.3.0)
+* Ready-to-use Bootstrap component templates
 * Intuitive template tag API for generating valid Bootstrap markup
 * Extensive and up-to-date documentation
 * Mainstream Python (2.7, 3.3, 3.4) and Django (1.7, 1.8) support
@@ -79,6 +80,19 @@ Prepare your page for Bootstrap and provide your content:
             <h1>Hello, I'm using django-bootstrap-ui!</h1>
         {% endblock %}
 
+Bootstrap component templates
+*****************************
+
+Render complete Bootstrap components by including our default implementations. Example:
+
+#. Provide a list of strings ``['alpha', 'beta', 'gamma']`` as template variable ``items``
+
+#. Include ``listgroup.html`` parameterized with ``type='list'`` and ``items=items``:
+
+    .. code:: Django
+
+        {% include 'bootstrap_ui/listgroup.html' with type='list' items=items only %}
+
 Template tag API
 ****************
 

diff --git a/bootstrap_ui/templates/bootstrap_ui/listgroup.html b/bootstrap_ui/templates/bootstrap_ui/listgroup.html
@@ -0,0 +1,21 @@
+{% load bootstrap_ui_tags %}
+
+{% if type == 'list' %}
+    {% listgroup %}
+        {% for text in items %}
+            {% listgroupitem %}
+                {{ text }}
+            {% endlistgroupitem %}
+        {% endfor %}
+    {% endlistgroup %}
+{% elif type == 'linklist' %}
+    {% listgroup use_tag='div' %}
+        {% for text, url in items %}
+            {% with link=url|default:'#' %}
+                {% listgroupitem use_tag='a' link=link %}
+                    {{ text }}
+                {% endlistgroupitem %}
+            {% endwith %}
+        {% endfor %}
+    {% endlistgroup %}
+{% endif %}
diff --git a/docs/getting_started/index.rst b/docs/getting_started/index.rst
@@ -42,6 +42,19 @@ Prepare your page for Bootstrap and provide your content:
             <h1>Hello, I'm using django-bootstrap-ui!</h1>
         {% endblock %}
 
+Bootstrap component templates
+*****************************
+
+Render complete Bootstrap components by including our default implementations. Example:
+
+#. Provide a list of strings ``['alpha', 'beta', 'gamma']`` as template variable ``items``
+
+#. Include ``listgroup.html`` parameterized with ``type='list'`` and ``items=items``:
+
+    .. code:: Django
+
+        {% include 'bootstrap_ui/listgroup.html' with type='list' items=items only %}
+
 Template tag API
 ****************
 

diff --git a/docs/index.rst b/docs/index.rst
@@ -32,6 +32,7 @@ Features
 
 * Full-featured Bootstrap 3 template (3.3.5)
 * Latest Font Awesome integration (4.3.0)
+* Ready-to-use Bootstrap component templates
 * Intuitive template tag API for generating valid Bootstrap markup
 * Extensive and up-to-date documentation
 * Mainstream Python (2.7, 3.3, 3.4) and Django (1.7, 1.8) support

diff --git a/docs/templates/components/index.rst b/docs/templates/components/index.rst
@@ -0,0 +1,62 @@
+Bootstrap component templates
+=============================
+
+Render complete Bootstrap components by including our default implementations.
+
+List group
+----------
+
+This template (``listgroup.html``) renders a list group. Two parameters are required:
+
+* type
+* items
+
+Basic example
+*************
+
+Given a list of strings ``['alpha', 'beta', 'gamma']`` as template variable ``items``:
+
+.. code:: Django
+
+    {% include 'bootstrap_ui/listgroup.html' with type='list' items=items only %}
+
+This renders the following html code:
+
+.. code:: HTML
+
+    <ul class="list-group">
+        <li class="list-group-item">
+            alpha
+        </li>
+        <li class="list-group-item">
+            beta
+        </li>
+        <li class="list-group-item">
+            gamma
+        </li>
+    </ul>
+
+Linked items
+************
+
+Given a list of 2-tuples containing ``[('alpha', 'http://example.org'), ('beta', 'local.html'), ('gamma', '#')]`` as template variable ``items``:
+
+.. code:: Django
+
+    {% include 'bootstrap_ui/listgroup.html' with type='linklist' items=items only %}
+
+This renders the following html code:
+
+.. code:: HTML
+
+    <div class="list-group">
+        <a class="list-group-item" href="http://example.org">
+            alpha
+        </a>
+        <a class="list-group-item" href="local.html">
+            beta
+        </a>
+        <a class="list-group-item" href="#">
+            gamma
+        </a>
+    </div>
diff --git a/docs/templates/index.rst b/docs/templates/index.rst
@@ -1,13 +1,18 @@
 Templates
 =========
 
-django-bootstrap-ui enables you to quickly get started through a set of predefined templates.
+django-bootstrap-ui enables you to quickly get started through a set of predefined templates. There are two sort of templates:
 
 #. :doc:`skeletons/index`
 
    These templates render entire html pages. They are meant to serve as base templates to be extended and provide HTML5 and Bootstrap skeletons.
 
+#. :doc:`components/index`
+
+   These templates encapsulate Bootstrap components. Included and parameterized as a one-liner within your page templates they will return completely rendered UI components.
+
 .. toctree::
    :maxdepth: 2
 
    skeletons/index
+   components/index
diff --git a/setup.py b/setup.py
@@ -9,7 +9,7 @@
 
 setup(
     name='django-bootstrap-ui',
-    version='0.1.0b2',
+    version='0.1.0rc1',
     packages=find_packages(exclude=['tests', 'docs']),
     include_package_data=True,
     license='ISC License (ISCL)',

diff --git a/tests/templates/listgrouptags.html b/tests/templates/listgrouptags.html
@@ -1,13 +1,17 @@
 {% load bootstrap_ui_tags %}
 
-{% listgroup %}
-    {% listgroupitem %}
-        {{ content }}
-    {% endlistgroupitem %}
-{% endlistgroup %}
+{% if not items %}
+    {% listgroup %}
+        {% listgroupitem %}
+            {{ content }}
+        {% endlistgroupitem %}
+    {% endlistgroup %}
 
-{% if use_tag == 'a' %}
-    {% listgroupitem use_tag=use_tag link=link %}
-        {{ label }}
-    {% endlistgroupitem %}
-{% endif %}
+    {% if use_tag == 'a' %}
+        {% listgroupitem use_tag=use_tag link=link %}
+            {{ label }}
+        {% endlistgroupitem %}
+    {% endif %}
+{% endif %}
+
+{% include 'bootstrap_ui/listgroup.html' with type=type items=items only %}
diff --git a/tests/tests.py b/tests/tests.py
@@ -123,13 +123,26 @@ def test_column_custom_grid_with_defaults_is_rendered(self):
 class ListGroupTagsTest(SimpleTestCase):
     SAMPLE_LINK = 'http://example.org'
     SAMPLE_LABEL = 'Linklabel'
+    SAMPLE_LIST = [
+        'alpha',
+        'beta',
+        'gamma',
+    ]
+    SAMPLE_LINKLIST = [
+        ('alpha', SAMPLE_LINK),
+        ('beta', SAMPLE_LINK),
+        ('gamma', SAMPLE_LINK),
+    ]
 
     LIST_GROUP_START = mark_safe('<ul class="list-group">')
     LIST_GROUP_END = mark_safe('</ul>')
 
     LIST_GROUP_ITEM_START = mark_safe('<li class="list-group-item">')
     LIST_GROUP_ITEM_END = mark_safe('</li>')
 
+    LIST_GROUP_LINK_START = mark_safe('<div class="list-group">')
+    LIST_GROUP_LINK_END = mark_safe('</div>')
+
     LIST_GROUP_ITEM_LINK_START = mark_safe('<a class="list-group-item" href="' + SAMPLE_LINK + '">')
     LIST_GROUP_ITEM_LINK_END = mark_safe('</a>')
 
@@ -162,6 +175,32 @@ def test_list_group_item_link_without_destination_raises_exception(self):
         with self.assertRaises(TemplateSyntaxError):
             self.template.render(Context({'use_tag': 'a'}))
 
+    def test_listgroup_list_is_rendered(self):
+        rendered = self.template.render(Context({'type': 'list', 'items': self.SAMPLE_LIST}))
+        self.assertInHTML(
+            self.LIST_GROUP_START
+            + ''.join(self.LIST_GROUP_ITEM_START + item + self.LIST_GROUP_ITEM_END for item in self.SAMPLE_LIST)
+            + self.LIST_GROUP_END,
+            rendered
+        )
+
+    def test_listgroup_without_type_is_empty(self):
+        rendered = self.template.render(Context({'items': self.SAMPLE_LIST}))
+        self.assertHTMLEqual('', rendered)
+
+    def test_listgroup_linklist_is_rendered(self):
+        rendered = self.template.render(Context({'type': 'linklist', 'items': self.SAMPLE_LINKLIST}))
+        self.assertInHTML(
+            self.LIST_GROUP_LINK_START
+            + ''.join(
+                self.LIST_GROUP_ITEM_LINK_START
+                + item[0]
+                + self.LIST_GROUP_ITEM_LINK_END for item in self.SAMPLE_LINKLIST
+            )
+            + self.LIST_GROUP_LINK_END,
+            rendered
+        )
+
 
 class PanelTagsTest(SimpleTestCase):
     SAMPLE_HEADING = 'Lorem ipsum heading'