The Standalone Satellite

Getting the Satellite

You fetch the satellite from its location in the SourceForge Project (Downloads a zip file).

This will download a zip file with a directory called "satellite_server" in it. That directory, in turn has a couple of files and a couple of directories in it. These should be kept together. It’s a good idea to keep them in the "satellite_server" directory (You can rename it, but don’t rename the contained directories). The "c_comdef_mainpage.txt.php" file is not necessary. Unless you will be doing your own PDF files (the server can usually generate them), then you won’t need the "pdf_generator" directory, either. The "index.php" file is the main file. You can modify it directly, or use it as an example for your own work. Remember that, if you move it out of the "satellite_server" directory, you will probably need to change the pathnames.

How to Use the Standalone Satellite

Before you start, download the source code for the standalone satellite.

The next thing to do is to set up your parameters in the standalone/config.inc file.

You will need to point to whatever root server is being used. You get this URL from the root server administrator. The URL is displayed on the front page of the root server. If you go to the root server’s main page, you will see the URL displayed along the top of the screen.

Next, you’ll need to get a Google Maps API Key for your domain, and replace the default one with that (The trick is to get one for the top-level domain: bmlt.magshare.org/blog, as opposed to bmlt.magshare.org/blog/satellite_server/).

$root_server_root = "Replace This With the URI to Your BMLT Root Server.";
$gkey_my = "Replace This With Your Google Maps API Key.";
$support_old_browsers = false;
$bmlt_initial_view = '';
$preset_service_bodies = array ();
$map_center_latitude = 41.5;
$map_center_longitude = -73.5;
$map_zoom = 8;
$lang_enum = null;
$use_local_pdf_generator = false;

There is some debug stuff in there that you can safely delete.

Here are the various settings in the file:

$support_old_browsers

If you set this to true, then the interactive search will reload, which will detect whether or not the visitor’s browser can handle JavaScript and AJAX. If they cannot, then a simpler set of code is given the browser. This makes page loads slower.

$bmlt_initial_view

This determines what the initial view of the interactive search will be. The values are 'map', 'text', 'advanced', 'advanced_map', 'advanced_text' or nothing. If nothing (''), then the root server will decide what to display. The same goes for just 'advanced'.

$preset_service_bodies

This is a bit technical. You make this an array of integers, with each integer being the BMLT ID of a Service Body (You would get these from the Server Administrator). If these are provided, then the Advanced Search will have these Service Bodies “pre-checked.” This can be confusing to users, as they may not understand why only certain meetings are being returned from their searches.

$map_center_latitude, $map_center_longitude and $map_zoom

These are the Google Maps longitude, latitude and zoom for the center of the map. This tool can help you to determine these values.

$lang_enum

If the root server allows different languages, you can specify the preferred language for your satellite here.

$use_local_pdf_generator

This is only necessary if the root server does not provide this service, or if you will be customizing your own PDF generators. If this is false, you will not need the pdf_generator directory.

The Structure of the Code

The standalone satellite server consists of one PHP class: BMLT_Satellite. This is instantiated by your code, and you simply make a couple of calls to it in order to generate the BMLT code you need for your site.

For an example of this file, look at the standalone/index.php file. It will show exactly how you implement this code.

In order to start, you should do an include() or require() of the BMLT_Satellite.class.php file at the beginning of your file (before any HTML), like so:

<?php
	include ( dirname ( __FILE__ ).'/standalone/BMLT_Satellite.class.php' );

	if ( !(($bmlt_instance = BMLT_Satellite::MakeBMLT()) instanceof BMLT_Satellite) )
		{
		die ( 'The BMLT object could not be created' );
		}
?>

The “dirname ( __FILE__ )” simply tells PHP to start off where the file is, and that the path should be relative from there. It is sort of optional, but it’s usually a good idea to do that. It will allow the file to be included into other files.

The BMLT_Satellite::MakeBMLT() function is a “factory” function. It ensures that there is only ever one instance of the class, which is important.

The $bmlt_instance variable will now contain your connection to the BMLT root server.

