Merge pull request #883 from flask-admin/examples

Examples

examples/auth-flask-login/README.rst

+This example shows how to integrate Flask-Login authentication with Flask-Admin using the SQLAlchemy backend.
+
+To run this example:
+
+1. Clone the repository::
+
+     git clone https://github.com/flask-admin/flask-admin.git
+     cd flask-admin
+
+2. Create and activate a virtual environment::
+
+     virtualenv env
+     source env/bin/activate
+
+3. Install requirements::
+
+     pip install -r 'examples/auth-flask-login/requirements.txt'
+
+4. Run the application::
+
+     python examples/auth-flask-login/app.py
+
+The first time you run this example, a sample sqlite database gets populated automatically. To suppress this behaviour,
+comment the following lines in app.py:::
+
+     if not os.path.exists(database_path):
+         build_sample_db()

examples/auth-flask-login/app.py

+import os
+from flask import Flask, url_for, redirect, render_template, request
+from flask_sqlalchemy import SQLAlchemy
+from wtforms import form, fields, validators
+import flask_admin as admin
+import flask_login as login
+from flask_admin.contrib import sqla
+from flask_admin import helpers, expose
+from werkzeug.security import generate_password_hash, check_password_hash
+
+
+# Create Flask application
+app = Flask(__name__)
+
+# Create dummy secrey key so we can use sessions
+app.config['SECRET_KEY'] = '123456790'
+
+# Create in-memory database
+app.config['DATABASE_FILE'] = 'sample_db.sqlite'
+app.config['SQLALCHEMY_DATABASE_URI'] = 'sqlite:///' + app.config['DATABASE_FILE']
+app.config['SQLALCHEMY_ECHO'] = True
+db = SQLAlchemy(app)
+
+
+# Create user model.
+class User(db.Model):
+    id = db.Column(db.Integer, primary_key=True)
+    first_name = db.Column(db.String(100))
+    last_name = db.Column(db.String(100))
+    login = db.Column(db.String(80), unique=True)
+    email = db.Column(db.String(120))
+    password = db.Column(db.String(64))
+
+    # Flask-Login integration
+    def is_authenticated(self):
+        return True
+
+    def is_active(self):
+        return True
+
+    def is_anonymous(self):
+        return False
+
+    def get_id(self):
+        return self.id
+
+    # Required for administrative interface
+    def __unicode__(self):
+        return self.username
+
+
+# Define login and registration forms (for flask-login)
+class LoginForm(form.Form):
+    login = fields.TextField(validators=[validators.required()])
+    password = fields.PasswordField(validators=[validators.required()])
+
+    def validate_login(self, field):
+        user = self.get_user()
+
+        if user is None:
+            raise validators.ValidationError('Invalid user')
+
+        # we're comparing the plaintext pw with the the hash from the db
+        if not check_password_hash(user.password, self.password.data):
+        # to compare plain text passwords use
+        # if user.password != self.password.data:
+            raise validators.ValidationError('Invalid password')
+
+    def get_user(self):
+        return db.session.query(User).filter_by(login=self.login.data).first()
+
+
+class RegistrationForm(form.Form):
+    login = fields.TextField(validators=[validators.required()])
+    email = fields.TextField()
+    password = fields.PasswordField(validators=[validators.required()])
+
+    def validate_login(self, field):
+        if db.session.query(User).filter_by(login=self.login.data).count() > 0:
+            raise validators.ValidationError('Duplicate username')
+
+
+# Initialize flask-login
+def init_login():
+    login_manager = login.LoginManager()
+    login_manager.init_app(app)
+
+    # Create user loader function
+    @login_manager.user_loader
+    def load_user(user_id):
+        return db.session.query(User).get(user_id)
+
+
+# Create customized model view class
+class MyModelView(sqla.ModelView):
+
+    def is_accessible(self):
+        return login.current_user.is_authenticated()
+
+
+# Create customized index view class that handles login & registration
+class MyAdminIndexView(admin.AdminIndexView):
+
+    @expose('/')
+    def index(self):
+        if not login.current_user.is_authenticated():
+            return redirect(url_for('.login_view'))
+        return super(MyAdminIndexView, self).index()
+
+    @expose('/login/', methods=('GET', 'POST'))
+    def login_view(self):
+        # handle user login
+        form = LoginForm(request.form)
+        if helpers.validate_form_on_submit(form):
+            user = form.get_user()
+            login.login_user(user)
+
+        if login.current_user.is_authenticated():
+            return redirect(url_for('.index'))
+        link = '<p>Don\'t have an account? <a href="' + url_for('.register_view') + '">Click here to register.</a></p>'
+        self._template_args['form'] = form
+        self._template_args['link'] = link
+        return super(MyAdminIndexView, self).index()
+
+    @expose('/register/', methods=('GET', 'POST'))
+    def register_view(self):
+        form = RegistrationForm(request.form)
+        if helpers.validate_form_on_submit(form):
+            user = User()
+
+            form.populate_obj(user)
+            # we hash the users password to avoid saving it as plaintext in the db,
+            # remove to use plain text:
+            user.password = generate_password_hash(form.password.data)
+
+            db.session.add(user)
+            db.session.commit()
+
+            login.login_user(user)
+            return redirect(url_for('.index'))
+        link = '<p>Already have an account? <a href="' + url_for('.login_view') + '">Click here to log in.</a></p>'
+        self._template_args['form'] = form
+        self._template_args['link'] = link
+        return super(MyAdminIndexView, self).index()
+
+    @expose('/logout/')
+    def logout_view(self):
+        login.logout_user()
+        return redirect(url_for('.index'))
+
+
+# Flask views
+@app.route('/')
+def index():
+    return render_template('index.html')
+
+
+# Initialize flask-login
+init_login()
+
+# Create admin
+admin = admin.Admin(app, 'Example: Auth', index_view=MyAdminIndexView(), base_template='my_master.html')
+
+# Add view
+admin.add_view(MyModelView(User, db.session))
+
+
+def build_sample_db():
+    """
+    Populate a small db with some example entries.
+    """
+
+    import string
+    import random
+
+    db.drop_all()
+    db.create_all()
+    # passwords are hashed, to use plaintext passwords instead:
+    # test_user = User(login="test", password="test")
+    test_user = User(login="test", password=generate_password_hash("test"))
+    db.session.add(test_user)
+
+    first_names = [
+        'Harry', 'Amelia', 'Oliver', 'Jack', 'Isabella', 'Charlie','Sophie', 'Mia',
+        'Jacob', 'Thomas', 'Emily', 'Lily', 'Ava', 'Isla', 'Alfie', 'Olivia', 'Jessica',
+        'Riley', 'William', 'James', 'Geoffrey', 'Lisa', 'Benjamin', 'Stacey', 'Lucy'
+    ]
+    last_names = [
+        'Brown', 'Smith', 'Patel', 'Jones', 'Williams', 'Johnson', 'Taylor', 'Thomas',
+        'Roberts', 'Khan', 'Lewis', 'Jackson', 'Clarke', 'James', 'Phillips', 'Wilson',
+        'Ali', 'Mason', 'Mitchell', 'Rose', 'Davis', 'Davies', 'Rodriguez', 'Cox', 'Alexander'
+    ]
+
+    for i in range(len(first_names)):
+        user = User()
+        user.first_name = first_names[i]
+        user.last_name = last_names[i]
+        user.login = user.first_name.lower()
+        user.email = user.login + "@example.com"
+        user.password = generate_password_hash(''.join(random.choice(string.ascii_lowercase + string.digits) for i in range(10)))
+        db.session.add(user)
+
+    db.session.commit()
+    return
+
+if __name__ == '__main__':
+
+    # Build a sample db on the fly, if one does not exist yet.
+    app_dir = os.path.realpath(os.path.dirname(__file__))
+    database_path = os.path.join(app_dir, app.config['DATABASE_FILE'])
+    if not os.path.exists(database_path):
+        build_sample_db()
+
+    # Start app
+    app.run(debug=True)

