Merge pull request #289 from MongoEngine/better-documentation

Better documentation around pagination

Author: lafrech

docs/conf.py

@@ -49,9 +49,9 @@
 #
 import flask_mongoengine
 # The short X.Y version.
-version = flask_mongoengine.get_version()
+version = flask_mongoengine.__version__
 # The full version, including alpha/beta/rc tags.
-release = flask_mongoengine.get_version()
+release = flask_mongoengine.__version__
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

docs/index.rst

@@ -107,9 +107,17 @@ has_prev, next_num, prev_num.
 
 In the template::
 
-    {% macro render_pagination(pagination, endpoint) %}
+    {# Display a page of todos #}
+    <ul>
+        {% for todo in paginated_todos.items %}
+            <li>{{ todo.title }}</li>
+        {% endfor %}
+    </ul>
+
+    {# Macro for creating navigation links #}
+    {% macro render_navigation(pagination, endpoint) %}
       <div class=pagination>
-      {%- for page in pagination.iter_pages() %}
+      {% for page in pagination.iter_pages() %}
         {% if page %}
           {% if page != pagination.page %}
             <a href="{{ url_for(endpoint, page=page) }}">{{ page }}</a>
@@ -119,10 +127,12 @@ In the template::
         {% else %}
           <span class=ellipsis>…</span>
         {% endif %}
-      {%- endfor %}
+      {% endfor %}
       </div>
     {% endmacro %}
 
+    {{ render_navigation(paginated_todos, 'view_todos') }}
+
 
 MongoEngine and WTForms
 =======================

examples/biggerapp/app.py

@@ -28,8 +28,9 @@
 
 DebugToolbarExtension(app)
 
-from views import index
+from views import index, pagination
 app.add_url_rule('/', view_func=index)
+app.add_url_rule('/pagination', view_func=pagination)
 
 if __name__ == "__main__":
     app.run(host="0.0.0.0", port=4000)

examples/biggerapp/templates/index.html

@@ -8,4 +8,6 @@ <h2>{{ todo.title }}</h2>
   {% else %}
     <em>Unbelievable.  No todos here so far <a href="/add">Add one</a></em>
   {% endfor %}
+  <br/>
+  <a href="{{ url_for('pagination') }}">See pagination</a>
 {% endblock %}

examples/biggerapp/templates/pagination.html

@@ -0,0 +1,35 @@
+{% extends "layout.html" %}
+
+{# Macro for creating navigation links #}
+{% macro render_navigation(pagination, endpoint) %}
+    <div class=pagination>
+        {% for page in pagination.iter_pages() %}
+            {% if page %}
+                {% if page != pagination.page %}
+                    <a href="{{ url_for(endpoint, page=page) }}">{{ page }}</a>
+                {% else %}
+                    <strong>{{ page }}</strong>
+                {% endif %}
+            {% else %}
+                <span class=ellipsis>…</span>
+            {% endif %}
+        {% endfor %}
+    </div>
+{% endmacro %}
+
+{% block body %}
+
+<div class="todos">
+    <ul>
+        {% for todo in todos_page.items %}
+            <li>{{ todo.title }}</li>
+        {% endfor %}
+    </ul>
+</div>
+
+<div class="navigation">
+    {{ render_navigation(todos_page, 'pagination') }}
+</div>
+
+
+{% endblock %}

examples/biggerapp/views.py

@@ -10,3 +10,13 @@ def index():
     todos = list(Todo.objects[:10])
     todos = Todo.objects.all()
     return flask.render_template('index.html', todos=todos)
+
+def pagination():
+    Todo.objects().delete()
+    for i in range(10):
+        Todo(title='Simple todo {}'.format(i), text="12345678910").save()  # Insert
+
+    page_num = int(flask.request.args.get('page') or 1)
+    todos_page = Todo.objects.paginate(page=page_num, per_page=3)
+
+    return flask.render_template('pagination.html', todos_page=todos_page)

flask_mongoengine/__init__.py

@@ -16,6 +16,19 @@
 from .wtf import WtfBaseField
 
 
+VERSION = (0, 9, 0)
+
+
+def get_version():
+    """Return the VERSION as a string, e.g. for VERSION == (0, 9, 0),
+    return '0.9.0'.
+    """
+    return '.'.join(map(str, VERSION))
+
+
+__version__ = get_version()
+
+
 def _patch_base_field(obj, name):
     """
     If the object submitted has a class whose base class is

setup.py

@@ -15,11 +15,26 @@
 except:
     pass
 
+
+def get_version(version_tuple):
+    """Return the version tuple as a string, e.g. for (0, 10, 7),
+    return '0.10.7'.
+    """
+    return '.'.join(map(str, version_tuple))
+
+
+# Dirty hack to get version number from flask_monogengine/__init__.py - we
+# can't import it as it depends on PyMongo and PyMongo isn't installed until
+# this file is read
+init = os.path.join(os.path.dirname(__file__), 'flask_mongoengine', '__init__.py')
+version_line = list(filter(lambda l: l.startswith('VERSION'), open(init)))[0]
+version = get_version(eval(version_line.split('=')[-1]))
+
 test_requirements = ['coverage', 'nose', 'rednose']
 
 setup(
     name='flask-mongoengine',
-    version='0.9.0',
+    version=version,
     url='https://github.com/mongoengine/flask-mongoengine',
     license='BSD',
     author='Ross Lawley',