Author: |
GRAP, Odoo Community Association (OCA) |
License: |
AGPL-3 |
Branch: |
12.0 |
Repository: |
acsone/geospatial |
Dependencies: |
base_geolocalize,
and
web |
Languages: |
CSS (607, 40.0%),
HTML (452, 29.8%),
JavaScript (160, 10.5%),
PO File (54, 3.6%),
Python (68, 4.5%),
XML (29, 1.9%),
and
reStructuredText (149, 9.8%) |
Other repositories: |
Change2improve/geospatial,
OCA/geospatial,
agrista/odoo-geospatial,
and
zarumaru/geospatial |
<h1 class="title">Leaflet Map View (OpenStreetMap)</h1>
<p><a class="reference external image-reference" href="https://odoo-community.org/page/development-status"><img alt="Alpha" src="https://img.shields.io/badge/maturity-Alpha-red.png" /></a> <a class="reference external image-reference" href="http://www.gnu.org/licenses/agpl-3.0-standalone.html"><img alt="License: AGPL-3" src="https://img.shields.io/badge/licence-AGPL--3-blue.png" /></a> <a class="reference external image-reference" href="https://github.com/OCA/geospatial/tree/12.0/web_view_leaflet_map"><img alt="OCA/geospatial" src="https://img.shields.io/badge/github-OCA%2Fgeospatial-lightgray.png?logo=github" /></a> <a class="reference external image-reference" href="https://translation.odoo-community.org/projects/geospatial-12-0/geospatial-12-0-web_view_leaflet_map"><img alt="Translate me on Weblate" src="https://img.shields.io/badge/weblate-Translate%20me-F47D42.png" /></a> <a class="reference external image-reference" href="https://runbot.odoo-community.org/runbot/115/12.0"><img alt="Try me on Runbot" src="https://img.shields.io/badge/runbot-Try%20me-875A7B.png" /></a></p>
<p>This module extends odoo views, to add a new kind of view, named <code>leaflet_map</code>
that is using the Leaflet javascript library to use maps. (<a class="reference external" href="https://leafletjs.com/">https://leafletjs.com/</a>)
This library is for exemple, used in the OpenStreetMap project. (<a class="reference external" href="https://www.openstreetmap.org/">https://www.openstreetmap.org/</a>)</p>
<p>You can see a simple usage in the module <code>web_view_leaflet_map_partner</code> in the
same OCA repository that displays your contact in a map, if latitude and longitude are
defined. (To define latitude and longitude, refer to the Odoo module <code>base_geolocalize</code>)</p>
<div class="figure">
<img alt="https://raw.githubusercontent.com/OCA/geospatial/12.0/web_view_leaflet_map/static/description/view_res_partner_map_1.png" src="https://raw.githubusercontent.com/OCA/geospatial/12.0/web_view_leaflet_map/static/description/view_res_partner_map_1.png" />
</div>
<div class="figure">
<img alt="https://raw.githubusercontent.com/OCA/geospatial/12.0/web_view_leaflet_map/static/description/view_res_partner_map_2.png" src="https://raw.githubusercontent.com/OCA/geospatial/12.0/web_view_leaflet_map/static/description/view_res_partner_map_2.png" />
</div>
<p><strong>Important Note</strong></p>
<p>The javascript library is opensource and distributed under BSD 2 Licence.
See : <a class="reference external" href="https://github.com/Leaflet/Leaflet/blob/main/LICENSE">https://github.com/Leaflet/Leaflet/blob/main/LICENSE</a>
You can so use it freely.</p>
<p>However, display maps requires to display layers provided by tiles servers, that
requires ressources.</p>
<p><strong>For testing purpose</strong></p>
<p>you can use the openStreetMap url <code>https://tile.openstreetmap.org/{z}/{x}/{y}.png</code> or other, listed in that page : <a class="reference external" href="https://wiki.openstreetmap.org/wiki/Tile_servers">https://wiki.openstreetmap.org/wiki/Tile_servers</a></p>
<p>Apart from very limited testing purposes, you should not use the tiles supplied by OpenStreetMap.org itself. OpenStreetMap is a volunteer-run non-profit body and cannot supply tiles for large-scale commercial use.</p>
<p><strong>Regular / High Usage</strong></p>
<ul class="simple">
<li>you can contact one of the following companies : <a class="reference external" href="https://switch2osm.org/providers/">https://switch2osm.org/providers/</a></li>
<li>You can also install yourself your own tiles servers. See documentation : <a class="reference external" href="https://switch2osm.org/serving-tiles/">https://switch2osm.org/serving-tiles/</a></li>
</ul>
<div class="admonition important">
<p class="first admonition-title">Important</p>
<p class="last">This is an alpha version, the data model and design can change at any time without warning.
Only for development or testing purpose, do not use in production.
<a class="reference external" href="https://odoo-community.org/page/development-status">More details on development status</a></p>
</div>
<p><strong>Table of contents</strong></p>
<div class="contents local topic" id="contents">
<ul class="simple">
<li><a class="reference internal" href="#configuration" id="id1">Configuration</a></li>
<li><a class="reference internal" href="#development" id="id2">Development</a></li>
<li><a class="reference internal" href="#known-issues-roadmap" id="id3">Known issues / Roadmap</a></li>
<li><a class="reference internal" href="#bug-tracker" id="id4">Bug Tracker</a></li>
<li><a class="reference internal" href="#credits" id="id5">Credits</a><ul>
<li><a class="reference internal" href="#authors" id="id6">Authors</a></li>
<li><a class="reference internal" href="#contributors" id="id7">Contributors</a></li>
<li><a class="reference internal" href="#other-credits" id="id8">Other credits</a></li>
<li><a class="reference internal" href="#maintainers" id="id9">Maintainers</a></li>
</ul>
</li>
</ul>
</div>
<a name="configuration"></a>
<h2><a class="toc-backref" href="#id1">Configuration</a></h2>
<ul class="simple">
<li>Go to Settings > Technical > Parameters > System Parameters</li>
<li>Create or edit the parameter with the key <code>leaflet.tile_url</code></li>
<li>As a value, set the url of the tiles server you chose. (See description)</li>
</ul>
<a name="development"></a>
<h2><a class="toc-backref" href="#id2">Development</a></h2>
<p>Create a new view :</p>
<pre>
<code lang="xml"><record id="view_my_model_map" model="ir.ui.view">
<field name="model">my.model</field>
<field name="arch" type="xml">
<leaflet_map
field_latitude="FIELD_LATITUDE"
field_longitude="FIELD_LONGITUDE"
field_title="FIELD_TITLE"
field_address="FIELD_ADDRESS"
field_marker_icon_image="FIELD_MARKER_ICON_IMAGE"
>
<field name="__last_update"/>
<field name="FIELD_LATITUDE"/>
<field name="FIELD_LONGITUDE"/>
<field name="FIELD_TITLE"/>
<field name="FIELD_ADDRESS"/>
</leaflet_map>
</field>
</record></code>
</pre>
<ol class="arabic simple">
<li>FIELD_LATITUDE and FIELD_LONGITUDE are the name of the fields that contains GPS coordinates of the model.</li>
<li>FIELD_TITLE will be used when the popup is displayed, as a title.</li>
<li>FIELD_ADDRESS will be used when the popup is displayed to display the adress.</li>
<li>(optional) FIELD_MARKER_ICON_IMAGE, is the name of the image field to place as an icon
of the marker.
Note: You can set extra settings <code>marker_icon_size_x</code>, <code>marker_icon_size_y</code>, to define
the size of the image, and <code>marker_popup_anchor_x</code>, <code>marker_popup_anchor_y</code> to define
the position of the popup.</li>
</ol>
<p>Map options :</p>
<ul class="simple">
<li><code>default_zoom</code> : define the default zoom value. (7 if not defined)</li>
<li><code>max_zoom</code> : define the max zoom value. (19 if not defined)</li>
<li><code>zoom_snap</code> : define the zoom level in each change. (1 if not defined)</li>
</ul>
<ul class="simple">
<li>Create or update an action for the model</li>
</ul>
<pre>
<code lang="xml"><record id="my_module.action_my_model" model="ir.actions.act_window">
<field name="view_mode">tree,form,leaflet_map</field>
</record></code>
</pre>
<p><strong>Library Update</strong></p>
<p>For the time being, the module embed the lealflet.js library version 1.8.0 ( released on April 18, 2022.)</p>
<p>If a new release is out:</p>
<ul class="simple">
<li>please download it here <a class="reference external" href="https://leafletjs.com/download.html">https://leafletjs.com/download.html</a></li>
<li>update the javascript, css and images, present in the folder <code>static/lib/leaflet</code></li>
<li>test the features</li>
<li>make a Pull Request</li>
</ul>
<p><strong>Default position in the map</strong></p>
<p>By default, the position of the map is defined by the user, in the function
<code>get_default_leaflet_position</code>. It returns the position of the current company, if defined.
you can overload this function globally, or per model.</p>
<a name="known-issues-roadmap"></a>
<h2><a class="toc-backref" href="#id3">Known issues / Roadmap</a></h2>
<ul class="simple">
<li>For the time being, at the start of the map loading, the call of <code>invalidateSize()</code>
is required. We should investigate why and try to remove that call.
see <a class="reference external" href="https://github.com/Leaflet/Leaflet/issues/3002#issuecomment-93836022">https://github.com/Leaflet/Leaflet/issues/3002#issuecomment-93836022</a></li>
<li>For the time being, the map has "Markers" and allow to display odoo items
if longitude and latitude are available. We could imagine other kind of usages,
with Polylines, Polygons, etc...
See all the leaflet options : <a class="reference external" href="https://leafletjs.com/reference.html">https://leafletjs.com/reference.html</a></li>
<li>The module could not work properly on mobile devices.</li>
</ul>
<a name="bug-tracker"></a>
<h2><a class="toc-backref" href="#id4">Bug Tracker</a></h2>
<p>Bugs are tracked on <a class="reference external" href="https://github.com/OCA/geospatial/issues">GitHub Issues</a>.
In case of trouble, please check there if your issue has already been reported.
If you spotted it first, help us smashing it by providing a detailed and welcomed
<a class="reference external" href="https://github.com/OCA/geospatial/issues/new?body=module:%20web_view_leaflet_map%0Aversion:%2012.0%0A%0A**Steps%20to%20reproduce**%0A-%20...%0A%0A**Current%20behavior**%0A%0A**Expected%20behavior**">feedback</a>.</p>
<p>Do not contact contributors directly about support or help with technical issues.</p>
<a name="credits"></a>
<h2><a class="toc-backref" href="#id5">Credits</a></h2>
<a name="authors"></a>
<h3><a class="toc-backref" href="#id6">Authors</a></h3>
<ul class="simple">
<li>GRAP</li>
</ul>
<a name="contributors"></a>
<h3><a class="toc-backref" href="#id7">Contributors</a></h3>
<ul class="simple">
<li>Sylvain LE GAL (<a class="reference external" href="https://www.twitter.com/legalsylvain">https://www.twitter.com/legalsylvain</a>)</li>
</ul>
<a name="other-credits"></a>
<h3><a class="toc-backref" href="#id8">Other credits</a></h3>
<p>The module embed the Leaflet.js library.</p>
<a name="maintainers"></a>
<h3><a class="toc-backref" href="#id9">Maintainers</a></h3>
<p>This module is maintained by the OCA.</p>
<a class="reference external image-reference" href="https://odoo-community.org"><img alt="Odoo Community Association" src="https://odoo-community.org/logo.png" /></a>
<p>OCA, or the Odoo Community Association, is a nonprofit organization whose
mission is to support the collaborative development of Odoo features and
promote its widespread use.</p>
<p>Current <a class="reference external" href="https://odoo-community.org/page/maintainer-role">maintainer</a>:</p>
<p><a class="reference external image-reference" href="https://github.com/legalsylvain"><img alt="legalsylvain" src="https://github.com/legalsylvain.png?size=40px" /></a></p>
<p>This module is part of the <a class="reference external" href="https://github.com/OCA/geospatial/tree/12.0/web_view_leaflet_map">OCA/geospatial</a> project on GitHub.</p>
<p>You are welcome to contribute. To learn how please visit <a class="reference external" href="https://odoo-community.org/page/Contribute">https://odoo-community.org/page/Contribute</a>.</p>