examples/auth-flask-login/requirements.txt

+Flask
+Flask-Admin
+Flask-SQLAlchemy
+Flask-Login

examples/auth-flask-login/templates/admin/index.html

+{% extends 'admin/master.html' %}
+{% block body %}
+{{ super() }}
+<div class="row-fluid">
+
+    <div>
+        {% if current_user.is_authenticated() %}
+        <h1>Flask-Admin example</h1>
+        <p class="lead">
+            Authentication
+        </p>
+        <p>
+            This example shows how you can use Flask-Login for authentication. It is only intended as a basic demonstration.
+        </p>
+        {% else %}
+        <form method="POST" action="">
+            {{ form.hidden_tag() if form.hidden_tag }}
+            {% for f in form if f.type != 'CSRFTokenField' %}
+            <div>
+            {{ f.label }}
+            {{ f }}
+            {% if f.errors %}
+            <ul>
+                {% for e in f.errors %}
+                <li>{{ e }}</li>
+                {% endfor %}
+            </ul>
+            {% endif %}
+            </div>
+            {% endfor %}
+            <button class="btn" type="submit">Submit</button>
+        </form>
+        {{ link | safe }}
+        {% endif %}
+    </div>
+
+    <a class="btn btn-primary" href="/"><i class="icon-arrow-left icon-white"></i> Back</a>
+</div>
+{% endblock body %}
\ No newline at end of file

