Update example app (#89)

Closes #51

Author: kytta

CHANGES

@@ -9,6 +9,7 @@ upcoming: Version 2.0.0
               inside the "simple_menu" subfolder
 - Moved CI to GitHub Actions (#67, #72)
 - Project is now a part of Jazzband (#54)
+- Updated the example app
 
 Version 1.2.1 - Released May 1st, 2016
 - Fixing sdist packaging

example/.gitignore

@@ -0,0 +1,18 @@
+### Django ###
+db.sqlite3
+db.sqlite3-journal
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# PyCharm
+.idea/
+
+# Visual Studio Code
+.vscode/

example/README.rst

@@ -1,30 +1,61 @@
-Example Project for django-simple-menu
-======================================
+==============================
+django-simple-menu example app
+==============================
 
-This is a complete example project for django-simple-menu that can be quickly
-used to evaluate if django-simple-menu is right for you.
+Set up
+------
 
-Setting up
-----------
+1. Create a virtualenv, source it, and install dependencies::
+
+       python3 -m venv .venv
+       source .venv/bin/activate
+       pip install -r requirements.txt
+
+2. Initialize a database and create test users::
+
+       python3 manage.py makemigrations
+       python3 manage.py migrate
+       python3 manage.py createsuperuser --username admin
+       python3 manage.py createsuperuser --username user
+
+3. Run server::
+
+       python3 manage.py runserver
+
+4. Go to Django administration (probably under http://127.0.0.1:8000/admin/)
+   and remove superuser rights from the second user you've created.
+
+5. Look around the website, try logging in, have fun :)
 
-To setup the project you need to create a new virtualenv directory and install
-the dependencies listed in the requirements file::
+Screenshots
+-----------
+.. figure:: ./screenshots/main_page.png
 
-    virtualenv testenv
-    source testenv/bin/activate
-    pip install -r requirements.txt
+   Index page of the example app
 
-Next setup the Django instance::
+.. figure:: ./screenshots/subpage.png
+
+   Page featuring a submenu
+
+.. figure:: ./screenshots/user_page.png
+
+   Page only shown to the authenticated users
+
+.. figure:: ./screenshots/secret_page.png
+
+   Page only shown to the superusers
+
+Learn more
+----------
 
-    ./manage.py syncdb
+Full documentation, including installation and configuration instructions, is
+available at https://django-simple-menu.readthedocs.io/.
 
-And finally run the project::
+``django-simple-menu`` is released under the *BSD 2-Clause "Simplified" License*.
+If you like it, please consider contributing!
 
-    ./manage.py runserver
+``django-simple-menu`` was originally created by
+Evan Borgstom <[email protected]> and was further developed by many
+contributors_.
 
-Once you access the project at http://127.0.0.1:8000 you will see a menu that
-will change depending on if you're logged in, logged in as a staff member or
-logged in as a superuser. To fully see the menu system in action you will need
-to login to the Django admin and create two new users (one just a staff member
-and the other a regular user, you already have a superuser from the syncdb
-call) and then login with all three of them to compare the resulting menus.
+.. _contributors: https://github.com/jazzband/django-simple-menu/graphs/contributors

example/accounts/apps.py

@@ -0,0 +1,6 @@
+from django.apps import AppConfig
+
+
+class AccountsConfig(AppConfig):
+    default_auto_field = 'django.db.models.BigAutoField'
+    name = 'accounts'

example/accounts/menus.py

@@ -1,36 +1,49 @@
-from django.core.urlresolvers import reverse
+from django.urls import reverse
+
+from simple_menu import Menu, MenuItem
 
-from menu import Menu, MenuItem
 
 def profile_title(request):
-    """
-    Return a personalized title for our profile menu item
+    """Return a personalized title for our profile menu item
     """
     # we don't need to check if the user is authenticated because our menu
     # item will have a check that does that for us
     name = request.user.get_full_name() or request.user
 
-    return "%s's Profile" % name
+    return f"{name}'s Profile"
 
-Menu.add_item("main", MenuItem("Accounts Index",
-                               reverse("accounts.views.index")))
+
+submenu_items = [
+    MenuItem(f"Page {i}",
+             reverse('accounts:subpage', kwargs={'i': i}),
+             icon=f'{i}-circle')
+    for i in range(1, 4)
+]
+Menu.add_item("user", MenuItem("Subpages",
+                               reverse('accounts:subpage', kwargs={'i': 1}),
+                               icon="menu-app",
+                               children=submenu_items))
 
 # this item will be shown to users who are not logged in
-Menu.add_item("user", MenuItem("Login",
-                               reverse('django.contrib.auth.views.login'),
-                               check=lambda request: not request.user.is_authenticated()))
+Menu.add_item("user", MenuItem("Sign in",
+                               reverse('accounts:sign_in'),
+                               icon='box-arrow-in-right',
+                               check=lambda r: not r.user.is_authenticated))
 
 # this will only be shown to logged in users and also demonstrates how to use
 # a callable for the title to return a customized title for each request
 Menu.add_item("user", MenuItem(profile_title,
-                               reverse('accounts.views.profile'),
-                               check=lambda request: request.user.is_authenticated()))
-Menu.add_item("user", MenuItem("Logout",
-                               reverse('django.contrib.auth.views.logout'),
-                               check=lambda request: request.user.is_authenticated()))
+                               reverse('accounts:profile'),
+                               icon='person-circle',
+                               check=lambda r: r.user.is_authenticated))
 
 # this only shows to superusers
-Menu.add_item("user", MenuItem("Admin",
-                               reverse("admin:index"),
-                               separator=True,
-                               check=lambda request: request.user.is_superuser))
+Menu.add_item("user", MenuItem("Secret superuser page",
+                               reverse("accounts:super_only"),
+                               icon='incognito',
+                               check=lambda r: r.user.is_superuser))
+
+Menu.add_item("user", MenuItem("Sign out",
+                               reverse('accounts:sign_out'),
+                               icon='box-arrow-right',
+                               check=lambda r: r.user.is_authenticated))

example/reports/__init__.py renamed to example/accounts/migrations/__init__.py

@@ -0,0 +1,59 @@
+{% extends 'base.html' %}
+
+{% block title %}
+    Accounts | {{ block.super }}
+{% endblock %}
+
+{% block body %}
+    <main class="py-5">
+        <div class="container content">
+            <h1>Welcome!</h1>
+            <p class="lead">
+                This is an example website for
+                <a href="https://github.com/jazzband/django-simple-menu">django-simple-menu</a>.
+            </p>
+            <section>
+                <h2>How to use this example</h2>
+                <ol>
+                    <li>
+                        Create a superuser:
+                        <code class="user-select-all">python3 manage.py
+                            createsuperuser --username "admin"</code>
+                    </li>
+                    <li>
+                        Create another superuser:
+                        <code class="user-select-all">python3 manage.py
+                            createsuperuser --username "guest"</code>
+                    </li>
+                    <li>
+                        Log in as <code>admin</code> into
+                        <a href="/admin">Django administration</a>
+                        and remove admin and staff rights from
+                        <code>guest</code>.
+                    </li>
+                    <li>
+                        Try logging in and out on the website and visit
+                        the pages in the top menu.
+                    </li>
+                </ol>
+            </section>
+            <section>
+                <h2>More</h2>
+                <ul>
+                    <li>
+                        <i class="bi bi-journal-code"></i>
+                        <a href="https://django-simple-menu.readthedocs.io/">
+                            Documentation
+                        </a>
+                    </li>
+                    <li>
+                        <i class="bi bi-github"></i>
+                        <a href="https://github.com/jazzband/django-simple-menu">
+                            Source code
+                        </a>
+                    </li>
+                </ul>
+            </section>
+        </div>
+    </main>
+{% endblock %}

example/accounts/templates/accounts/index.html

@@ -0,0 +1,35 @@
+{% extends 'base.html' %}
+
+{% block title %}
+    Your profile | {{ block.super }}
+{% endblock %}
+
+{% block body %}
+    <main class="py-5">
+        <section class="container">
+            <h1>{{ request.user.get_full_name|default:"" }}
+                (@{{ request.user.username }})</h1>
+            <p>
+                <strong>E-Mail:</strong> {{ request.user.email }}
+            </p>
+        </section>
+        <section class="container content">
+            <p>
+                The menu item for this page is being shown to everyone,
+                who is authenticated:
+            </p>
+            <pre><code>Menu.add_item("user", MenuItem(profile_title,
+                               reverse('accounts:profile'),
+                               icon='person-circle',
+                               <mark>check=lambda r: r.user.is_authenticated</mark>))</code></pre>
+            <p>
+                Also take a look at the <code>profile_title</code>. It's not a string,
+                but a callable, which accepts the request object. In our case,
+                it renders the user's name on the button:
+            </p>
+            <pre><code>def profile_title(request):
+    name = request.user.get_full_name() or request.user
+    return f"{name}'s Profile"</code></pre>
+        </section>
+    </main>
+{% endblock %}

example/accounts/templates/accounts/profile.html

@@ -0,0 +1,39 @@
+{% extends 'base.html' %}
+
+{% block title %}
+    Sign in | {{ block.super }}
+{% endblock %}
+
+{% block body %}
+    <main class="p-4">
+        <section class="container w-25 mx-auto mb-5">
+            <form action="{% url 'accounts:sign_in' %}" method="post">
+                {% csrf_token %}
+                <h1>Sign in</h1>
+
+                <div class="mb-3">
+                    <label for="username">Username</label>
+                    <input type="text" class="form-control" id="username"
+                           name="username" autofocus>
+                </div>
+                <div class="mb-3">
+                    <label for="password">Password</label>
+                    <input type="password" class="form-control"
+                           id="password" name="password">
+                </div>
+
+                <button class="btn btn-lg btn-primary" type="submit">
+                    Sign in
+                </button>
+            </form>
+        </section>
+        <section class="container content">
+            The menu item for this page is being shown to everyone,
+            who is not authenticated:
+            <pre><code>Menu.add_item("user", MenuItem("Sign in",
+                               reverse('accounts:sign_in'),
+                               icon='box-arrow-in-right',
+                               <mark>check=lambda r: not r.user.is_authenticated</mark>))</code></pre>
+        </section>
+    </main>
+{% endblock %}

example/accounts/templates/accounts/sign_in.html

@@ -0,0 +1,37 @@
+{% extends 'base.html' %}
+
+{% block title %}
+    Subpage | {{ block.super }}
+{% endblock %}
+
+{% block body %}
+    <main class="py-5">
+        <section class="container">
+            <h1>This is a subpage</h1>
+        </section>
+        <section class="container content">
+            <p>
+                There are three identical pages that are nested inside their
+                parent menu item:
+            </p>
+            <pre><code>submenu_items = [...]
+Menu.add_item("user", MenuItem("Subpages",
+                               reverse('accounts:subpage', kwargs={'i': 1}),
+                               icon="menu-app",
+                               <mark>children=submenu_items</mark>))</code></pre>
+            <p>
+                Note that the second navigation bar is only shown for the pages
+                that have a submenu. You can check it in the template:
+            </p>
+            <pre><code>&lbrace;% <mark>if has_submenu</mark>
+    &lt;!-- display submenu --&gt;
+&lbrace;% endif %}</code></pre>
+
+            <p>
+                By default, the parent will not be marked active if their child
+                active. The example site changes this behavior using a setting:
+            </p>
+            <pre><code>MENU_SELECT_PARENTS = True</code></pre>
+        </section>
+    </main>
+{% endblock %}