Skip to content

Commit

Permalink
Update readme
Browse files Browse the repository at this point in the history
  • Loading branch information
@ansis
ansis committed Jul 26, 2012
1 parent 0f17651 commit 82f994b
Showing 1 changed file with 62 additions and 85 deletions.
147 changes: 62 additions & 85 deletions readme.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,121 +10,98 @@ To build a project based on this template, fork this repository, edit the html c

To make your custom base map, [sign up for MapBox](http://mapbox.com/plans/) and [create a map](http://mapbox.com/hosting/creating/).


## Using this template

Edit the content by adjusting, removing, or adding to `index.html`. This is the main markup document with the content and layout for the map-site.

Adjust the design by editing the `style.css` file and adding any additional supporting structure to `index.html`.
Edit the content by adjusting, removing, or adding to `index.html`. This is
the main markup document with the content and layout for the map-site.

Set the map features by writing a configuration script at the bottom of `index.html`.
Adjust the design by editing the `style.css` file and adding any additional
supporting structure to `index.html`.

Set the map features by writing a configuration script at the bottom of `index.html`.

## HTML layout

The html markup for the template is in `index.html`. It's a simple html page layout. Generally, you'll want to change the content elements like `title`, `h1`, `img#logo` and `div#about`.
The html markup for the template is in `index.html`. It's a simple HTML5 page layout. Generally, there are three things to change in this document:

1. Content elements like the `title`, `h1`, and `div#about` elements
2. Add new container elements for features like maps, layer switchers, and geocoders
3. Layout structure, as controlled by the `class` attribute on the `body` element

## CSS styles

Most of the hard work on a map site build is template design implemented through CSS. This template by default is simple and clean so you can modify or replace it. This design and be completely overridden by applying new CSS styles or changing the exisiting rules in `style.css`.
There are three layout classes that can be applied to the `body` element:

CSS rules are set in two files:
- `right` A full screen map with a header and right content sidebar (default)
- `left` A similar full screen map with a centered header and left content sidebar
- `hero` An inline map hero with a header and full-width, scrollable content section

- `style.css` contains all the layout and typographic styles as well as some overridden styles for map controls, and a [reset stylesheet](http://meyerweb.com/eric/tools/css/reset/). Implement your design by editing this file.
- `map.css` holds the default map styles from tiles.mapbox.com embeds.
## CSS styles

Most of the hard work on a microsite build is template design implemented through CSS. This template by default is simple and clean, and it's based on the tiles.mapbox.com full map view. This design and be completely overridden by applying new CSS styles. `style.css` contains all the layout and typographic styles as well as some overridden styles for map controls, as well as a [reset stylesheet](http://meyerweb.com/eric/tools/css/reset/). Implement your design by editing this file.

## Javascript interaction

All of the external javascript libraries to make the map interactive and connect it to MapBox are stored in the `ext` directory. For this template, we're using [Modest Maps](http://modestmaps.com/) and [Wax](http://mapbox.com/wax) to make the map interactive, [Easey](https://github.com/mapbox/easey) for smooth aninmated panning and zooming, and [MMG](http://mapbox.com/mmg/) for adding markers to the map based on [geojson](http://www.geojson.org/)-formatted data.
The map is configured in `script.js` and takes advantage of many [MapBox Javascript API](http://mapbox.com/developers/mapbox.js/)
features - so the documentation for the MapBox Javascript API applies to every part
of this site.

Additional integration is added with `mapbox.jquery.js`, which automatically binds
links that control the map - see the navigation links for examples.

An internal javascript library, `script.js`, abstracts common map settings, and `tweetRace.js` is the library we put together to take two terms and compare their results in Twitter searches.
All the following controls require that the id of the element containing the map be specified using the `data-control` attribute. In this case it is `data-control="map"`. This attribute may be placed in any of the controls' parent elements.

We're also using [jQuery](http://jquery.com/) for DOM manipulation and handling events, and [Underscore.js](http://documentcloud.github.com/underscore/) for data processing.
### Address search

### Map configuration
To search for an address, we need a geocoding service that converts a plain-text
address query into a geographic location. This template uses [MapQuest Open](http://open.mapquest.com/)
search, which is free to use for noncommercial and commercial applications alike. If you'd
like to use another service, edit the `geocode` function in `script.js`.

The map is added to the `<div>` container in `index.html` with `id="map"`. Styles to lay out the map container come from `class="map"`.
To add an address search to your page, build a simple html form to gather user input:

```html
<div id="map" class="map"></div>
<div data-control="geocode" id="search">
<form class="geocode">
<input placeholder="Search for an address" type="text">
<input type="submit" />
<div id="geocode-error"></div>
</form>
</div>
```

At the bottom of the `index.html` document, we set up the map. The `id` of the container is the first argument (`'map'`), and an object of options is the second argument. The third arugement is the name of an optional callback function, which we use to start the `tweetRace.js` main function, once the map is loaded.

The only required option is `api`, and it should contain the API URL from MapBox. After you create a new map through your MapBox account, click `embed` on the `info` tab and copy the API URL.
By specifying `data-control="gecode"` on the `div` containing your `form`,
`mapbox.jquery.geocoder.js` will bind a function that handles address searches and repositions
the map accordingly. If the geocoder has a successful response to a search, it
will center the map and zoom it to show the bounding box extent of that response. If
the bounding box is small enough to zoom the map to its maximum zoom, the geocoder
will also place a pin with a star over the response's exact location.

```js
var main = Map('map', {
api: 'http://a.tiles.mapbox.com/v3/mapbox.map-hv50mbs9.jsonp'
});
```

The map options object can take several options:

- `api` The MapBox API URL from the `embed` button on your map:
![](http://mapbox.com/images/hosting/embedding-4.png)
- `center` An object of `{ lat: ##, lon: ##, zoom: ## }` that defines the map's initial view. If not is provided, the default center set from MapBox will be used
- `zoomRange` An array of `[##, ##]` where the first element is the minimum zoom level and the second is the max
- `features` An array of additional features for the map

The features object may contain any of the following:

- `zoomwheel` Use the scroll wheel on the mouse to zoom the map
- `tooltips` or `movetips` For layers with interactive overlays, display fixed `tooltips` or `movetips`, which are overlays the follow the cursor
- `zoombox` Allow uses to zoom to a bounding box by holding the shift key and dragging over the map
- `zoompan` Show zoom controls on the map
- `legend` Show a legend on the map. Legends from multiple layers will stack on top of each other
- `share` Show a share button on the map with Twitter, Facebook links and an embed code for the map. The embedded view of the map will add a `class="embed"` to the `<body>` element of the page for easy theming. For instance, by default the embed layout is a full screen map with the layer switcher over it on the left. The header and content are hidden.
- `bwdetect` Automatically detect low bandwidth contections and decrease the quality of the map images to accomodate

A map with all the options and a callback function would look like this:

```js
var main = Map('map', {
api: 'http://a.tiles.mapbox.com/v3/mapbox.map-hv50mbs9.jsonp',
center: {
lat: 38.8850033656251,
lon: -77.01439615889109,
zoom: 14
},
zoomRange: [0, 15],
features: [
'zoomwheel',
'tooltips', // or 'movetips'
'zoombox',
'zoompan',
'legend',
'share',
'bwdetect'
]
}, tweetRace.start);
```

### tweetRace.js
### Easing links
To link to a geographic location add at least one of the following data attributes:

Live tweets are pulled in through a recursive function in `tweetRace.js` that fetches the tweets from Twitter's API and processes them to be mapped. Initialize the tweet race with the following:
- `data-lat`: The latitude of the location.
- `data-lon`: The longitude of the location.
- `data-zoom`: The zoom level.

```js
var tweets = [
'work', // First term
'play', // Second term
'39,-98,1500mi' // search location and radius
];
```html
<a data-lat="39" data-lon"77" data-zoom="10" href="#">
```

`tweetRace.js` supports searching for two terms and mapping the results. The sidebar lists the names of the terms and has a class for each term applied to it to make it easy to style custom background images, like we've done for work and play. Add classes for your search terms to your CSS to style this section.
If you specify any of these, the link will be automatically bound to the map.

The internals of `tweetRace.js` mostly deal with parsing the Twitter API to filter for tweets with longitude and latitude coordinates. See the [inline documentation] for more information.

### Layer Switcher
Use `data-control="switcher"` to bind all links in child elements to the layer switcher function. Specify the layer by setting the `href` attribute of anchors to the layer's name. There are two optional layer attributes:

## Further Reading
- `data-group`: Specifies the group, defaulting to 0. Only one layer per group can be enabled at any time.
- `data-toggle="true"`: Allow a layer to be toggled off.

```html
<div data-control="switcher">
<a data-group="0" href="#streets">Streets</a>
<a data-group="1" href="#construction">Construction projects</a>
<a data-group="1" href="#building">Building permits</a>
</div>
```

* [MapBox API](http://mapbox.com/hosting/api/)
* [MapBox Wax](http://mapbox.com/wax/)
* [MapBox MMG](http://mapbox.com/mmg/)
* [MapBox Easey](http://mapbox.com/easey/)
* [Modest Maps](http://modestmaps.com/)
* [jQuery](http://jquery.com/)
* [Underscore.js](http://documentcloud.github.com/underscore/)
Easing links can be used together with the layer switcher.

0 comments on commit 82f994b

Please sign in to comment.