examples/auth-flask-login/templates/index.html

+<html>
+    <body>
+        <div>
+            <a href="{{ url_for('admin.index') }}">Go to admin!</a>
+        </div>
+    </body>
+</html>

examples/auth-flask-login/templates/my_master.html

+{% extends 'admin/base.html' %}
+
+{% block access_control %}
+{% if current_user.is_authenticated() %}
+<div class="btn-group pull-right">
+    <a class="btn dropdown-toggle" data-toggle="dropdown" href="#">
+        <i class="icon-user"></i> {{ current_user.login }} <span class="caret"></span>
+    </a>
+    <ul class="dropdown-menu">
+        <li><a href="{{ url_for('admin.logout_view') }}">Log out</a></li>
+    </ul>
+</div>
+{% endif %}
+{% endblock %}
\ No newline at end of file

examples/auth/config.py

+# Create dummy secrey key so we can use sessions
+SECRET_KEY = '123456790'
+
+# Create in-memory database
+DATABASE_FILE = 'sample_db.sqlite'
+SQLALCHEMY_DATABASE_URI = 'sqlite:///' + DATABASE_FILE
+SQLALCHEMY_ECHO = True
+
+# Flask-Security config
+SECURITY_URL_PREFIX = "/admin"
+SECURITY_PASSWORD_HASH = "pbkdf2_sha512"
+SECURITY_PASSWORD_SALT = "ATGUOHAELKiubahiughaerGOJAEGj"
+
+# Flask-Security URLs, overridden because they don't put a / at the end
+SECURITY_LOGIN_URL = "/login/"
+SECURITY_LOGOUT_URL = "/logout/"
+SECURITY_REGISTER_URL = "/register/"
+
+SECURITY_POST_LOGIN_VIEW = "/admin/"
+SECURITY_POST_LOGOUT_VIEW = "/admin/"
+SECURITY_POST_REGISTER_VIEW = "/admin/"
+
+# Flask-Security features
+SECURITY_REGISTERABLE = True
+SECURITY_SEND_REGISTER_EMAIL = False
\ No newline at end of file

examples/auth/requirements.txt

 Flask
 Flask-Admin
 Flask-SQLAlchemy
-Flask-Login
+Flask-Security==1.7.4
\ No newline at end of file

examples/auth/templates/admin/index.html

@@ -3,37 +3,27 @@
 {{ super() }}
 <div class="row-fluid">
 
-    <div>
-        {% if current_user.is_authenticated() %}
-        <h1>Flask-Admin example</h1>
-        <p class="lead">
-            Authentication
-        </p>
-        <p>
-            This example shows how you can use Flask-Login for authentication. It is only intended as a basic demonstration.
-        </p>
-        {% else %}
-        <form method="POST" action="">
-            {{ form.hidden_tag() if form.hidden_tag }}
-            {% for f in form if f.type != 'CSRFTokenField' %}
-            <div>
-            {{ f.label }}
-            {{ f }}
-            {% if f.errors %}
-            <ul>
-                {% for e in f.errors %}
-                <li>{{ e }}</li>
-                {% endfor %}
-            </ul>
-            {% endif %}
-            </div>
-            {% endfor %}
-            <button class="btn" type="submit">Submit</button>
-        </form>
-        {{ link | safe }}
-        {% endif %}
-    </div>
+  <div>
+    <h1>Flask-Admin example</h1>
+    <p class="lead">
+      Authentication
+    </p>
+    <p>
+      This example shows how you can use Flask-Security for authentication.
+    </p>
+    {% if not current_user.is_authenticated() %}
+    <p>You can register as a regular user, or log in as a superuser with the following credentials:
+    <ul>
+      <li>email: <b>admin</b></li>
+      <li>password: <b>admin</b></li>
+    </ul>
+    </p>
+    <p>
+      <a class="btn btn-default" href="{{ url_for('security.login') }}">login</a> <a class="btn btn-default" href="{{ url_for('security.register') }}">register</a>
+    </p>
+    {% endif %}
+  </div>
 
