Merge pull request #364 from petrus-jvrensburg/examples

Examples

.gitignore

@@ -13,7 +13,6 @@ flask_admin/tests/tmp
 dist/*
 make.bat
 venv
-*.sqlite
 *.sublime-*
 .coverage
 __pycache__

README.rst

@@ -23,9 +23,6 @@ Out-of-the-box, Flask-Admin plays nicely with various ORM's, including
 
 It also boasts a simple file management interface and a `redis client <http://redis.io/>`_ console.
 
-Several usage examples are included in the */examples* folder. Please feel free to add your own examples, or improve
-on some of the existing ones, and then submit them via GitHub as a *pull-request*.
-
 The biggest feature of Flask-Admin is flexibility. It aims to provide a set of simple tools that can be used for
 building admin interfaces of any complexity. So, to start off with you can create a very simple application in no time,
 with auto-generated CRUD-views for each of your models. But then you can go further and customize those views & forms
@@ -33,6 +30,18 @@ as the need arises.
 
 Flask-Admin is an active project, well-tested and production ready.
 
+Examples
+--------
+Several usage examples are included in the */examples* folder. Please feel free to add your own examples, or improve
+on some of the existing ones, and then submit them via GitHub as a *pull-request*.
+
+You can see some of these examples in action at `http://examples.flask-admin.org <http://examples.flask-admin.org/>`_.
+
+To run one of the examples in your local environment, simply::
+
+    cd flask-admin
+    python examples/simple/simple.py
+
 Documentation
 -------------
 Flask-Admin is extensively documented, you can find all of the documentation at `http://readthedocs.org/docs/flask-admin <http://readthedocs.org/docs/flask-admin>`_.
@@ -40,6 +49,14 @@ Flask-Admin is extensively documented, you can find all of the documentation at
 The docs are auto-generated from the *.rst* files in the */doc* folder. So if you come across any errors, or
 if you think of anything else that should be included, then please make the changes and submit them as a *pull-request*.
 
+To build the docs in your local environment::
+
+    sudo pip install sphinx
+    cd flask-admin
+    sudo make html
+
+Or, if you want to preview any *.rst* snippets that you may want to contribute, go to `http://rst.ninjs.org/ <http://rst.ninjs.org/>`_.
+
 Installation
 ------------
 To install Flask-Admin, simply::

doc/index.rst

@@ -5,6 +5,8 @@ Flask-Admin is a batteries-included, simple-to-use `Flask <http://flask.pocoo.or
 add admin interfaces to Flask applications. It is inspired by the *django-admin* package, but implemented in such
 a way that the developer has total control of the look, feel and functionality of the resulting application.
 
+You can see some examples of how Flask-Admin can be used at `http://examples.flask-admin.org <http://examples.flask-admin.org/>`_.
+
 Browse through the documentation below to learn more about what you can do with Flask-Admin. Or head over to
 `our GitHub repository <http://github.com/mrjoes/flask-admin>`_ to find out how you can contribute to the project.
 

examples/layout/simple.py

@@ -11,7 +11,7 @@ app = Flask(__name__)
 app.config['SECRET_KEY'] = '123456790'
 
 # Create in-memory database
-app.config['SQLALCHEMY_DATABASE_URI'] = 'sqlite:///dummy.sqlite'
+app.config['SQLALCHEMY_DATABASE_URI'] = 'sqlite:///sample_db.sqlite'
 app.config['SQLALCHEMY_ECHO'] = True
 db = SQLAlchemy(app)
 
@@ -53,13 +53,14 @@ def index():
     return '<a href="/admin/">Click me to get to Admin!</a>'
 
 
-if __name__ == '__main__':
-    # Create admin with custom base template
-    admin = admin.Admin(app, base_template='layout.html')
+# Create admin with custom base template
+admin = admin.Admin(app, base_template='layout.html')
+
+# Add views
+admin.add_view(UserAdmin(User, db.session))
+admin.add_view(CustomView(Page, db.session))
 
-    # Add views
-    admin.add_view(UserAdmin(User, db.session))
-    admin.add_view(CustomView(Page, db.session))
+if __name__ == '__main__':
 
     # Create DB
     db.create_all()

examples/layout/templates/admin/index.html

+{% extends 'admin/master.html' %}
+{% block body %}
+{{ super() }}
+<div class="row-fluid">
+    <h1>Flask-Admin example</h1>
+    <p class="lead">
+        Customize the layout
+    </p>
+    <p>
+        This example shows how you can customize the look & feel of the admin interface.
+    </p>
+    <p>
+        This is done by overriding some of the built-in templates.
+    </p>
+    <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/quickstart/first.py

@@ -3,6 +3,11 @@ from flask.ext.admin import Admin
 
 
 app = Flask(__name__)
+app.debug = True
 
 admin = Admin(app)
-app.run(debug=True)
+
+if __name__ == '__main__':
+
+    # Start app
+    app.run(debug=True)

examples/quickstart/second.py

@@ -8,8 +8,12 @@ class MyView(BaseView):
         return self.render('index.html')
 
 app = Flask(__name__)
+app.debug = True
 
 admin = Admin(app)
 admin.add_view(MyView(name='Hello'))
 
-app.run(debug=True)
+if __name__ == '__main__':
+
+    # Start app
+    app.run()

examples/quickstart/third.py

 from flask import Flask
 from flask.ext.admin import Admin, BaseView, expose
 
+
 class MyView(BaseView):
     @expose('/')
     def index(self):
         return self.render('index.html')
 
 app = Flask(__name__)
