WordPress Plugins and TomTom: The Admin Panel 

In the second installment of our WordPress Plugin series we'll walk through creating the administrator-facing interface of the Plugin, saving our TomTom developer API key as a Plugin setting, and displaying a map in the Plugin admin panel.

WordPress TomTom Plugins -- Part Two

In today's digital-first world it's important to connect your online presence -- website, blog, or social media account -- with the physical presence of your business: stores, offices, or events.

Our previous article looked at the process of adding a map to a business website in order to display the locations of all storefronts for a business. We chose WordPress as a popular, flexible, and easily extended publishing platform for our site and chose TomTom's Map Display API for its ease of use and industry leading map resources.

To put these technologies together, we started creating a WordPress Plugin that makes adding the functionality of the TomTom Map Display API to any WordPress-based website quick and easy. In the previous article we created the basic Plugin elements that allow the Plugin to appear in the WordPress administrative interface. We also registered our application with TomTom and got developer keys to access the Maps and Search APIs.

In this article we'll:

• Walk through the steps required to start creating the administrator-facing interface of the WordPress Plugin.

• Create a way to save our API key.

• Work on displaying a map in the Plugin admin panel.

Prerequisites

For this part, you will need to have an understanding of HTML, CSS, JavaScript, jQuery, and PHP. It will help if you’ve done some WordPress development before.

We’ll walk through the basic steps to activate the Plugin, but we’ll skip code that is just plain HTML, JavaScript, and PHP and unrelated to implementing the map portion of the Plugin.

saving the api key to the database

In the previous article we registered our application and got a developer API key. We’ll need to save it to the database so our Plugin will be able to use it.

We’re going to create a new admin page to do this. You already saw the function’s name referenced: ttlocator_sdk_setup_page_html(). It’s a simple function that generates an HTML form where the user can enter their TomTom API key:

function ttlocator_sdk_setup_page_html() {
    $plugin_directory = plugin_dir_url(__FILE__);
    $stylesheet = $plugin_directory . "styles/styles.css";
    ?>
    <link href="<?php echo $stylesheet ?>" rel="stylesheet">
    <h1>TomTom SDK Setup</h1>
    <h2>SDK Key</h2>
    <p>Please enter your TomTom API key:</p>
    <form method="post" action="options.php">
        <?php settings_fields( 'tomtom-map-plugin-sdk-setup' ); ?>
        <?php do_settings_sections( 'tomtom-map-plugin-sdk-setup' ); ?>
        <input type="text"
               class="ttlocator-sdk-key-input"
               name="tomtom_locator_api_key"
               value="<?php echo esc_attr(get_option("tomtom_locator_api_key")) ?>" />
        <?php submit_button() ?>
    </form>
    <?php
}

Note that we’re calling the settings_fields() and do_settings_fields() functions from the WordPress API at the beginning of our form. We also set the name of our input field equal to the name of the setting we’ll be saving. Together, these API calls ensure that WordPress is able to generate a form that will save our setting.

We also use the API’s get_option() function to pre-populate the text field with our API key if one has already been saved to the database. Using WordPress’ Options API is a huge time saver here, because it means we don’t have to create a new database just to hold our API key.

Finally, we call the WordPress API’s submit_button() function. This generates a button that will submit our form to the WordPress admin options page. And with that, we have a fully functioning page that will let users save their TomTom API key or update a key they have already entered.

using the maps sdk for web

Next, let's download the TomTom Maps SDK for Web files and copy them to the Plugin project.

The Maps SDK for Web includes all of the code files and resources you need to quickly add TomTom maps to a website. Rather than creating all the resources yourself, the Maps SDK for Web includes prepackaged JavaScript libraries, CSS stylesheets, images, glyphs and all the other resources needed to display maps. All you need to do is add a few lines of HTML and call the Maps SDK script.

Next, unpack the ZIP file, rename the SDK files folder “tomtom-sdk”, and copy the entire folder of SDK files to the WordPress Plugin project folder, \wp-tomtom-stores-map. The files should look like this:

The \scripts and \styles folders here are part of our Plugin project and will be explained later in this article.

adding maps to the admin panel

Now, let’s circle back to the ttlocator_config_page_html() function. Previously, all it did was show a title. Let’s crank it up to 11:

