Skip to content

Commit e7cbc13

Browse files
RiverfountRiverfount
committed
Fixed documentation link to edit it
1 parent e9cbd93 commit e7cbc13

File tree

5 files changed

+326
-310
lines changed

5 files changed

+326
-310
lines changed

‎docs/docs/contribute.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# Contribute
2+
3+
To contribute with the project, clone it, create a virtualenv and install all of you need to dev, see below:
4+
5+
```bash
6+
git clone https://github.com/flask-extensions/Flask-GoogleMaps.git
7+
cd Flask-GoogleMaps
8+
poetry use env 3.8 # just to create virtualenv at the first time
9+
poetry shell # activate virtualenv
10+
poetry install # to install all for dev
11+
```

‎docs/docs/how_it_works.md‎

Lines changed: 277 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,277 @@
1+
# How it works
2+
3+
Flask-GoogleMaps includes some global functions and template filters in your Jinja environment, also it allows you to use the Map in views if needed.
4+
5+
## registering
6+
7+
in your app
8+
9+
```python
10+
11+
from flask import Flask
12+
from flask_googlemaps import GoogleMaps
13+
14+
app = Flask(__name__)
15+
16+
# you can set key as config
17+
app.config['GOOGLEMAPS_KEY'] = "8JZ7i18MjFuM35dJHq70n3Hx4"
18+
19+
# Initialize the extension
20+
GoogleMaps(app)
21+
22+
# you can also pass the key here if you prefer
23+
GoogleMaps(app, key="8JZ7i18MjFuM35dJHq70n3Hx4")
24+
25+
```
26+
27+
In template
28+
29+
```html
30+
{{googlemap("my_awesome_map", lat=0.23234234, lng=-0.234234234, markers=[(0.12,
31+
-0.45345), ...])}}
32+
```
33+
34+
That's it! now you have some template filters and functions to use, more details in examples and screenshot below.
35+
36+
## Usage
37+
38+
- You can create the map in the view and then send to the template context
39+
- you can use the template functions and filters directly
40+
41+
### 1. View
42+
43+
```python
44+
45+
from flask import Flask, render_template
46+
from flask_googlemaps import GoogleMaps
47+
from flask_googlemaps import Map
48+
49+
app = Flask(__name__, template_folder=".")
50+
GoogleMaps(app)
51+
52+
@app.route("/")
53+
def mapview():
54+
# creating a map in the view
55+
mymap = Map(
56+
identifier="view-side",
57+
lat=37.4419,
58+
lng=-122.1419,
59+
markers=[(37.4419, -122.1419)]
60+
)
61+
sndmap = Map(
62+
identifier="sndmap",
63+
lat=37.4419,
64+
lng=-122.1419,
65+
markers=[
66+
{
67+
'icon': 'http://maps.google.com/mapfiles/ms/icons/green-dot.png',
68+
'lat': 37.4419,
69+
'lng': -122.1419,
70+
'infobox': "<b>Hello World</b>"
71+
},
72+
{
73+
'icon': 'http://maps.google.com/mapfiles/ms/icons/blue-dot.png',
74+
'lat': 37.4300,
75+
'lng': -122.1400,
76+
'infobox': "<b>Hello World from other place</b>"
77+
}
78+
]
79+
)
80+
return render_template('example.html', mymap=mymap, sndmap=sndmap)
81+
82+
if __name__ == "__main__":
83+
app.run(debug=True)
84+
85+
```
86+
87+
#### `Map()` Parameters
88+
89+
- **lat**: The latitude coordinate for centering the map.
90+
- **lng**: The longitutde coordinate for centering the map.
91+
- **zoom**: The zoom level. Defaults to `13`.
92+
- **maptype**: The map type - `ROADMAP`, `SATELLITE`, `HYBRID`, `TERRAIN`. Defaults to `ROADMAP`.
93+
- **markers**: Markers array of tuples having (**lat**, **lng**, infobox, icon). Defaults to `None`.
94+
- or **markers**: a list of dicts containing **icon, lat, lng, infobox**.
95+
- or **markers**: Markers dictionary with icon urls as keys and markers array as values.
96+
- **varname**: The instance variable name.
97+
- **style**: A string containing CSS styles. Defaults to `"height:300px;width:300px;margin:0;"`.
98+
- **identifier**: The CSS ID selector name.
99+
- **cls**: The CSS Class selector name. Defaults to `"map"`.
100+
- **language**: The map language. Defaults to `"en"`.
101+
- **region**: The map region. Defaults to `"US"`.
102+
103+
Also controls True or False:
104+
105+
- zoom_control
106+
- maptype_control
107+
- scale_control
108+
- scale_control
109+
- streetview_control
110+
- rotate_control
111+
- fullscreen_control
112+
- scroll_wheel
113+
- collapsible (map collapses by click on **varname**\_collapse button)
114+
- center_on_user_location (using HTML5 Geolocation)
115+
116+
### 2. Template
117+
118+
```html
119+
<!DOCTYPE html>
120+
<html>
121+
<head>
122+
{{"decoupled-map"|googlemap_js(37.4419, -122.1419, markers=[(37.4419,
123+
-122.1419)])}} {{mymap.js}} {{sndmap.js}}
124+
</head>
125+
<body>
126+
<h1>Flask Google Maps Example</h1>
127+
128+
<h2>Template function centered, no marker</h2>
129+
{{googlemap("simple-map", 37.4419, -122.1419)}}
130+
131+
<h2>Template filter decoupled with single marker</h2>
132+
{{"decoupled-map"|googlemap_html(37.4419, -122.1419)}}
133+
134+
<h2>Template function with multiple markers</h2>
135+
{% with map=googlemap_obj("another-map", 37.4419, -122.1419,
136+
markers=[(37.4419, -122.1419), (37.4300, -122.1400)]) %} {{map.html}}
137+
{{map.js}} {% endwith %}
138+
139+
<h2>First map generated in view</h2>
140+
{{mymap.html}}
141+
142+
<h2>Second map generated in view</h2>
143+
<h3>Example for different icons in multiple markers with infoboxes</h3>
144+
{{sndmap.html}}
145+
</body>
146+
</html>
147+
```
148+
149+
## Infobox
150+
151+
Here's an example snippet of code:
152+
153+
```python
154+
155+
Map(
156+
identifier="catsmap",
157+
lat=37.4419,
158+
lng=-122.1419,
159+
markers=[
160+
{
161+
'icon': 'http://maps.google.com/mapfiles/ms/icons/green-dot.png',
162+
'lat': 37.4419,
163+
'lng': -122.1419,
164+
'infobox': "<img src='cat1.jpg' />"
165+
},
166+
{
167+
'icon': 'http://maps.google.com/mapfiles/ms/icons/blue-dot.png',
168+
'lat': 37.4300,
169+
'lng': -122.1400,
170+
'infobox': "<img src='cat2.jpg' />"
171+
},
172+
{
173+
'icon': 'http://maps.google.com/mapfiles/ms/icons/yellow-dot.png',
174+
'lat': 37.4500,
175+
'lng': -122.1350,
176+
'infobox': "<img src='cat3.jpg' />"
177+
}
178+
]
179+
)
180+
181+
```
182+
183+
Which results in something like the following map:
184+
<img width="1439" alt="screen shot 2015-07-29 at 2 41 52 pm" src="https://cloud.githubusercontent.com/assets/8108300/8969650/13b0de7a-3602-11e5-9ed0-9f328ac9253f.png">
185+
186+
## Fit all markers within bounds
187+
188+
Allow users to easily fit all markers within view on page load
189+
190+
### Without bounds
191+
192+
```python
193+
194+
@app.route('/map-unbounded/')
195+
def map_unbounded():
196+
"""Create map with markers out of bounds."""
197+
locations = [] # long list of coordinates
198+
map = Map(
199+
lat=locations[0].latitude,
200+
lng=locations[0].longitude,
201+
markers=[(loc.latitude, loc.longitude) for loc in locations]
202+
)
203+
return render_template('map.html', map=map)
204+
205+
```
206+
207+
![image](https://user-images.githubusercontent.com/14223309/29294427-24a8d4e0-8104-11e7-967b-0c55c20d0f7c.png)
208+
209+
### With bounds
210+
211+
```python
212+
213+
@app.route('/map-bounded/')
214+
def map_bounded():
215+
"""Create map with all markers within bounds."""
216+
locations = [] # long list of coordinates
217+
map = Map(
218+
lat=locations[0].latitude,
219+
lng=locations[0].longitude,
220+
markers=[(loc.latitude, loc.longitude) for loc in locations],
221+
fit_markers_to_bounds = True
222+
)
223+
return render_template('map.html', map=map)
224+
225+
```
226+
227+
![image](https://user-images.githubusercontent.com/14223309/29294483-6ac3e532-8104-11e7-988c-5c19d700fe5b.png)
228+
229+
## Geocoding and Reverse Geocoding
230+
231+
```python
232+
from flask_googlemaps import get_address, get_coordinates
233+
API_KEY = 'YOUR API KEY'
234+
235+
#Reverse Geocoding: getting detailed address from coordinates of a location
236+
print(get_address(API_KEY,22.4761596,88.4149326))
237+
#output: {'zip': '700150', 'country': 'India', 'state': 'West Bengal', 'city': 'Kolkata', 'locality': 'Kolkata', 'road': 'Techno City', 'formatted_address': 'Sirin Rd, Mauza Ranabhutia, Techno City, Kolkata, West Bengal 700150, India'}
238+
239+
240+
#Geocoding: getting coordinates from address text
241+
print(get_coordinates(API_KEY,'Netaji Subhash Engineering College Kolkata'))
242+
#output: {'lat': 22.4761596, 'lng': 88.4149326}
243+
```
244+
245+
## Run the example app
246+
247+
```bash
248+
$ git clone https://github.com/flask-extensions/Flask-GoogleMaps
249+
$ cd Flask-GoogleMaps/
250+
```
251+
252+
If you have Poetry
253+
254+
```bash
255+
$ poetry install
256+
```
257+
258+
without poetry
259+
260+
```bash
261+
$ pip install --upgrade pip
262+
$ pip install -e .
263+
$ pip install -r requirements.txt
264+
```
265+
266+
Run it.
267+
268+
```bash
269+
$ FLASK_GOOGLEMAPS_KEY="YourKeyHERE" FLASK_APP=examples/example.py flask run
270+
running on localhost:5000 .....
271+
```
272+
273+
Access: http://localhost:5000/ and http://localhost:5000/fullmap
274+
275+
# Contribute with the Google Maps API
276+
277+
Please see this page [developers.google.com/maps/documentation/javascript/tutorial](https://developers.google.com/maps/documentation/javascript/tutorial) and contribute!

0 commit comments

Comments
 (0)