Use Leaflet in your django projects
Project description
*django-leaflet* allows you to use `Leaflet <http://leaflet.cloudmade.com>`_
in your `Django <https://www.djangoproject.com>`_ projects.
It embeds Leaflet in version *0.5.1*.
=======
INSTALL
=======
::
pip install django-leaflet
=====
USAGE
=====
* Add ``leaflet`` to your ``INSTALLED_APPS``
* Add the HTML header::
{% load leaflet_tags %}
<head>
...
{% leaflet_js %}
{% leaflet_css %}
</head>
These tags also support loading CSS and JS resources for leaflet plugins.
All plugins msut be specified in settings.py in LEAFLET_CONFIG['PLUGINS'] as described below.
To include specific plugins in the page, specify plugin names, comma separated::
{% load leaflet_tags %}
<head>
...
{% leaflet_js plugins="bouncemarker, draw" %}
{% leaflet_css plugins="bouncemarker, draw"%}
</head>
To include all plugins configured in LEAFLET_CONFIG['PLUGINS'], use::
{% leaflet_js plugins="ALL" %}
{% leaflet_css plugins="ALL" %}
By default no plugins will be included.
* Add the map in your page, providing a name::
...
<body>
...
{% leaflet_map "yourmap" %}
...
</body>
* Your maps shows up!
Use Leaflet API
---------------
You can use the *Leaflet* API as usual in the map initialization callback::
<script type="text/javascript">
function yourmapInit(map, bounds) {
...
L.marker([50.5, 30.5]).addTo(map);
...
}
</script>
Customize map size
------------------
::
<style>
.leaflet-container { /* all maps */
width: 600px;
height: 400px;
}
#specialbigmap {
height: 800px;
}
</style>
Configuration
=============
In order to configure *django-leaflet*, just add a new section in your
settings::
LEAFLET_CONFIG = {
# conf here
}
Spatial extent
--------------
You can configure a global spatial extent for your maps, that will
automatically center your maps, restrict panning and add reset view and scale
controls. (*See advanced usage to tweak that.*)::
'SPATIAL_EXTENT': (5.0, 44.0, 7.5, 46)
Initial map center and zoom level
---------------------------------
In addition to limiting your maps with ``SPATIAL_EXTENT``, you can also specify
initial map center and zoom level::
'MAP_CENTER': (6.0, 45.0),
'MAP_ZOOM': 16,
The tuple/list must contain (lat,lng) coords.
Default tiles layer
-------------------
To globally add a tiles layer to your maps::
'TILES_URL': 'http://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png'
This setting can also be a list of tuples (name, url) ! A layer switcher
will then be added automatically.
Scale control
-------------
Disable scale control with km and miles::
'SCALE': False
Minimap control
---------------
Shows a small map in the corner which shows the same as the main map with a
set zoom offset::
'MINIMAP': True
By default it shows the tiles of the first layer in the list.
(`More info... <https://github.com/Norkart/Leaflet-MiniMap>`_)
Plugins
-------
To ease the usage of plugins, django-leaflet allows specifying a set of plugins, that can
later be referred to from the template tags by name::
'PLUGINS': {
'name-of-plugin': {
'css': ['relative/path/to/stylesheet.css', '/root/path/to/stylesheet.css'],
'js': 'http://absolute-url.example.com/path/to/script.js',
},
. . .
}
Both 'css' and 'js' support identical features for specifying resource URLs:
* can be either a plain string or a list of URLs
* each string can be:
- absolute URL - will be included as-is; **example**: ``http://absolute-url.example.com/path/to/script.js``
- a URL beginning from the root - will be included as-is; **example**: ``/root/path/to/stylesheet.css``
- a relative URL - settings.STATIC_URL will be prepended; **example**: ``relative/path/to/stylesheet.css`` will be included as **/static/relative/path/to/stylesheet.css** (depending on your setting for STATIC_URL)
Advanced usage
==============
``{% leaflet_map %}`` tag parameters
------------------------------------
* ``callback``: javascript function name for initialization callback.
(Default: ``name + Init``). Example::
{% leaflet_map "yourmap" callback="window.customMap" %}
* ``fixextent``: control if map initial view shoud be set to extent setting.
(Default: ``True``). Setting fixextent to ``False`` will prevent view reset
and scale controls to be added.
* ``creatediv``: control if the leaflet map tags creates a new div or not.
(Default: ``True``).
Useful to put the javascript code in the header or footer instead of the
body of the html document. If used, do not forget to create the div manually.
Projection
----------
It is possible to setup the map spatial reference in ``LEAFLET_CONFIG``::
'SRID': 2154 # See http://spatialreference.org
Additional parameter is required to compute scale levels : the tiles extent in
local projection::
'TILES_EXTENT': [700000, 6325197, 1060000, 6617738],
For more information, `have a look at this example <http://blog.mathieu-leplatre.info/leaflet-tiles-in-lambert-93-projection-2154.html>`_.
By default, Django will try to load the spatial reference from your static
files at "proj4js/{{ srid }}.js". If it fails, it will eventually rely on
`<spatialreference.org>`_.
=======
AUTHORS
=======
* Mathieu Leplatre <mathieu.leplatre@makina-corpus.com>
* Ariel Núñez <http://ingenieroariel.com>
* Boris Chervenkov <https://github.com/boris-chervenkov>
|makinacom|_
.. |makinacom| image:: http://depot.makina-corpus.org/public/logo.gif
.. _makinacom: http://www.makina-corpus.com
=======
LICENSE
=======
* Lesser GNU Public License
* Leaflet Copyright - 2010-2011 CloudMade, Vladimir Agafonkin
=========
CHANGELOG
=========
0.5.1
=====
* Update Leaflet.Minimap
* Fix apparence of Reset view button
0.5.1 (2013-04-08)
==================
* Add minimap support
* Drop Leaflet version switching
* Update Leaflet to 0.5.1
0.4.1 (2012-11-05)
==================
* Fix div creation test in template.
0.4.0 (2012-11-05)
==================
* Remove imperial scale.
* Add ``create_div`` parameter
0.3.0 (2012-10-26)
==================
* Remove max resolution setting since it can be computed
* Allow scale control even if view is not set
* Upgrade Leaflet to 0.4.5
0.2.0 (2012-09-22)
==================
* Fix packaging of templates
* Use template for <head> fragment
* Do not rely on spatialreference.org by default
* Default settings for SRID
* Default settings for map extent
* Default map height
* Default tiles base layer
* map variable is not global anymore
0.1.0 (2012-08-13)
==================
* Initial support for map projection
* Show zoom scale by default
* Spatial extent configuration
* Initialization callback instead of global JS variable
* Leaflet version switching
* Global layers configuration
0.0.2 (2012-03-22)
==================
* Add IE conditional CSS
0.0.1 (2012-03-16)
==================
* Initial working version
in your `Django <https://www.djangoproject.com>`_ projects.
It embeds Leaflet in version *0.5.1*.
=======
INSTALL
=======
::
pip install django-leaflet
=====
USAGE
=====
* Add ``leaflet`` to your ``INSTALLED_APPS``
* Add the HTML header::
{% load leaflet_tags %}
<head>
...
{% leaflet_js %}
{% leaflet_css %}
</head>
These tags also support loading CSS and JS resources for leaflet plugins.
All plugins msut be specified in settings.py in LEAFLET_CONFIG['PLUGINS'] as described below.
To include specific plugins in the page, specify plugin names, comma separated::
{% load leaflet_tags %}
<head>
...
{% leaflet_js plugins="bouncemarker, draw" %}
{% leaflet_css plugins="bouncemarker, draw"%}
</head>
To include all plugins configured in LEAFLET_CONFIG['PLUGINS'], use::
{% leaflet_js plugins="ALL" %}
{% leaflet_css plugins="ALL" %}
By default no plugins will be included.
* Add the map in your page, providing a name::
...
<body>
...
{% leaflet_map "yourmap" %}
...
</body>
* Your maps shows up!
Use Leaflet API
---------------
You can use the *Leaflet* API as usual in the map initialization callback::
<script type="text/javascript">
function yourmapInit(map, bounds) {
...
L.marker([50.5, 30.5]).addTo(map);
...
}
</script>
Customize map size
------------------
::
<style>
.leaflet-container { /* all maps */
width: 600px;
height: 400px;
}
#specialbigmap {
height: 800px;
}
</style>
Configuration
=============
In order to configure *django-leaflet*, just add a new section in your
settings::
LEAFLET_CONFIG = {
# conf here
}
Spatial extent
--------------
You can configure a global spatial extent for your maps, that will
automatically center your maps, restrict panning and add reset view and scale
controls. (*See advanced usage to tweak that.*)::
'SPATIAL_EXTENT': (5.0, 44.0, 7.5, 46)
Initial map center and zoom level
---------------------------------
In addition to limiting your maps with ``SPATIAL_EXTENT``, you can also specify
initial map center and zoom level::
'MAP_CENTER': (6.0, 45.0),
'MAP_ZOOM': 16,
The tuple/list must contain (lat,lng) coords.
Default tiles layer
-------------------
To globally add a tiles layer to your maps::
'TILES_URL': 'http://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png'
This setting can also be a list of tuples (name, url) ! A layer switcher
will then be added automatically.
Scale control
-------------
Disable scale control with km and miles::
'SCALE': False
Minimap control
---------------
Shows a small map in the corner which shows the same as the main map with a
set zoom offset::
'MINIMAP': True
By default it shows the tiles of the first layer in the list.
(`More info... <https://github.com/Norkart/Leaflet-MiniMap>`_)
Plugins
-------
To ease the usage of plugins, django-leaflet allows specifying a set of plugins, that can
later be referred to from the template tags by name::
'PLUGINS': {
'name-of-plugin': {
'css': ['relative/path/to/stylesheet.css', '/root/path/to/stylesheet.css'],
'js': 'http://absolute-url.example.com/path/to/script.js',
},
. . .
}
Both 'css' and 'js' support identical features for specifying resource URLs:
* can be either a plain string or a list of URLs
* each string can be:
- absolute URL - will be included as-is; **example**: ``http://absolute-url.example.com/path/to/script.js``
- a URL beginning from the root - will be included as-is; **example**: ``/root/path/to/stylesheet.css``
- a relative URL - settings.STATIC_URL will be prepended; **example**: ``relative/path/to/stylesheet.css`` will be included as **/static/relative/path/to/stylesheet.css** (depending on your setting for STATIC_URL)
Advanced usage
==============
``{% leaflet_map %}`` tag parameters
------------------------------------
* ``callback``: javascript function name for initialization callback.
(Default: ``name + Init``). Example::
{% leaflet_map "yourmap" callback="window.customMap" %}
* ``fixextent``: control if map initial view shoud be set to extent setting.
(Default: ``True``). Setting fixextent to ``False`` will prevent view reset
and scale controls to be added.
* ``creatediv``: control if the leaflet map tags creates a new div or not.
(Default: ``True``).
Useful to put the javascript code in the header or footer instead of the
body of the html document. If used, do not forget to create the div manually.
Projection
----------
It is possible to setup the map spatial reference in ``LEAFLET_CONFIG``::
'SRID': 2154 # See http://spatialreference.org
Additional parameter is required to compute scale levels : the tiles extent in
local projection::
'TILES_EXTENT': [700000, 6325197, 1060000, 6617738],
For more information, `have a look at this example <http://blog.mathieu-leplatre.info/leaflet-tiles-in-lambert-93-projection-2154.html>`_.
By default, Django will try to load the spatial reference from your static
files at "proj4js/{{ srid }}.js". If it fails, it will eventually rely on
`<spatialreference.org>`_.
=======
AUTHORS
=======
* Mathieu Leplatre <mathieu.leplatre@makina-corpus.com>
* Ariel Núñez <http://ingenieroariel.com>
* Boris Chervenkov <https://github.com/boris-chervenkov>
|makinacom|_
.. |makinacom| image:: http://depot.makina-corpus.org/public/logo.gif
.. _makinacom: http://www.makina-corpus.com
=======
LICENSE
=======
* Lesser GNU Public License
* Leaflet Copyright - 2010-2011 CloudMade, Vladimir Agafonkin
=========
CHANGELOG
=========
0.5.1
=====
* Update Leaflet.Minimap
* Fix apparence of Reset view button
0.5.1 (2013-04-08)
==================
* Add minimap support
* Drop Leaflet version switching
* Update Leaflet to 0.5.1
0.4.1 (2012-11-05)
==================
* Fix div creation test in template.
0.4.0 (2012-11-05)
==================
* Remove imperial scale.
* Add ``create_div`` parameter
0.3.0 (2012-10-26)
==================
* Remove max resolution setting since it can be computed
* Allow scale control even if view is not set
* Upgrade Leaflet to 0.4.5
0.2.0 (2012-09-22)
==================
* Fix packaging of templates
* Use template for <head> fragment
* Do not rely on spatialreference.org by default
* Default settings for SRID
* Default settings for map extent
* Default map height
* Default tiles base layer
* map variable is not global anymore
0.1.0 (2012-08-13)
==================
* Initial support for map projection
* Show zoom scale by default
* Spatial extent configuration
* Initialization callback instead of global JS variable
* Leaflet version switching
* Global layers configuration
0.0.2 (2012-03-22)
==================
* Add IE conditional CSS
0.0.1 (2012-03-16)
==================
* Initial working version
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
django-leaflet-0.5.1.tar.gz
(125.3 kB
view details)
File details
Details for the file django-leaflet-0.5.1.tar.gz.
File metadata
- Download URL: django-leaflet-0.5.1.tar.gz
- Upload date:
- Size: 125.3 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 87ee889a54710d414e0e17a5d7126135ea7adbff10060343d9df68648795e301 |
|
| MD5 | c8ed35e2a3b545d1ecc6e43c3ad15dda |
|
| BLAKE2b-256 | 59e3eb36b300adc9b5c31bc3744de3cfcf24e4b16245c73127f48dbe3e77a271 |