-    <a class="btn btn-primary" href="/"><i class="icon-arrow-left icon-white"></i> Back</a>
+  <a class="btn btn-primary" href="/"><i class="icon-arrow-left icon-white"></i> Back</a>
 </div>
 {% endblock body %}
\ No newline at end of file

examples/auth/templates/my_master.html

@@ -4,10 +4,15 @@
 {% if current_user.is_authenticated() %}
 <div class="btn-group pull-right">
     <a class="btn dropdown-toggle" data-toggle="dropdown" href="#">
-        <i class="icon-user"></i> {{ current_user.login }} <span class="caret"></span>
+        <i class="icon-user"></i>
+      {% if current_user.first_name -%}
+      {{ current_user.first_name }}
+      {% else -%}
+      {{ current_user.email }}
+      {%- endif %} <span class="caret"></span>
     </a>
     <ul class="dropdown-menu">
-        <li><a href="{{ url_for('admin.logout_view') }}">Log out</a></li>
+        <li><a href="{{ url_for('security.logout') }}">Log out</a></li>
     </ul>
 </div>
 {% endif %}

examples/auth/templates/security/_macros.html

+{% macro render_field_with_errors(field) %}
+<p>
+  {{ field.label }} {{ field(**kwargs)|safe }}
+  {% if field.errors %}
+<ul>
+  {% for error in field.errors %}
+  <li>{{ error }}</li>
+  {% endfor %}
+</ul>
+{% endif %}
+</p>
+{% endmacro %}
+
+{% macro render_field(field) %}
+<p>{{ field(**kwargs)|safe }}</p>
+{% endmacro %}
\ No newline at end of file

examples/auth/templates/security/_menu.html

+{% if security.registerable or security.recoverable or security.confirmable %}
+<h2>Menu</h2>
+<ul>
+  <li><a href="{{ url_for_security('login') }}{% if 'next' in request.args %}?next={{ request.args.next|urlencode }}{% endif %}">Login</a></li>
+  {% if security.registerable %}
+  <li><a href="{{ url_for_security('register') }}{% if 'next' in request.args %}?next={{ request.args.next|urlencode }}{% endif %}">Register</a><br/></li>
+  {% endif %}
+  {% if security.recoverable %}
+  <li><a href="{{ url_for_security('forgot_password') }}">Forgot password</a><br/></li>
+  {% endif %}
+  {% if security.confirmable %}
+  <li><a href="{{ url_for_security('send_confirmation') }}">Confirm account</a></li>
+  {% endif %}
+</ul>
+{% endif %}

examples/auth/templates/security/_messages.html

+{%- with messages = get_flashed_messages(with_categories=true) -%}
+{% if messages %}
+<ul class="flashes">
+  {% for category, message in messages %}
+  <li class="{{ category }}">{{ message }}</li>
+  {% endfor %}
+</ul>
+{% endif %}
+{%- endwith %}
\ No newline at end of file

examples/auth/templates/security/login_user.html

+{% extends 'admin/master.html' %}
+{% from "security/_macros.html" import render_field_with_errors, render_field %}
+{% include "security/_messages.html" %}
+{% block body %}
+{{ super() }}
+<div class="row-fluid">
+  <h1>Login</h1>
+  <form action="{{ url_for_security('login') }}" method="POST" name="login_user_form">
+    {{ login_user_form.hidden_tag() }}
+    {{ render_field_with_errors(login_user_form.email) }}
+    {{ render_field_with_errors(login_user_form.password) }}
+    {{ render_field_with_errors(login_user_form.remember) }}
+    {{ render_field(login_user_form.next) }}
+    {{ render_field(login_user_form.submit, class="btn btn-primary") }}
+  </form>
+  {% include "security/_menu.html" %}
+</div>
+{% endblock body %}
\ No newline at end of file

examples/auth/templates/security/register_user.html

