Version Notes

Just recently EllisLab, the creators of ExpressionEngine, announced the official release date of ExpressionEngine 2.0 as being December 1st, 2009. Please note that this tutorial is written with details specific to versions 1.6.x. Certain details such as file paths and global objects will be changing for version 2.0. While these details will be different the general application and approach to plugin creation for ExpressionEngine will remain the same.

Types of ExpressionEngine Add-Ons

Like most robust management systems available, ExpressionEngine, or “EE”, comes with a number of ways for a developer to add functionality that may not be there by default. Unlike popular systems like WordPress, EE has different names for these add-ons depending on how they interact with your site. There are three primary ways you can add functionality to EE 1.6.x which are Plugins, Extensions and Modules. Plugins primarily deal with modifying your template code and tend to be more of a front-end job. Extensions typically tweak the functionality of the back-end, or Control Panel by tying into “hooks” in the system. Modules tend to be larger in scope, have their own area in the Control Panel and can also be used on the front-end of the EE website. Modules can be full blown apps sitting within EE and utilizing membership, templates, database, etc.

Required Experience

Things it would sure help to know before moving forward:

• How to setup and install ExpressionEngine in a development environment
• Basic understanding of ExpressionEngine’s Control Panel and template parsing
• Basic understanding of PHP and Object Oriented programming
• How to read documentation!

Our Plugin

For this tutorial we are going to create a simple plugin that scans through the data passed to it and wraps certain strings with HTML tags. This is a very simple application of an EE plugin and should show you how easy it is to get started with plugin development. Our plugin will be used to search for and replace acronyms that we use as developers. For the sake of the example we will stick to three: HTML, CSS, and RSS. Let’s call the plugin “Auto Acronym.”

Where Do I Start?

The best place to start with EE Add-On development is the official ExpressionEngine Documentation. Before you dive into developing for ExpressionEngine you should read through their guidelines which, if followed, help keep the system running well. The guidelines cover things like naming conventions, performance and security. I’ll give you a few minutes to read over the ExpressionEngine Add-On Development Guidelines

Okay, now that you’ve read that we can start looking at how we actually create the plugins and what makes up a simple one.

Pieces of the Puzzle

Every plugin requires one class and at least one function. The naming convention is very specific so we need to make sure we do it correctly and carefully. The name of our plugin is Auto Acronym and it comes into play with our file name, class name, and EE tags. The file name takes the name of your plugin and replaces all spaces with underscores while prepending “pi.” to the front. All letters must be lower case. That would make our file name “pi.auto_acronym.php”. All EE plugins go into a single directory located under system/plugins (imagine that).

The class name is similar to the file name with the exception of the first letter being capitalized. This makes our class name “Auto_acronym”. This plugin will only need one function so it will have the same name as the class. These will also be the names we use in our EE plugin tags. Plugin tags always start with “exp:” which is telling the template parser, “Hey! I need some processing over here!”. What follows will be the name of your class all lowercase giving us: “exp:auto_acronym”. The third segment of a plugin tag calls the function within the plugin’s class. In our example we will just be using the one function, the constructor, so we only need the class name. So far here is what we know about our plugin:

Putting it to Code

Let’s see what our code is so far:

<?php

class Auto_acronym
{

   function Auto_acronym()
   {

   }

}

/* End of file pi.auto_acronym.php */
/* Location: ./system/plugins/pi.auto_acronym.php */

For those of you who are familiar with WordPress plugin development, you know that WordPress extracts some data from commented code when displaying details in the Plugin Manager. ExpressionEngine does something similar except with an array within your plugin file. Let’s go ahead and add that to our file above the class and give it the appropriate information.

<?php

$plugin_info       = array(
   'pi_name'        => 'Auto Acronym',
   'pi_version'     => '1.0',
   'pi_author'      => 'Erik Reagan',
   'pi_author_url'  => 'http://erikreagan.com',
   'pi_description' => 'Automatically wraps certain acronyms in the HTML <acronym> tag',
   'pi_usage'       => Auto_acronym::usage()
   );

class Auto_acronym
{

   function Auto_acronym()
   {

   }

}

/* End of file pi.auto_acronym.php */
/* Location: ./system/plugins/pi.auto_acronym.php */