function ttlocator_config_page_html() {
    $plugin_directory = plugin_dir_url(__FILE__);
    $stylesheet = $plugin_directory . "styles/styles.css";
    $locator_js = $plugin_directory . "scripts/locator.js";
    $tomtom_sdk_dir = $plugin_directory . "tomtom-sdk/";
    $map_stylesheet = $tomtom_sdk_dir . "map.css";
    $tomtom_js = $tomtom_sdk_dir . "tomtom.min.js";
    $locations = ttlocator_get_locations();

    wp_enqueue_script("jquery");
    wp_enqueue_style("ttlocator-styles", $stylesheet);
    wp_enqueue_style("ttlocator-tomtom-map-styles", $map_stylesheet);
    wp_enqueue_script("ttlocator-tomtom-sdk", $tomtom_js);
    wp_enqueue_script("ttlocator-locator-page-script",
        $locator_js, array(), false, true);

    // add jQuery UI dialogs for deletion confirmation
    wp_enqueue_script( 'jquery-ui-dialog' ); //
    wp_enqueue_style( 'wp-jquery-ui-dialog' );

    ?>
    <div class="ttlocator_locator_page">
    <h1>TomTom Store Locator</h1>
    <div id='map' style='height:500px;width:95%'></div>
    <script>
        var tomtomSdkKey = '<?php echo esc_attr(get_option("tomtom_locator_api_key")); ?>';
        var tomtomSdkPath = '<?php echo $tomtom_sdk_dir; ?>';
        var storeLocations = <?php echo json_encode($locations); ?>;
    </script>
    <div class="ttlocator-stores-table">
    <h2>Stores</h2>
    <?php if (sizeof($locations) === 0): ?>
        <p>
            You havent added any stores. Would you like to add one now?
        </p>
    <?php
    else:
        echo ttlocator_store_table_html($locations);
    endif; ?>
        <div class="ttlocator-add-store-button">
            <button class="button button-primary ttlocator-add-store">
                Add Store
            </button>
            <button id="ttlocator-delete-selected"
                    class="button bu">
                Delete Selected
            </button>
        </div>
    </div>
    </div>
    <?php
    echo ttlocator_add_store_html();
    echo ttlocator_delete_location_confirm_dialog_html();
}

There’s a lot going on here, but if we break it down, it’s not so bad. Aside from a few WordPress API functions, it is mostly plain HTML.

The key thing to notice is the call to plugin_dir_url(). This is a WordPress API call that, as its name implies, provides the URL of the currently executing plugin. This is important because of all the assets our admin page needs — both JavaScript and CSS — are in subfolders of our plugin directory. We can’t hard code this because our plugin may be running on many different sites, each with a custom domain. Asking WordPress for our plugin’s URL ensures that we’re always loading our assets from the correct location.

Next, we set up variables that store the locations of resources our page will need: our own JavaScript and CSS, along with the JavaScript and CSS required by the TomTom Web SDK.

Then, you’ll notice several calls to wp_enqueue_style() and wp_enqueue_script(). This is the preferred way of loading scripts and stylesheets in a WordPress plugin. Instead of inserting your own link and script tags all over the place, you can rely on WordPress to place them correctly on the page.

After this, you see a div:

  
  
   
   <div id="map" style="height:500px;width:95%"> </div>

  
  

It may look unassuming, but this is where our admin page’s map will live!

After the div, we set a few JavaScript variables that our map will need to create itself:

    <script>
        var tomtomSdkKey = '<?php echo esc_attr(get_option("tomtom_locator_api_key")); ?>';
        var tomtomSdkPath = '<?php echo $tomtom_sdk_dir; ?>';
        var storeLocations = <?php echo json_encode($locations); ?>;
    </script>

First, we’re setting up the TomTom key that our setup page saved in the database. This key must be accessible to JavaScript in order for your map to work. Next, we’re saving the exact URL where the TomTom SDK is located. The map will also require this in order to work. Finally, we’re saving a list of store locations that we loaded from the custom WordPress table that our plugin creates when it is activated.

The real magic happens locator.js - conveniently located in our plugin’s scripts subdirectory. Starting on line 5, you’ll see the following code:

tomtom.setProductInfo('Store Locator', '1.0'); 
var map = tomtom.L.map('map', { 
   key: window.tomtomSdkKey, 
   source: 'vector', 
   basePath: tomtomSdkPath, 
   center: [39.8283, -98.5795], 
   zoom: 3.5 
});  

We start by telling the SDK a little about the product that will be using it, and then we dive right into the code that creates the map. It’s fairly self-explanatory: to create a map with the TomTom Web SDK, you simply make a call to the tomtom.L.map() function.

The first argument to the function is a string containing the id of the div where the map should be created. The second argument is a JavaScript object containing additional data the map needs. key, source, and basepath are all required. key and basepath use the variables we set up earlier in our PHP code. source can be either ‘vector’ or ‘raster’.

Discussing the difference between vector and raster maps is beyond the scope of this article, but in general when working with maps on the web, you should default to using vector maps unless you have a specific reason not to.

The two final properties, center and zoom, are optional, and give our map a bit of information about how to render itself. As expected, center gives the map a set of latitude and longitude coordinates on which to center itself. We’ve set the map center to the exact middle of the United States in the map above, but feel free to customize it to your needs or even make it a configuration option in your own plugin.

Side note: you may have noticed that we called tomtom.L.map() when creating the map. That L stands for Leaflet, a JavaScript open source mapping library that the TomTom Web SDK uses to render maps. When interacting directly with the map to do things like add markers, you’ll be using functions of the Leaflet API.

After the map setup, the remainder of ttlocator_config_page_html() is bog-standard PHP and HTML — nothing WordPress specific. We even outsource some of our HTML generation to two functions named ttlocator_add_store_html() and ttlocator_delete_location_confirm_dialog_html() to prevent ttlocator_config_page_html() from becoming too unwieldy.

Next steps

In this article we started creating a basic WordPress Plugin admin panel that enables a site administrator to configure the stores map for a website. We downloaded and installed the TomTom Maps SDK for Web and started using the SDK and APIs to build our map.

In the next article we'll create the database table that will save store locations. We’ll add an interface to create the list of store locations, converting addresses to coordinates with the TomTom Search API, and displaying locations on the map.