+app.debug = True
 
 admin = Admin(app)
 admin.add_view(MyView(name='Hello 1', endpoint='test1', category='Test'))
 admin.add_view(MyView(name='Hello 2', endpoint='test2', category='Test'))
 admin.add_view(MyView(name='Hello 3', endpoint='test3', category='Test'))
-app.run(debug=True)
+
+if __name__ == '__main__':
+
+    # Start app
+    app.run()

examples/simple/simple.py

@@ -22,20 +22,20 @@ class AnotherAdminView(admin.BaseView):
 
 # Create flask app
 app = Flask(__name__, template_folder='templates')
-
+app.debug = True
 
 # Flask views
 @app.route('/')
 def index():
     return '<a href="/admin/">Click me to get to Admin!</a>'
 
+# Create admin interface
+admin = admin.Admin()
+admin.add_view(MyAdminView(category='Test'))
+admin.add_view(AnotherAdminView(category='Test'))
+admin.init_app(app)
 
 if __name__ == '__main__':
-    # Create admin interface
-    admin = admin.Admin()
-    admin.add_view(MyAdminView(category='Test'))
-    admin.add_view(AnotherAdminView(category='Test'))
-    admin.init_app(app)
 
     # Start app
-    app.run(debug=True)
+    app.run()

examples/simple/templates/admin/index.html

+{% extends 'admin/master.html' %}
+{% block body %}
+{{ super() }}
+<div class="row-fluid">
+    <h1>Flask-Admin example</h1>
+    <p class="lead">
+        Simple admin views, not related to models.
+    </p>
+    <p>
+        This example shows how to add your own views to the admin interface. The views do not have to be associated
+        to any of your models, and you can fill them with whatever content you want.
+    </p>
+    <p>
+        By adding custom views to the admin interface, they become accessible through the <em>navbar</em> at the top.
+    </p>
+    <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/sqla/multiplepk.py → examples/sqla/multiple_pk.py

@@ -13,7 +13,7 @@ app = Flask(__name__)
 app.config['SECRET_KEY'] = '123456790'
 
 # Create in-memory database
-app.config['SQLALCHEMY_DATABASE_URI'] = 'sqlite:///test.sqlite'
+app.config['SQLALCHEMY_DATABASE_URI'] = 'sqlite:///sample_db_2.sqlite'
 app.config['SQLALCHEMY_ECHO'] = True
 db = SQLAlchemy(app)
 
@@ -22,6 +22,7 @@ db = SQLAlchemy(app)
 def index():
     return '<a href="/admin/">Click me to get to Admin!</a>'
 
+
 class Car(db.Model):
     __tablename__ = 'cars'
     id = db.Column(db.Integer, primary_key=True, autoincrement=True)
@@ -30,6 +31,7 @@ class Car(db.Model):
     def __unicode__(self):
         return self.desc
 
+
 class Tyre(db.Model):
     __tablename__ = 'tyres'
     car_id = db.Column(db.Integer, db.ForeignKey('cars.id'), primary_key=True)
@@ -37,19 +39,22 @@ class Tyre(db.Model):
     car = db.relationship('Car', backref='tyres')
     desc = db.Column(db.String(50))
 
+
 class CarAdmin(sqla.ModelView):
     column_display_pk = True
     form_columns = ['id', 'desc']
 
+
 class TyreAdmin(sqla.ModelView):
     column_display_pk = True
     form_columns = ['car', 'tyre_id', 'desc']
 
+# Create admin
+admin = admin.Admin(app, 'Simple Models')
+admin.add_view(CarAdmin(Car, db.session))
+admin.add_view(TyreAdmin(Tyre, db.session))
+
 if __name__ == '__main__':
-    # Create admin
-    admin = admin.Admin(app, 'Simple Models')
-    admin.add_view(CarAdmin(Car, db.session))
-    admin.add_view(TyreAdmin(Tyre, db.session))
 
     # Create DB
     db.create_all()

examples/sqla/simple.py

@@ -16,7 +16,7 @@ app = Flask(__name__)
 app.config['SECRET_KEY'] = '123456790'
 
 # Create in-memory database
-app.config['SQLALCHEMY_DATABASE_URI'] = 'sqlite:///test.sqlite'
+app.config['SQLALCHEMY_DATABASE_URI'] = 'sqlite:///sample_db.sqlite'
 app.config['SQLALCHEMY_ECHO'] = True
 db = SQLAlchemy(app)
 
@@ -139,15 +139,16 @@ class TreeView(sqla.ModelView):
     inline_models = (Tree,)
 
 
+# Create admin
+admin = admin.Admin(app, 'Simple Models')
+
+# Add views
+admin.add_view(UserAdmin(User, db.session))
+admin.add_view(sqla.ModelView(Tag, db.session))
+admin.add_view(PostAdmin(db.session))
+admin.add_view(TreeView(Tree, db.session))
+
 if __name__ == '__main__':
-    # Create admin
-    admin = admin.Admin(app, 'Simple Models')
-
-    # Add views
-    admin.add_view(UserAdmin(User, db.session))
-    admin.add_view(sqla.ModelView(Tag, db.session))
-    admin.add_view(PostAdmin(db.session))
-    admin.add_view(TreeView(Tree, db.session))
 
     # Create DB
     db.create_all()

examples/sqla/templates/admin/index.html

+{% extends 'admin/master.html' %}
+{% block body %}
+{{ super() }}
+<div class="row-fluid">
+    <h1>Flask-Admin example</h1>
+    <p class="lead">
+        Basic SQLAlchemy model views.
+    </p>
+    <p>
+        This example shows how to add basic CRUD-views for your SQLAlchemy models.
+    </p>
+    <p>
+        The views are generated automatically, but it is perfectly possible to customize them to suit your needs.
+    </p>
+    <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