Each of the array keys should be pretty obvious as far as what they are for. The last key, however, is a little different. It’s obviously not just a string like the others. It is used to tell the ExpressionEngine control panel where to find the usage, or simple documentation, for the plugin. Every EE plugin should have some basic docs within the plugin file so that those using the plugin can just view it in the Control Panel and see how to utilize the tags. This is done by adding a function to your plugin class called “usage” which . I like to put the usage function last in my class so let’s go ahead and copy & paste the example from the ExpressionEngine Plugin Docs and remove the content between the ?> and <?php tags since our content will go there.

   // ----------------------------------------
   //  Plugin Usage
   // ----------------------------------------

   // This function describes how the plugin is used.
   //  Make sure and use output buffering

   function usage()
   {
   ob_start();
   ?>

   <?php
   $buffer = ob_get_contents();

   ob_end_clean(); 

   return $buffer;
   }

Our usage does will be written after we complete our plugin. For now let’s just put in some text for testing purposes. Keep in mind that this text will be treated as pre-formatted and all characters are converted into HTML entities; HTML will not work. Let’s look at our plugin in its entirety so far

<?php

$plugin_info       = array(
   'pi_name'        => 'Auto Acronym',
   'pi_version'     => '1.0',
   'pi_author'      => 'Erik Reagan',
   'pi_author_url'  => 'http://erikreagan.com',
   'pi_description' => 'Automatically wraps certain acronyms in the HTML <acronym> tag',
   'pi_usage'       => Auto_acronym::usage()
   );

class Auto_acronym
{

   function Auto_acronym()
   {

   }

   // ----------------------------------------
   //  Plugin Usage
   // ----------------------------------------

   // This function describes how the plugin is used.
   //  Make sure and use output buffering

   function usage()
   {
   ob_start();
   ?>

   This is where our simplified documentation will go

   <?php
   $buffer = ob_get_contents();

   ob_end_clean(); 

   return $buffer;
   }

}

/* End of file pi.auto_acronym.php */
/* Location: ./system/plugins/pi.auto_acronym.php */

Now that we have a bare-bones plugin file we need to save it to our system/plugins directory to make sure it’s being read by the system properly. After saving it you will see it under Admin > Utilities > Plugin Manager. If you click on our new plugin you should see a page like this that contains the information we just added to our plugin

Making it Work

Now that our plugin is being pulled into the ExpressionEngine system properly, we can make it actually do something. Every plugin returns some form of data. This data will always come from a standardized variable that EE will look for called “return_data”. The first thing we want to do is define it before our first function within the class. Then, just for testing purposes, we will use it within our first function to return a simple string.

class Auto_acronym
{

   var $return_data  = "";

