Last week I was writing a talk to give at Google Developers Bus and I needed to show how to integrate Flask and Google Maps API,
as I did not found any extension to Google Maps I decided to create one.
One of the best things in Flask is the way it is extended by Extensions and Blueprints, by the way, Blueprints is one of
the best idea I’ve seem in Python web frameworks, once you start working with Blueprints you want to use it everywhere
(but unfortunatelly not every framework has an ellegant way to be extended)
I will start showing how the extension works and then I will explain how to build it from scratch.
Flask Google Maps
Template filter and a template global to create Google Maps from latitude and longitude
Installing
pip install flask-googlemaps
Loading in your app
from flask import Flask
from flask.ext.googlemaps import GoogleMaps
app = Flask(__name__)
GoogleMaps(app)
Using in templates
<div>
{{ googlemap('identifier', **params)}}
</div>
<div>
{{googlemap("map_name", lat=-0.12, lng=-0.45, markers=[(lat, lng), (lat, lng)]}}
</div>
Parameters:
- identifier: The name tat will be used to identify your map (you can have multiple maps in one page)
- lat: latitude to center the map
- lng: Longitude to center the map
- markers: a list of tuples, each tuple is a (lat, lng) marker (a pointer in the map)
- zoom: percentage of the zoom
- maptype: Google map type, TERRAIN or ROADMAP. defaults to ROADMAP
- varname: The JS varname to bind the map, defaults to "map"
- style: css style to be appended to the < div >
- cls: css class to the map < div >
TODO: In near future it will be possible to pass an address as argument
Example
The template
<body>
<h1>Flask Google Maps Example</h1>
<h2> Google Dev Bus - Rua Quatá, 255 </h2>
{% with %}
{% set location=(-23.599097,-46.675903) %}
{% set style="width:500px;height:500px;"%}
{{
googlemap(
"simple-map",
location.0, location.1,
markers=[location,],
style=style
)
}}
{% endwith %}
</body>
The output
Github
Screenshots and docs on Github.
https://github.com/rochacbruno/Flask-GoogleMaps
How to create a Flask Extension
Flask is extendable by two patterns Extension and Blueprint
An Extension is something like a complete plugin, a distribution containing models, views, templates, static files, template globals and filters etc
and usually an Extension is built of Blueprints, which is an app prototype, it can define the way an app will be when registered, exposing resources,
and url rules, also the Blueprint has the capability to access the current running application to contribute with things like config values, template filters, etc.
In the Flask docs there is a great explanation on Extensions and Blueprints
Anathomy of an extension
An extension is just a Python package following the naming convention Flask_anything, with packages naming like that Flask will automatically find them in the Python PATH via the ext proxy. So instead of from flask_anything import something you can do from flask.ext.anything import something
in that way the code will be very clear and explicit and you know you are dealing with a Flask extension.
Flask-Anything
root folder
|__ flask_anything/
|__ templates/
|__ static/
|__ __init__.py
|__ __some_module.py
|__ *
|__ setup.py
That is it! you can write really anything you want and it will be available throught from flask.ext.anything.some_module import FooBar
What is inside?
Usually extensions expose a main Class which will be registered in your app, there is no rule, but there is some conventions, an example:
# flask.ext.anything.some_module.py
from flask import Blueprint
class Anything(object):
def __init__(self, app=None, **kwargs):
for k, v in kwargs.items():
setattr(self, k, v)
if app:
self.init_app(app)
def init_app(self, app):
# here you get the app object and can do anything you want
app.add_template_filter("pass a template filter function here")
app.add_template_global("pass a template global here")
app.add_url_rule("/anything/<arg>", view_func=self.something)
#or even better you can register a Blueprint
module = self.create_blueprint("module")
another_module = self.create_another_blueprint("another_module")
# then you can register many blueprints in the app
app.register_blueprint(module)
app.register_blueprint(another_module)
def create_blueprint(self, blueprint_name):
module = Blueprint(blueprint_name, __name__, template_folder="a_path_to_relative_folder")
module.add_app_template_filter(...)
module.add-app_template_global(...)
module.add_url_rule("/something/<argument>", view_func=self.some_view)
return module
def some_view(self, argument):
context = {'argument': argument}
return self.render(self.get_template_name, context)
def render(self, *args, **kwargs):
return render_template(*args, **kwargs)
...
By the community convention your extension main class should receive its configurations in
__init__method and should have a lazy way to init defined as a method calledinit_app, also is a good practice to create methods for things likecreate_blueprint,register_blueprint,get_url_rulesand also arender_templatemethod inside your Blueprint is usefull. That is because others could extend your class and overwrite them, in example to use Flask-Themes it is usefull to overwrite therender_templatemethod.
Using your extension/Blueprint
# your_app.py
from flask import Flask
from flask.ext.anything.some_module import Anything
app = Flask(__name__)
# option 1
Anything(app)
# option 2
anything = Anything()
anything.init_app(app)
With the above instantiation/init_app your app will be manipulated by the extension and the views, urls, template filters etc will be available.
There is more conventions to follow as state, namespace, resource access etc, but you can find all the information on Flask docs.
If you have some idea to improve Flask-GoogleMaps, please comment!