+{% extends 'admin/master.html' %}
+{% from "security/_macros.html" import render_field_with_errors, render_field %}
+{% include "security/_messages.html" %}
+{% block body %}
+{{ super() }}
+<div class="row-fluid">
+  <h1>Register</h1>
+  <form action="{{ url_for_security('register') }}" method="POST" name="register_user_form">
+    {{ register_user_form.hidden_tag() }}
+    {{ render_field_with_errors(register_user_form.email) }}
+    {{ render_field_with_errors(register_user_form.password) }}
+    {% if register_user_form.password_confirm %}
+    {{ render_field_with_errors(register_user_form.password_confirm) }}
+    {% endif %}
+    {{ render_field(register_user_form.submit, class="btn btn-primary") }}
+  </form>
+  {% include "security/_menu.html" %}
+</div>
+{% endblock body %}
\ No newline at end of file

examples/geo-alchemy/README.rst

+SQLAlchemy model backend integration examples.
+
+To run this example:
+
+1. Clone the repository::
+
+    git clone https://github.com/flask-admin/flask-admin.git
+    cd flask-admin
+
+2. Create and activate a virtual environment::
+
+    virtualenv env
+    source env/bin/activate
+
+3. Install requirements::
+
+    pip install -r 'examples/geo-alchemy/requirements.txt'
+
+4. Setup the database::
+
+    psql postgres
+
+    CREATE DATABASE flask_admin_geo;
+    CREATE ROLE flask_admin_geo LOGIN PASSWORD 'flask_admin_geo';
+    GRANT ALL PRIVILEGES ON DATABASE flask_admin_geo TO flask_admin_geo;
+    \q
+
+    psql flask_admin_geo
+
+    CREATE EXTENSION postgis;
+    \q
+
+5. Run the application::
+
+    python examples/sqla/app.py
+
+6. You will notice that the maps are not rendered. To see them, you will have
+to register for a free account at `Mapbox <https://www.mapbox.com/>`_ and set
+the *MAPBOX_MAP_ID* and *MAPBOX_ACCESS_TOKEN* config variables accordingly.
\ No newline at end of file

examples/geo-alchemy/app.py

+from flask import Flask
+from flask_sqlalchemy import SQLAlchemy
+
+import flask_admin as admin
+from geoalchemy2.types import Geometry
+from flask_admin.contrib.geoa import ModelView
+
+
+# Create application
+app = Flask(__name__)
+
+# Create dummy secrey key so we can use sessions
+app.config['SECRET_KEY'] = '123456790'
+
+app.config['SQLALCHEMY_DATABASE_URI'] = 'postgresql+psycopg2://flask_admin_geo:flask_admin_geo@localhost/flask_admin_geo'
+app.config['SQLALCHEMY_ECHO'] = True
+db = SQLAlchemy(app)
+
+app.config['MAPBOX_MAP_ID'] = "..."
+app.config['MAPBOX_ACCESS_TOKEN'] = "..."
+
+
+class Location(db.Model):
+    id = db.Column(db.Integer, primary_key=True)
+    name = db.Column(db.String(64), unique=True)
+    point = db.Column(Geometry("POINT"))
+
+
+# Flask views
+@app.route('/')
+def index():
+    return '<a href="/admin/">Click me to get to Admin!</a>'
+
+# Create admin
+admin = admin.Admin(app, name='Example: GeoAlchemy')
+
+# Add views
+admin.add_view(ModelView(Location, db.session))
+
+if __name__ == '__main__':
+
+    db.create_all()
+
+    # Start app
+    app.run(debug=True)

examples/geo-alchemy/requirements.txt

+Flask
+Flask-Admin
+Flask-SQLAlchemy
+shapely
+geoalchemy2
+psycopg2
\ No newline at end of file

examples/geo-alchemy/templates/admin/index.html

+{% extends 'admin/master.html' %}
+{% block body %}
+{{ super() }}
+<div class="row">
+  <div class="span10 offset1">
+    <h1>Flask-Admin example</h1>
+    <p class="lead">
+      GeoAlchemy model view.
+    </p>
+    <p>
+      This example shows how to manage spatial information in a GIS database.
+    </p>
+    <a class="btn btn-primary" href="/"><i class="icon-arrow-left icon-white"></i> Back</a>
+  </div>
+</div>
+{% endblock body %}