   function Auto_acronym()
   {
      $this->return_data = "Just making sure this works";

   }

Now that we have some data being returned we can test it on the front end of our website. I am using a very minimal template for testing purposes right now but you can use this within any of your ExpressionEngine templates. If you recall from earlier our plugin tag is {exp:auto_acronym} and since we only have one function we do not need to use a third segment in this plugin. Here’s what my template code looks like followed by what my browser shows:

<h1>Plugin Tutorial</h1>

<p>{exp:auto_acronym}</p>

Not exactly ground-breaking but it is getting us one step closer to our goal. Now that we know how to pass data back we can look at grabbing data passed to our plugin.

Processing Data with our Plugin

The first method we will focus on with processing data is where ExpressionEngine reads all of the data between the plugin tag pair. I you don’t already know, our tag pair is very similar to how HTML tag pairs work. We have an open tag followed by data followed by a close tag like this:

{exp:auto_acronym}
This gets processed
{/exp:auto_acronym}

ExpressionEngine makes it very easy to get this data with the use of the Template Object. In this case we will need to make it global within our function so that we have access to it. Then we define our variable by calling in to play the “tagdata” variable. This variable is the data between our open and close tag pair. Take a look:

function Auto_acronym()
{
   global $TMPL;

   $data = $TMPL->tagdata;
}

Now lets do something very simple with our data and make it bold since it is just text right now. We will add the <strong> tags around it and then define our return_data variable accordingly. This is what our code, template and rendered page should look like now:

Plugin:

function Auto_acronym()
{
   global $TMPL;

   $data = '<strong>'.$TMPL->tagdata.'</strong>';

   $this->return_data = $data;
}

Template:

<h1>Plugin Tutorial</h1>

{exp:auto_acronym}
<p>This gets processed</p>
{/exp:auto_acronym}

Rendered in Browser:

Do Something Already!

Okay, okay. Let’s actually have some fun with this now. Our goal with this plugin is to scan through the data passed to it for common web development acronyms. I mentioned that we would be using 3 for the tutorial: HTML, CSS & RSS. The first this we want to do is put them all into an array within our function. Note that if we were using this array across the plugin and had multiple functions we would probably want to store this outside of the constructor so it could be called by any of the functions.

function Auto_acronym()
{
   global $TMPL;

   $data = $TMPL->tagdata;

   $acronyms = array(
      'HTML' => 'HyperText Markup Language',
      'CSS' => 'Cascading Style Sheets',
      'RSS' => 'Really Simple Syndication'
      );
}

Now that we have our tag data along with the array of acronyms we need to run a foreach() loop on the acronyms. The first thing we will do is run the acronym and tagdata through a strpos() function to make sure that the acronym is, in fact, within our string. The reason we do this is so that we don’t run unneeded string replacements. If your acronym dictionary had hundreds of values and you were running it through a lengthy article it could risk unnecessary processing time. If and only if the acronym is within our tag data we will use the str_replace() function to actually add in the <acronym> tags. After our foreach() loop we will define our return_data variable accordingly. Here’s what it looks like:

function Auto_acronym()
{
   global $TMPL;

   $data = $TMPL->tagdata;

   $acronyms = array(
      'HTML' => 'HyperText Markup Language',
      'CSS' => 'Cascading Style Sheets',
      'RSS' => 'Really Simple Syndication'
      );

   foreach ($acronyms as $short => $long)
   {
      if (strpos($data, $short) !== FALSE)
      {
         $data = str_replace($short, '<acronym title="'.$long.'">'.$short.'</acronym>', $data);
      }
   }

   $this->return_data = $data;

}

In order to test this properly we will need to change our template so that it actually has some of our desired acronyms in it. I’m going to change my template to this:

<h1>Plugin Tutorial</h1>

{exp:auto_acronym}
<p>My name is Erik and I am an addict. I stay up late into the night marking up HTML and CSS with magical alignment.
Whitespace speaks volumes of my care and finesse of the code. My RSS subscribers wait on their toes for my next
example of code beauty. Okay...not really.</p>
{/exp:auto_acronym}

Saving our template and refreshing our browser should produce this:

Now We’re Getting Somewhere!

Now that we are properly processing the tags between the open and close tags of our plugin, let’s look at the other option: passing data within a single tag. Using a single tag with plugins will require adding in a parameter so that data is still passed through to the plugin to be process. You can name the parameter whatever you want. In our case we will use this and add it to our template:

{exp:auto_acronym data="HTML"}

Now that we have a single tag we need to find a way to use it in our plugin. Any parameter that you want to use in your plugin can be fetched using the same Template Object that we used earlier. Instead of being available via a variable you need to fetch it with a function called fetch_param(). We want our pluign to be usable with either a single tag or a tag pair so we will take that into account when we define our $data variable. This is what we will change:

// Original
$data = $TMPL->tagdata;

// New
$data = ($TMPL->fetch_param('data')) ? $TMPL->fetch_param('data') : $TMPL->tagdata ;

If you are not familiar with this syntax is basically says “if the data parameter exists (or returns true) then use it as our data variable, otherwise use the tagdata between tag pairs.” This one change will enable us to use both tag pairs and single tags with the data parameter defined. Here’s what our template should render now:

Almost Done!

Now we have a fully functioning ExpressionEngine plugin. The final step in completing it is adding in useful “usage” information. Let’s go down to the usage() function and add in some simple documentation for the Control Panel.

function usage()
{
   ob_start();
?>

The "dictionary" of acronyms is stored in an array within the plugins/pi.auto_acronym.php file.

Automatically turn a string into an HTML acronym if it is within our acronym dictionary. You can do this with individual words or large blocks of text.

Simple Example
===========================

{exp:auto_acronym data="HTML"}

This outputs:
<acronym title="Hypertext Markup Language">HTML</acronym> in your ExpressionEngine template.

Large Block Example
===========================

{exp:auto_acronym}

<p>My name is Erik and I am an addict. I stay up late into the night marking up HTML and CSS with magical alignment.
Whitespace speaks volumes of my care and finesse of the code. My RSS subscribers wait on their toes for my next
example of code beauty. Okay...not really.</p>

{/exp:auto_acronym}

This outputs:
<p>My name is Erik and I am an addict. I stay up late into the night marking up <acronym title="Hypertext Markup Language">HTML</acronym> and <acronym title="Cascading Style Sheets">CSS</acronym> with magical alignment.
Whitespace speaks volumes of my care and finesse of the code. My <acronym title="Really Simple Syndication">RSS</acronym> subscribers wait on their toes for my next
example of code beauty. Okay...not really.</p>
<?php
   $buffer         = ob_get_contents();

   ob_end_clean(); 

   return $buffer;
}

Now our control panel should look something like this:

Congratulations!

You’ve now completed your first ExpressionEngine plugin. Hopefully this will open up the doors for you now that you see how easy it is. Fetching and returning data is very simple and you can run a lot of your PHP magic from within the plugin itself. I am hosting this plugin on my GitHub account where you can download the full plugin code there if you would like. Next in our ExpressionEngine Add-On series we will look at creating a simple Extension for the Control Panel. Stay tuned!

P.S.

Don’t forget to check out these other awesome ExpressionEngine tutorials!

• Creating a Google Map with EE
• Create a Slideshow with Slideshow Pro and ExpressionEngine
• Become an ExpressionEngine Superstar in 5 Days

• Follow us on Twitter, or subscribe to the Nettuts+ RSS Feed for the best web development tutorials on the web.

For this example, let’s assume that our company has various locations throughout the US, and we are tasked with creating a Google Map that shows all the locations and is easy to maintain. Take a look at the demo to see what we are trying to accomplish.

Setting Up the Weblog and Custom Field Group

First, remember that a weblog is nothing more than just a container of data. Actually, in EE 2.0, they are changing the term weblog to channel. So we are going to create a weblog called Locations and a custom field group called Locations. It’s definitely not a requirement to have them be named the same, but it just makes it easier to understand the relationship.

Defining the Custom Field Group

I actually like to create the field group first, so let’s do that by going to Admin > Weblog Administration > Custom Weblog Fields. Then click on the big green button that says Create a New Weblog Field Group.

Field Groups

Enter Locations as the Field Group Name and click submit.

Naming the new field group

After you click submit, you will see that EE tells you that you can’t use it until you assign it to a weblog. But, we will assign it to a weblog when we create the weblog.

The Locations field group has been created

Now that our field group is created, we need to think about the actual fields that we want to have in it. The following are the fields that I think fit, and their properties in EE:

1. Field Label: Longitude
   • Field Name: locations_longitude
   • Field Type: Text Input
   • Maxlength: 50
   • Default Text Formatting: None
   • Hide Formatting Menu
   • Required Field? Yes
2. Field Label: Latitude
   • Field Name: locations_latitude
   • Field Type: Text Input
   • Maxlength: 50
   • Default Text Formatting: None
   • Hide Formatting Menu
   • Required Field? Yes
3. Field Label: Address
   • Field Name: locations_address
   • Field Type: Text Input
   • Maxlength: 200
   • Default Text Formatting: None
   • Hide Formatting Menu
   • Required Field? Yes
4. Field Label: Photo
   • Field Name: locations_photo
   • Field Type: Text Input
   • Maxlength: 50
   • Default Text Formatting: None
   • Hide Formatting Menu
   • Required Field? No
5. Field Label: Photo Width
   • Field Name: locations_photo_width
   • Field Type: Text Input
   • Maxlength: 4
   • Default Text Formatting: None
   • Hide Formatting Menu
   • Required Field? No
6. Field Label: Photo Height
   • Field Name: locations_photo_height
   • Field Type: Text Input
   • Maxlength: 4
   • Default Text Formatting: None
   • Hide Formatting Menu
   • Required Field? No
7. Field Label: Description
   • Field Name: locations_description
   • Field Type: Textarea
   • Textarea Rows: 6
   • Default Text Formatting: XHTML
   • Display Formatting Menu
   • Required Field? No

Now that we have mapped out our fields, we need to create the fields in EE. So first, click on Add/Edit Custom Fields in the Locations record. Then, click on the big green button that says Create a New Custom Field.

Click on Create a New Custom Field

Now here is where we create the fields in EE that we defined previously. First, let’s start with the Longitude field:

Defining the Longitude field

Once we have selected all of the appropriate properties, click submit. Now, the Longitude field is created.

The Longitude field is created

Now that you have seen how to create one field, I’m just going to go ahead and create the rest.

All custom fields created

Create the Locations Weblog

Now that our field group has been defined, we need to create our weblog and assign the Locations custom field group to it. First, click on the Weblog Administration bread crumb. Then click on Weblog Management. Finally, click the big green button that says Create a New Weblog.

Weblog Management

Enter Locations as the Full Weblog Name and locations as the Short Name. Select Yes for Edit Group Preferences, and a new section will show up. This is where we select Locations as the Field Group.

Create Locations Weblog

Once all the settings have been select, click submit, and the Locations weblog is created.

Locations Weblog Created

Entering Locations

Now that our Locations weblog is created, we can start to enter the locations. Hover over the Publish tab and click on Locations.

Locations Entry Form

The Title, Address, and Description fields are pretty self explanatory, but the URL Title, Longitude, Latitude, and Photo fields may need a little explanation.

URL Title

The URL Title field is auto-populated when you enter the Title. The URL Title replaces spaces with underscores and makes the text lowercase. For this certain situation, we are not going to use it. There is a way to hide it, but I’m not going to go through that right now.

Longitude and Latitude

I’m sure everyone knows what longitude and latitude are, but the question is: how do you determine it from an address? By using a third party site like Map Builder. This site allows you to enter an address, and it returns the longitude and latitude.

Using Map Builder to get longitude and latitude

Photo

If we had a photo of the location, we can include it in when the plot point is clicked. Uploading images in EE can be a little confusing, so let’s walk through it.

First, click on the Upload File link which is located under the submit button. A pop-up window will come up.

File Upload

Browse for your file on your computer, and click Submit.

You can resize the photo after uploading it by clicking the Resize Image button, but I sized my image before uploading, so I won’t demo that part. We want to select URL Only for the File Type and Photo for the Image Location.

File Uploaded

Once our options have been selected, click on Place Image and Close Window. This will now populate your Photo field with the location of your image.

Photo Width and Height

If a user uploads a photo of the location, we want them to input the image height and width. If they do not, the image will break out of the information bubble because of how Google Maps calculates the size of the bubble. It is simple enough to add in the width and height to solve this problem, so we added that in.

Description

If we want to enter a brief description to display in the bubble when the plot point is clicked, this is where you would enter it. This field supports HTML formatting by default.

Now that we have entered all of our pieces of data, we can submit the form and the location will be published.

Our Completed Entry

Then, just repeat this process for the additional entries.

Creating the Map

First, we need to create a new template group for our locations map by clicking on the Templates tab. Then, click on the big green button that says Create a New Template Group.

Templates

Then, enter locations into the Template Group name field, and click submit. Our template group has now been created.

Template Group Created

While we are here, let’s make another template group called scripts.

Next, select the locations template group from the left hand column, and click on index. Now we can start to build our template. You will presented with what is just an empty box, this is where you will add all of your code.

Editing Templates

Now all we need to do is enter our code and click update, and our template is updated.

The Code

In order to use the Google Maps API, you need to sign up for an API key for your site. Once you sign up, you will be provided with the API key, which you use when including the JavaScript on the page. Let’s get started with a simple page and include our Google Maps code:

<!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">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<title>Locations</title>
<script src="http://maps.google.com/maps?file=api&v=2&sensor=false&key=ABQIAAAAGbpRl2XCyCtoHtEtVLA9mhT9xvUTfY2sa86RDF1pWLQtRVPGPxQD1aEASfi1xtt39RqVCDd8ib1hGw" type="text/javascript"></script>
</head>

<body>

</body>
</html>

Note: ABQIAAAAGbpRl2XCyCtoHtEtVLA9mhT9xvUTfY2sa86RDF1pWLQtRVPGPxQD1aEASfi1xtt39RqVCDd8ib1hGw is the value of the Google Maps API key for my site. You will need to update this with your own key.

Once this code has been entered into to textarea, just click update to save the template. Then, if you click the big green button that says View Rendered Template, we will see what the page will look like.

Next, we need to add a div that will actually contain the map.

<!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">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<title>Locations</title>
<script src="http://maps.google.com/maps?file=api&v=2&sensor=false&key=ABQIAAAAGbpRl2XCyCtoHtEtVLA9mhT9xvUTfY2sa86RDF1pWLQtRVPGPxQD1aEASfi1xtt39RqVCDd8ib1hGw" type="text/javascript"></script>
</head>

<body>

<div id="map">You must have JavaScript Enabled to view this map.</div>

</body>
</html>

Note: I just added the message about needing JavaScript for the users who do not have JavaScript enabled, but you could certainly output the list of locations instead of this message.

We need to define the height and width of the div that is going to contain the map, so for this example, I am just going to use some CSS on the page.

<!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">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<title>Locations</title>
<script src="http://maps.google.com/maps?file=api&v=2&sensor=false&key=ABQIAAAAGbpRl2XCyCtoHtEtVLA9mhT9xvUTfY2sa86RDF1pWLQtRVPGPxQD1aEASfi1xtt39RqVCDd8ib1hGw" type="text/javascript"></script>
<style type="text/css">
#map { height: 600px; width: 800px; }
</style>
</head>

<body>

<div id="map">You must have JavaScript Enabled to view this map.</div>

</body>
</html>

That is all of the HTML we need to get our map to show up, so once the code is entered, click Update and Finished, and we are taken back to the main templates section. Next, we are going to code our JavaScript to add the points to the map.

Select scripts from the left hand column and click on New Template. Enter map as the template name, and select JavaScript from the Template Type dropdown, and then click Submit.

Our new template named map has now been created. So click on map, and let’t edit the template.

The cool thing about EE is that we can enter EE code into the JS and CSS templates and it will process that code. In order to do this, we do have to add a hidden config variable to our config.php file that is located in the system folder. So open up your config.php file and enter the following: $conf['protect_javascript'] = ‘n’;. Then upload it, and EE tags will be processed in JS code.

Note: I am going to use plain old JavaScript for this example, but you could easily modify some code to use your framework of choice.

First, we are going to get started creating a function that will add the plot points to the map:

function populateMap() {
	var map = new GMap2(document.getElementById("map"));
	map.setCenter(new GLatLng(32.02670629333614, -95.009765625), 4);
	map.setUIToDefault();
}

The first line is specifying to use the element with an id of map to create the map. The next line sets the center of the map to the specified latitude and longitude, then sets the zoom level. These are just arbitrary values for this example, so you will most likely need to adjust. The final line sets up the controls on the map, i.e. zoom, move, map type, etc.

Now, we want to access the data that we entered in EE by using the exp:weblog:entries tag:

function populateMap() {
	var map = new GMap2(document.getElementById("map"));
	map.setCenter(new GLatLng(32.02670629333614, -95.009765625), 4);
	map.setUIToDefault();

	{exp:weblog:entries weblog="locations" disable="categories|category_fields|member_data|pagination|trackbacks"}
		{if count == 1}
			var points = new Array({total_results});
		{/if}

	{/exp:weblog:entries}
}

So this code is saying to “query” the locations weblog, and disable additional parameters that we will not be using. This is a good habit to get into because it can improve performance.

There are some EE variables that we are using that I will need to explain: count and total_results. count is exactly what it sounds like: it just indicates the number of the current record that we are on. total_results indicates how many total records will be returned.

So if count equals 1, this the first time through the loop, so we initialize our array that will have a size of the total number of records returned.

Next, we want to actually grab the data and output it in the loop. Note: I am going to add line breaks to this code just for readability, but in production use, the line breaks need to be removed.

function populateMap() {
	var map = new GMap2(document.getElementById("map"));
	map.setCenter(new GLatLng(32.02670629333614, -95.009765625), 4);
	map.setUIToDefault();

	{exp:weblog:entries weblog="locations" disable="categories|category_fields|member_data|pagination|trackbacks"}
		{if count == 1}
			var points = new Array({total_results});
		{/if}

		points[{count}] = [{locations_latitude},{locations_longitude},
			'<div class="infoContainer">
				<h2>{title}</h2>
				{if locations_photo && locations_photo_width && locations_photo_height}
					<img src="{locations_photo}" alt="" height="{locations_photo_height}" width="{locations_photo_width}" />
				{/if}
				<p class="address">{locations_address}</p>
				{if locations_description}
					{locations_description}
				{/if}
			</div>'];

	{/exp:weblog:entries}
}

That may look like a lot, so let’s go through it piece by piece.

points[{count}] = [{locations_latitude},{locations_longitude},

Here, we are adding an array to our points array. In this array, we are going to be adding the latitude, longitude, and information to display in the information bubble. Notice how locations_latitude and locations_longitude match up with the values we added for the Field Names in our custom field group.

'<div class="infoContainer">
	<h2>{title}</h2>
</div>'];

In this snippet, we are just adding a div and the title that was entered into EE.

{if locations_photo && locations_photo_width && locations_photo_height}
	<img src="{locations_photo}" alt="" height="{locations_photo_height}" width="{locations_photo_width}" />
{/if}

In this piece, we are checking to see if there was a value entered into the photo, photo width, and photo height fields. If there was, we add the photo to our information bubble.

<p class="address">{locations_address}</p>
{if locations_description}
	{locations_description}
{/if}

Finally, we add the address to the information bubble, and if there was a description entered, we add that too. Here is that whole line without any line breaks:

points[{count}] = [{locations_latitude},{locations_longitude},'<div class="infoContainer"><h2>{title}</h2>{if locations_photo && locations_photo_width && locations_photo_height}<img src="{locations_photo}" alt="" height="{locations_photo_height}" width="{locations_photo_width}" />{/if}<p class="address">{locations_address}</p>{if locations_description}{locations_description}{/if}</div>'];

To finish off the function, we just need to loop through the array and add the plot points and event listeners to the map:

function populateMap() {
	var map = new GMap2(document.getElementById("map"));
	map.setCenter(new GLatLng(32.02670629333614, -95.009765625), 4);
	map.setUIToDefault();

	{exp:weblog:entries weblog="locations" disable="categories|category_fields|member_data|pagination|trackbacks"}
		{if count == 1}
			var points = new Array({total_results});
		{/if}

		points[{count}] = [{locations_latitude},{locations_longitude},'<div class="infoContainer"><h2>{title}</h2>{if locations_photo && locations_photo_width && locations_photo_height}<img src="{locations_photo}" alt="" height="{locations_photo_height}" width="{locations_photo_width}" />{/if}<p class="address">{locations_address}</p>{if locations_description}{locations_description}{/if}</div>'];

	{/exp:weblog:entries}

	for(var i=1; i < points.length; i++) {
		var point = new GLatLng(points[i][0],points[i][1]);
		var windowInfo = points[i][2];
		var marker = createMarker(point,windowInfo);
		map.addOverlay(marker);
	}
}

So we are creating our point and passing in the latitude and longitude. Then, we are creating a variable that contains all of the information for the information bubble. Next, we are calling a custom function that I will define in a minute and passing in the point and information bubble text. Finally, we are adding the marker to the map.

Here is our custom function that is creating the marker:

function createMarker(point, overlayText) {
	var marker = new GMarker(point);
	GEvent.addListener(marker, "click", function() {marker.openInfoWindowHtml(overlayText);});
	return marker;
}

So we are creating a marker based on our point on the map, then adding an event listener that will open the information bubble with the appropriate text when it is clicked.

So that’s pretty much it. Although, I will add one more function that will tell the JS function to run once the dom has been loaded:

function addLoadEvent(func) {
	var oldonload = window.onload;
	if (typeof window.onload != 'function') {
		window.onload = func;
	} else {
		window.onload = function() {
			if (oldonload) {
				oldonload();
			}
			func();
		}
	}
}
addLoadEvent(populateMap);

I first read about this function from Simon Willison. You could again replace this with code for whatever JS library you are using.

Here is the full JS for that template:

function populateMap() {
	var map = new GMap2(document.getElementById("map"));
	map.setCenter(new GLatLng(32.02670629333614, -95.009765625), 4);
	map.setUIToDefault();

	{exp:weblog:entries weblog="locations" disable="categories|category_fields|member_data|pagination|trackbacks"}
		{if count == 1}
			var points = new Array({total_results});
		{/if}

		points[{count}] = [{locations_latitude},{locations_longitude},'<div class="infoContainer"><h2>{title}</h2>{if locations_photo && locations_photo_width && locations_photo_height}<img src="{locations_photo}" alt="" height="{locations_photo_height}" width="{locations_photo_width}" />{/if}<p class="address">{locations_address}</p>{if locations_description}{locations_description}{/if}</div>'];

	{/exp:weblog:entries}

	for(var i=1; i < points.length; i++) {
		var point = new GLatLng(points[i][0],points[i][1]);
		var windowInfo = points[i][2];
		var marker = createMarker(point,windowInfo);
		map.addOverlay(marker);
	}
}

function createMarker(point, overlayText) {
	var marker = new GMarker(point);
	GEvent.addListener(marker, "click", function() {marker.openInfoWindowHtml(overlayText);});
	return marker;
}

function addLoadEvent(func) {
	var oldonload = window.onload;
	if (typeof window.onload != 'function') {
		window.onload = func;
	} else {
		window.onload = function() {
			if (oldonload) {
				oldonload();
			}
			func();
		}
	}
}
addLoadEvent(populateMap);

Once all that code is added, click Update and Finished to be returned to the main templates page. Next, we need to go back to our locations template group and edit the index template.

We need to include the JS template that we just created in the head of the document:

<script type="text/javascript" src="{path="scripts/map"}"></script>

I am using the path variable to link to the JS template.

So now, when we go back and view our locations template in the browser, you may see a JS error. If a location description was entered, it may add some new lines to the code, so this will break the string in the JS. So the solution is to somehow remove those new lines.

Installing the Plugin

Luckily, there is a plugin for EE called Find and Replace that will let us replace all \n with nothing.

So browse to Admin > Utilities > Plugin Manager, and find the plugin in the right hand column. When you find it, click on install, and that’s it.

Using the Plugin

Now, we can use the plugin in our code. So go back and edit the map template in our scripts template group, and replace this:

{if locations_description}
	{locations_description}
{/if}

With this:

{if locations_description}
	{exp:replace find="\n" multiple="yes" regex="yes"}
		{locations_description}
	{/exp:replace}
{/if}

This function is basically just saying to replace all new lines with nothing. Of course we want to remove all of the line breaks from the code, so here is the updated full JS:

function populateMap() {
	var map = new GMap2(document.getElementById("map"));
	map.setCenter(new GLatLng(32.02670629333614, -95.009765625), 4);
	map.setUIToDefault();

	{exp:weblog:entries weblog="locations" disable="categories|category_fields|member_data|pagination|trackbacks"}
		{if count == 1}
			var points = new Array({total_results});
		{/if}

		points[{count}] = [{locations_latitude},{locations_longitude},'<div class="infoContainer"><h2>{title}</h2>{if locations_photo && locations_photo_width && locations_photo_height}<img src="{locations_photo}" alt="" height="{locations_photo_height}" width="{locations_photo_width}" />{/if}<p class="address">{locations_address}</p>{if locations_description}{exp:replace find="\n" multiple="yes" regex="yes"}{locations_description}{/exp:replace}{/if}</div>'];

	{/exp:weblog:entries}

	for(var i=1; i < points.length; i++) {
		var point = new GLatLng(points[i][0],points[i][1]);
		var windowInfo = points[i][2];
		var marker = createMarker(point,windowInfo);
		map.addOverlay(marker);
	}
}

function createMarker(point, overlayText) {
	var marker = new GMarker(point);
	GEvent.addListener(marker, "click", function() {marker.openInfoWindowHtml(overlayText);});
	return marker;
}

function addLoadEvent(func) {
	var oldonload = window.onload;
	if (typeof window.onload != 'function') {
		window.onload = func;
	} else {
		window.onload = function() {
			if (oldonload) {
				oldonload();
			}
			func();
		}
	}
}
addLoadEvent(populateMap);

Conclusion

That’s it! We can now view our template in the browser and see our EE powered Google Map. You can also view my demo.

• Follow us on Twitter, or subscribe to the NETTUTS RSS Feed for more daily web development tuts and articles.