The Fast Mobile Satellite is actually a set of PHP and JavaScript files that you integrate into your own site. It does not require that your site be a Content Management System. In fact, it is designed to be a standalone site, delivering full pages, in either XHTML or WML (for old phones that can’t handle full XHTML).
NOTE
If you have installed one of the CMS plugins, version 2.1.9 or greater, then you don’t need this. It is built into the plugin.
What the Satellite Does
It queries the phone, and, using a series of “tricks,” presents the best possible interface for the device. The best possible interface is a “find meetings around here” functionality, where the site uses information from the phone’s GPS, and presents an interactive Google Maps screen with nearby meetings. You can also enter an address (the client uses the Google Geocode API, so you can use extremely casual address information –such as only a zip code, town name or landmark). This is not a comprehensive search. A premium is placed on simplicity and speed. It is a convenience, and care has been taken to make it as convenient as possible.
A post describing the usage of the client is available here, on the Greater new York Region Web site. The GNYR is the “home field” for the BMLT, and is used to prototype and test many features. It boasts the latest stable versions of the root server and select satellites. The GNYR implementation of this satellite is available at this URI.
Under the Hood
The satellite is the first implementation of the BMLT REST-Based Satellite Driver that we developed earlier. It only uses this class for the “less-interactive” aspects of the satellite. The “full monty” implementation, where the user gets a “find meetings near me” and an interactive map, don’t actually use the class, relying instead on good old JavaScript and the JSON REST response. There is some in-depth technical documentation here. This is code-level documentation that is generated automatically by a utility called Doxygen. It will give you more information than you want to know.
Basically, the satelitte is not as “plug and play” as the three CMS plugins, but is a bit less technical to implement than the standalone satellite.
The Structure of the Satellite
The code for the satellite can be viewed in the SourceForge repository for the project. There are 18 files (as of version 1.0.1); 7 of which are images.
First, the source code files:
- bmlt_satellite_controller.class.php
- This is the BMLT Satellite Driver that we developed earlier. It handles communications with the root server.
- css_stripper.php
- js_stripper.php
- These two files are “optimizers” for the CSS and JavaScript files. They strip out comments and extra whitespace, and compress the files.
- fast_mobile_lookup.css
- custom.css
- These two files are the stylesheets for the satellite. They are only used for XHTML delivery. The custom.css file is one that you can edit to add your own styling. Leave the other one alone.
- fast_mobile_lookup.config.php
- This is the configuration file for the satellite. We’ll go into detail on this one soon.
- fast_mobile_lookup.js
- This is the JavaScript file that handles almost all the work for the “find meetings near me” functionality.
- fast_mobile_lookup.php
- This is the main implementation file for the satellite.
- index.php
- This is simply a redirector file. It loads the fast_mobile_lookup.php file.
Next, the images:
- images/closebigger.gif
- This is used as the “close box” for the popup window in map view.
- images/NACenterMarker.png
- images/NACenterMarkerS.png
- images/NAMarker.png
- images/NAMarkerG.png
- images/NAMarkerS.png
- These define the markers in map view.
- images/shortcut.png
- This is the default shortcut/bookmark icon.
- images/throbber.gif
- This is the default “AJAX throbber.”
The satellite map implementation uses the Google Maps API V3, which has been designed to target mobile devices. Even so, it is not able to support all mobile devices, so you may often get the “fallback” implementation, which offers an address entry and a list response.
Prerequisites
The satellite requires that the root server be version 1.8.11 or greater. In order to upgrade your root server, follow these instructions.
This satellite has the same server requirements as the other BMLT satellites.
Getting the Satellite
The stable version can be fetched via a TARBall of the stable source code (Downloads a GNU TARBall). This code comes in a “ready to implement” package, albeit very “generic.” You may want to customize the satellite for your particular implementation.
Configuring the Satellite
For the most part, the only two files that you need to worry about are the custom.css and the fast_mobile_lookup.config.php files. Remember that the satellite is designed to operate as a standalone site, so it is not meant to integrate into a CMS. If you are running a CMS, you will want to offer a link (or automatic redirection) to the fast mobile satellite. It is not designed to be integrated into a CMS (but you could probably integrate it into your theme -that is beyond the scope of this page). The instructions below will assume that this is the case.
No Need for a Google Maps API Key!
Because this satellite uses the Google Maps API V3, the need for a Google Maps API Key is gone. API V3 no longer requires an API key.
Editing the Config File
The place to start is the fast_mobile_lookup.config.php file. You change a couple of defines to suit your implementation. At the very least, you can change just the root server, and have a fully-functional satellite. For example, when we implemented the Greater new York Region Satellite, we changed the root server like so:
define ('_REMOTE_URI', 'http://bmlt.magshare.net/stable/main_server' );
was changed to:
define ('_REMOTE_URI', 'http://bmlt.newyorkna.org/main_server' );
At that point, we had a fully-functional mobile satellite that used our local database. However, we wanted to “theme” the satellite to “mesh” with our site a bit more, so we started with the two optional image links that are available in the fast_mobile_lookup.config.php file, so we changed:
define ( '_THROBBER_LOC_', 'images/throbber.gif' ); define ( '_SHORTCUT_LOC_', 'images/shortcut.png' );
to:
define ( '_THROBBER_LOC_', 'http://cfd.newyorkna.org/themes/gnyr_v1/images/throbber.gif' ); define ( '_SHORTCUT_LOC_', 'http://cfd.newyorkna.org/themes/gnyr_v1/images/shortcut.png' );
which are the same images that we use for the regular GNYR Web site. The rest of our customization was done to the custom.css file.
Editing the Custom CSS File
The default styling gives a white background, the default AJAX throbber, grey borders and sans-serif font. These can all be overridden in the custom.css file. We will not show you the original file (follow the links to see that), but we will show you the modified one for the GNYR implementation. Remember that this only applies to the XHTML version that is sent to phones configured to accept styles. The WML deck is completely unstyled.
/****************************************************************************************//**
* \file fast_mobile_lookup.css *
* \brief Contains the CSS to apply to the XHTML version of the satellite. *
* \version 1.0.5 *
* \license Public Domain -No restrictions at all. *
********************************************************************************************/
/* Dark blue background color */
body
{
background-color: #006;
font-family:Helvetica,Arial,San-Serif;
}
/* We use the GNYR throbber, at 80px square, and a 2px margin. We use a parchment color background. */
.throbber_div
{
-moz-border-radius:5px;
-webkit-border-radius:5px;
width:84px;
height:84px;
margin-left:-42px;
margin-top:-42px;
background-color:#006;
border:1px solid #f30;
}
.throbber_div img
{
width:80px;
height:80px;
margin:2px;
}
/* We use the Mozilla rounded corners, and a thick red border, and parchment background. */
#search_form_body div.search_div,
.multi_meeting_div
{
-moz-border-radius:7px;
-webkit-border-radius:7px;
border:3px solid #f30;
background-color: #ffc;
padding:8px;
}
/* We do the same for the info window fieldset, except the border is thinner. */
.multi_day_info_div fieldset
{
-moz-border-radius:7px;
-webkit-border-radius:7px;
margin-bottom: 4px;
border:1px solid #f30;
}
/* The info window will be surrounded by a red border with Mozilla rounding, and parchment background. */
div.infoWindow_Wrapper_div
{
-moz-border-radius:5px;
-webkit-border-radius:5px;
background-color:#ffc;
border:2px solid #f30;
padding:4px;
margin:0;
overflow:auto;
}
/* This is used to divide multiple meetings in the listing. */
.meeting_divider_hr
{
border:none;
border-bottom:1px solid #f30;
}
/* This is for the text input in the standard address entry form.
We want a white background, thin red border, and Mozilla rounding. */
input.address_input
{
-moz-border-radius:3px;
-webkit-border-radius:3px;
background-color:white;
border:1px solid #f30;
}
/* These define each link in the form. */
.link_one_line a,
.link_one_line a:visited
{
color: #00c;
text-decoration: underline;
}
/* Make sure that our links behave like the GNYR ones. */
.link_one_line a:hover,
.link_one_line a:focus,
.link_one_line a:active
{
color: #f30;
text-decoration: none;
}
/* These show up better against a blue page. */
.failed_search_h1
{
position:absolute;
top:50%;
left:50%;
margin-top: -2em;
margin-left: -10em;
}
.failed_search_h1,
.failed_search_h1_wml
{
display: block;
width: 20em;
height: 4em;
color:white;
background-color: #006;
}