Embedding Streetbrew

From GeoMonkey Wiki
Jump to: navigation, search

General disclaimer: The instructions on this page assume familiarity with HTML, CSS, JavaScript and your development or content management system. We assume no responsibility for misconfiguration, incompatibility or other negative side effects experienced during the implementation process. We recommend that you try to embed your Streetbrew map in a temporary, non-critical workspace prior to deploying it to your live system.

Contents

Primary method

Follow these steps with respect to a page you have selected on your web site. In order to embed Streetbrew without major conflicts, please observe the following:

  • We use Google Maps API V3. If the page where you have chosen to embed Streetbrew uses Google Maps API V2, conflicts will likely result.
  • We rely on the Prototype JavaScript framework, which may conflict with similar JavaScript frameworks (such as jQuery). If the web page where you have chosen to embed Streetbrew relies on jQuery or similar, we recommend that you instead embed Streetbrew in an empty sandbox page, and include that page on your intended page using a simple IFRAME. For more information, see the sandbox method below.
  • We make heavy use of CSS classes. The vast majority of our class names are prefixed with sb- or mwu- (e.g. sb-dialog or mwu-prompt) to avoid styling conflicts. Reuse of any of our required class names may result in display issues. We do not recommend that you attempt to override any CSS styling used by the Streetbrew widgets.

Step 1: Include Google Maps API and Streetbrew embed libraries

  • Streetbrew requires Google Maps API V3 (the official version of the Google Maps API). Include this script tag, inserted either inside of the <HEAD> tag of your web page, or just before the closing </BODY> tag.
  • Streetbrew widgets rely on our primary JavaScript library. It is minified to optimize your page's loading time. Please note that this JavaScript library includes a recent copy of the Prototype JavaScript framework (see above for concerns). Include this script tag, inserted immediately below the Google Maps API script tag.

Your script tags should appear as follows:

<script type="text/javascript" src="http://maps.google.com/maps/api/js?sensor=false"></script>
<script type="text/javascript"
    src="http://www.streetbrew.com/r/serve/jsx/streetbrew/script.js"></script>

Step 2: Include Streetbrew stylesheet

Our widgets require our CSS stylesheet. The style sheet is minified to optimize your page's loading time. Include this stylesheet link in the <HEAD> tag of your web page:

<link rel="stylesheet" type="text/css" href="http://www.streetbrew.com/r/serve/c/lY/stylesheet.css" />

Step 3: Add one or more containers for the Streetbrew widgets

The placement of the Streetbrew widgets is entirely at your discretion. For each instance of the Streetbrew map and associated smart-phone widget on your web page, include the following HTML:

<div id="streetbrew_widget"></div>

The identifier streetbrew_widget can be replaced with any name that is unique to your page. Note that if you wish to embed Streetbrew multiple times, you must give each <DIV> tag its own identifier, such as streetbrew_widget1 and streetbrew_widget2.

Also note that you must style this HTML element to fit the look and feel of your page, either using a CSS class or an in-line STYLE attribute. For example:

<style type="text/css">
  div#streetbrew_widget {
    width: 640px;
    height: 540px;
  }
</style>

Finally, be aware that the smart-phone widget will likely appear outside of the space reserved by this HTML element, so you may need to apply some extra spacing to prevent it from occluding your surrounding content. We recommend that you experiment with different styling options to find the look that best fits your web page.

Step 4: Execute JavaScript when the page loads

There are several ways to go about executing JavaScript when a web page loads, not all of which will be explained here. For convenience, the Streetbrew embed library provides a simple method to execute JavaScript when the page loads. Include the following script immediately below the Google Maps API and Streetbrew embed scripts that you incorporated previously:

<script type="text/javascript">
  function startStreetbrew() {
    new streetbrew.embed.Embed(
      'streetbrew_widget',
      {   //options
          offsetLeft: 0,
          offsetTop: 0
      }
    );    
  }
  mapwithus.util.addOnloadListener(function() {
    mapwithus.xd.setXD(true);
    mapwithus.xd.setBaseURL("http://www.streetbrew.com");
    mapwithus.xd.setBaseContext("/brew");
    streetbrew.embed.init(startStreetbrew);
  });
</script>

Pay careful attention to the startStreetbrew function defined above, as you will likely need to modify its contents to customize the Streetbrew widgets to meet your requirements. When embedding one or more instances of the Streetbrew map and smart-phone widgets on a given web page, you must execute the following JavaScript call in the body of the startStreetbrew function for each embedded Streetbrew instance:

new streetbrew.embed.Embed(container, options)

Here, container refers to the identifier that you applied to your HTML element in the previous step, such as 'streetbrew_widget' in the example above. Additionally, options is a JavaScript object in which you can specify any number of additional parameters, as defined below:

Name Type Default Example Description
offsetLeft Integer 0 251 Shifts the smart-phone widget rightward from its default position. (Negative values shift the widget rightward.)
offsetTop Integer 0 -77 Shifts the smart-phone widget downward from its default position. (Negative values shift the widget upward.)
zoom Integer 10 12 Sets the zoom level for the map. The maximum zoom level varies depending on map type, but the maximum value at this time is 20. If a location is passed in and no zoom level is specified, the map will automatically adjust its zoom level to try to fit the contents of the map as best it can.
markerIcons Array [ ] [ 'checkin', 'posts', 'photos' ] An array of strings from this set: 'checkin', 'posts', 'photos', 'events', 'promos', 'fresh', 'hot'. The chosen icon types will appear in markers on the map if those walls contain the indicated content.
userLabels String None 'MyUsername' The name of the user whose labels should appear in the smart-phone widget. Labels are used for custom filtering of content. Typically this will be your username.
location String None 'Portland, OR' A description of the location on which your Streetbrew map should initially be centered. This may be a street address, city, state, country, zip code, or latitude/longitude pair (e.g. '45.6618, -112.5617').
publisher String None 'MyUsername' The name of a user with publisher privileges who should receive credit for wall purchases initiated via this widget. If you don't know what a publisher is then this option likely is not for you.

Here is an example that would set up two separate instances of the embedded Streetbrew widgets:

  function startStreetbrew() {
    new streetbrew.embed.Embed(
      'streetbrew_widget1',
      {   //options
          offsetLeft: 251,
          offsetTop: -77,
          markerIcons: [ 'events' ],
          userLabels: 'quailish'
      }
    );
    new streetbrew.embed.Embed(
      'streetbrew_widget2',
      {   //options
          markerIcons: [ 'photos', 'hot', 'fresh' ],
          location: '98662',
          userLabels: 'dinjas',
          publisher: 'dinjas'
      }
    );
  }

Putting it all together

When all is said and done, a simple web page embedding the Streetbrew widgets may look something like this:

<html>

  <head>

    <title>Streetbrew Embedded Demo</title>

    <link rel="stylesheet" type="text/css"
        href="http://www.streetbrew.com/r/serve/c/lY/stylesheet.css" />

    <style type="text/css">
      div#streetbrew_widget {
        margin: 20px;
        height: 560px;
      }
    </style>

  </head>

  <body>

    <div id="streetbrew_widget"></div>

    <script type="text/javascript"
        src="http://maps.google.com/maps/api/js?sensor=false"></script>
    <script type="text/javascript"
        src="http://www.streetbrew.com/r/serve/jsx/streetbrew/script.js"></script>

    <script type="text/javascript">
      function startStreetbrew() {
        new streetbrew.embed.Embed(
          'streetbrew_widget',
          {   //options
              offsetLeft: 251,
              offsetTop: -77,
              location: '98662',
              markerIcons: [ 'events' ],
              userLabels: 'quailish',
              publisher: 'quailish'
          }
        );    
      }
      mapwithus.util.addOnloadListener(function() {
        mapwithus.xd.setXD(true);
        mapwithus.xd.setBaseURL("http://www.streetbrew.com");
        mapwithus.xd.setBaseContext("/brew");
        streetbrew.embed.init(startStreetbrew);
      });
    </script>
    
  </body>

</html>

Interactive demo

An interactive demo of our Streetbrew embedded widgets using the primary method is available here: Streetbrew Demo 1. (You may borrow from the page's source code.)

Sandbox method

The sandbox method of embedding Streetbrew widgets is nearly identical to the primary method outlined above. Rather than embedding the Streetbrew widgets directly onto a page on your web site, however, you should instead create a new, empty page on which to work so as not to interfere with the operation of your existing web site.

For example, you might create a new web page located at the relative path /widgets/streetbrew_widget1.html on your web site. On this page, follow the steps outlined in the primary method above to populate the empty page with your customized Streetbrew widget.

Next, edit the real web page on which you would like your visitors to see the embedded Streetbrew widgets. On this page, insert a simple IFRAME anywhere in the body of the page. For example:

<iframe src="/widgets/streetbrew_widget1.html" width="640" height"540"
    frameborder="0" scrolling="no" style="border:none;"></iframe>

Note that your IFRAME's width and height should be sufficient to completely display the embedded Streetbrew widgets without cutting off any of their edges. You will also likely want to customize the background color of /widgets/streetbrew_widget1.html to match the background color of the page on which the IFRAME is displayed.

Interactive demo

An interactive demo of our Streetbrew embedded widgets using the sandbox method is available here: Streetbrew Demo 2. (You may borrow from the pages' source code.)

Caveats

While safer in terms of reducing potential conflicts, there are known issues with employing the sandbox method rather than the primary method:

  • The Streetbrew user login dialog requires that the IFRAME be at least 628 pixels wide. If the IFRAME is narrower than 628 pixels, parts of this and other dialogs may be hidden from view and adversely affect your visitors' experience.
  • When viewing pictures that have been uploaded to walls, the images will only fill the IFRAME sandbox rather than your visitor's entire browser window. To this end, we advise that you allot as much space as possible to the IFRAME.