After that, start building the Web page. Put the standard DOCTYPE stuff in there, and start the <head> section.

Now, the BMLT will need to put some stuff in the <head> section of the page, so we run a quick BMLT_Satellite::Execute(‘head’) call inside the head, like so:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
	"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
	<head>
		<meta http-equiv="X-UA-Compatible" content="IE=EmulateIE7" />
		<title>Demo of the BMLT</title>
		<?php echo ( $bmlt_instance->Execute ( 'head' ) ); ?>
	</head>

An important note is that “<meta http-equiv=”X-UA-Compatible” content=”IE=EmulateIE7″ />”. This meta element is necessary, because the new Microsoft Internet Explorer 8 browser doesn’t behave particularly well, unless it is sternly spoken to by that meta tag. Just take our word for it. Failing that, why don’t you take Microsoft’s word for it?

After that, you’ll need to insert one more BMLT_Satellite::Execute() call in the <body>, and that’s it!

In this call to BMLT_Satellite::Execute(), you don’t specify any parameters. The class knows what to do.

	<body>
		<?php echo ( $bmlt_instance->Execute ( ) ); ?>
	</body>
</html>

Here is a complete, minimalist implementation of the BMLT:

<?php
	include ( dirname ( __FILE__ ).'/standalone/BMLT_Satellite.class.php' );

	if ( !(($bmlt_instance = BMLT_Satellite::MakeBMLT()) instanceof BMLT_Satellite) )
		{
		die ( 'The BMLT object could not be created' );
		}
?><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
	"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
	<head>
		<meta http-equiv="X-UA-Compatible" content="IE=EmulateIE7" />
		<title>Demo of the BMLT</title>
		<?php echo ( $bmlt_instance->Execute ( 'head' ) ); ?>
	</head>
	<body>
		<?php echo ( $bmlt_instance->Execute ( ) ); ?>
	</body>
</html>

What could be simpler?

In the example file, you will see the following CSS in the <head> section:

<style type="text/css">
	*{ margin: 0; padding: 0 }
	body, html{ width:100%; height:100% }
</style>

This is there to ensure that the map fills the entire screen in all browsers. It’s required for Internet Explorer 6.

So, let’s add that to our minimalist file:

<?php
	include ( dirname ( __FILE__ ).'/standalone/BMLT_Satellite.class.php' );

	if ( !(($bmlt_instance = BMLT_Satellite::MakeBMLT()) instanceof BMLT_Satellite) )
		{
		die ( 'The BMLT object could not be created' );
		}
?><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
	"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
	<head>
		<meta http-equiv="X-UA-Compatible" content="IE=EmulateIE7" />
		<title>Demo of the BMLT</title>
		<?php echo ( $bmlt_instance->Execute ( 'head' ) ); ?>
		<style type="text/css">
			*{ margin: 0; padding: 0 }
			body, html{ width:100%; height:100% }
		</style>
	</head>
	<body>
		<?php echo ( $bmlt_instance->Execute ( ) ); ?>
	</body>
</html>

That’s all you need to do to give your Groups the best meeting list possible!

Preventing the Map Search From Taking Over the Entire Screen

The results of a map search, by default, fill the entire window. In many cases, this is not a desired outcome. The solution to this, is to add a bit of CSS to your <head> section, like so:

<style type="text/css">
*{ margin: 0; padding: 0 }
body, html{ width:100%; height:100% }
.c_comdef_search_results_map_container_div
{
   position: relative; /* This stops the display from covering everything else */
   height:640px;       /* Without the absolute position, the display needs a specific height. */
                       /* You can use any value you like, here. Width will default to 100%. */
}
</style>

IMPORTANT CAVEAT!

If you wish to use the local PDF generator (set $use_local_pdf_generator to true), then you need to keep the standalone and pdf_generator directories on the same level as the main file that you use as your satellite file. It is possible to move them around, but that requires monkeying with the code, and you probably want to avoid that. Just plonk the two directories on the same level as your main file, and it should be OK.