Using Polymer in WordPress: Build a Custom Google Maps Component

Web components are a set of standards for creating custom, reusable HTML elements. Polymer is an open-source JavaScript library for building web applications using web components. Created by those clever folks at Google, it provides a number of additional features over vanilla web components and when used with a polyfill, supports the latest version of all major browsers.

In this tutorial I'm going to show you how easy it is to make use of web components and Polymer in WordPress. I'm going to start by showing you how to integrate Polymer into your WordPress install, then I'm going to demonstrate how to add a working Google Maps component to your site's side bar. This might be useful for any site (e.g. that of a restaurant) which needs to provide visitors with directions to their premises.

After reading, you'll be able to employ this technique on a site of your own. And you'll not be limited to a Google Map widget, you'll be able to choose from the wide range of pre-made components, or even write your own.

As ever, all of the code for this tutorial is available in a GitHub repository.

Why Polymer?

As native support for web components is growing ever better, you might be forgiven for asking if Polymer is still relevant. The short answer to that question is Yes!

Polymer does make use of a variety of web component polyfills—which will hopefully one day full by the wayside—but it is a lot more than that. Polymer is a wrapper around the web components API that allows us to develop and implement new components at a much greater speed than we would otherwise be able. It offers various additional features over vanilla web components, such as one-way and two-way data binding, computed properties and gesture events. It comes with a very polished CLI which can be used for such tasks as scaffolding out a project, running tests, or running a local server, and it can make use of a wide range of pre-built elements, such as the much loved material design elements library.

In short, Polymer is still very relevant. It is a powerful framework, which is used in production by large companies such as USA Today, Coca Cola and Electronic Arts.

Setting Up WordPress

Before we start, we need to setup our environment that is going to be running WordPress. For this tutorial, I'll be using the ScotchBox Vagrant VM, equipped with some pre-installed tools to kickstart your WordPress installation.

If you have WordPress installed already, or would prefer to use a different method, you can skip this bit. If you need a bit of help with the setup, but don't want to go the vagrant route described below, try Googling "install WordPress locally" and looking for an up-to-date tutorial.

We start of by making sure that Git, Vagrant and Virtual Box are installed on our system. We can then clone the GitHub repo with ScotchBox's pre-populated Vagrantfile.

git clone http://ift.tt/1xiiR9O sitepoint-wp-polymer

Now we are ready to run vagrant up. After our machine has booted, we have to remove the default /public/index.php static file and install WordPress.

cd sitepoint-wp-polymer/public
rm index.php
git clone http://ift.tt/1BFfzSc .

Now we have to make a duplicate of the wp-config-sample.php file. Name it wp-config.php.

cp wp-config-sample.php wp-config.php

and edit the following values:

// wp-config.php

// ...

define('DB_NAME', 'scotchbox');
define('DB_USER', 'root');
define('DB_PASSWORD', 'root');

// ...

Now you are ready to fire up your browser and visit http://192.168.33.10. You will be prompted to enter the admin account credentials and site title. Feel free to fill these out as you see fit.

Adding the SitePoint Base Theme

So we've got WordPress set up, now we need a theme. Out of the box, this will be the Twenty Seventeen theme, but this is pretty generic and includes much more than you normally need. A good alternative here, is to use the SitePoint WordPress base theme.

This theme was created in response to the question "What would the perfect WordPress base theme look like?". Its features include:

• No fat. No cruft. Speedy.
• Minimal design. It’s your job to make it pretty.
• No ‘cute’ features you never actually use.
• SEO friendly to its core.
• Super Mobile-friendly.
• 100% Open Source and free to use.

The SitePoint WordPress base theme is a great starting point for new projects. It's mobile friendly, easy to use and 100% free. To follow along with the rest of tis tutorial, head over to the theme's homepage and download it now.

And while you're there, you might like to check out the suite of paid themes SitePoint offers, too. These are all built on top of the base theme and include an ecommerce theme, restaurant theme, portfolio theme, business theme and construction theme.

After downloading SitePoint WordPress base theme, unzip it and copy/paste to thewp-content/themes folder. Then create a new folder called sitepoint-base-child, in wp-content/themes. In that directory create a style.css file and a functions.php file.

cd wp-content/themes/
mkdir sitepoint-base-child
cd sitepoint-base-child
touch functions.php style.css

Open up style.css and copy this into it:

/*
 Theme Name:   SitePoint Base Child
 Author:       Almir B.
 Author URI:   http://ift.tt/28X308Z
 Template:     sitepoint-base
 Version:      1.0.0
 Text Domain:  ab-sitepoint-base
*/

And into functions.php:

<?php
//functions.php

add_action( 'wp_enqueue_scripts', 'sp_theme_enqueue_styles' );
function sp_theme_enqueue_styles() {
  wp_enqueue_style( 'parent-style', get_template_directory_uri() . '/style.css' );
}

This will enqueue the base CSS from the parent theme.

We just created a child theme, whose role is to implement functionalities on top of the base theme without having to modify the base files. All of the customisations go into this child theme.

One last step is to go to the admin dashboard, then to Appearance > Themes from the main side menu, and click Activate under, Sitepoint Base Child theme.

Including Polymer in WordPress

Now that's done, we have to install Polymer with bower. Make sure you are in the public/wp-content/themes/sitepoint-base-child folder, and then run:

bower init

You can answer with default answer to every question. Next we need to install the dependencies:

bower install --save Polymer/polymer#^2.0.0 PolymerElements/paper-input#2.0-preview

This will install Polymer and the paper-input component, so that we can have a fancy material designed input component out of the box. It is important to use the #2.0-preview tag for the paper input and also for the Google Map element later, as it will not work with the latest version of Polymer (version 2.0) otherwise.

In order to user Polymer, we have to include it using an HTML import, and we will also include the polyfill for web components, so as to support older browsers.

Head to the functions.php file in the child theme, and add an enqueue to the existing enqueue function.

<?php
//functions.php

add_action( 'wp_enqueue_scripts', 'sp_theme_enqueue_styles' );
function sp_theme_enqueue_styles() {
  wp_enqueue_style( 'parent-style', get_template_directory_uri() . '/style.css' );
  wp_enqueue_script( 'polymer', get_stylesheet_directory_uri() . '/bower_components/webcomponentsjs/webcomponents-lite.js' );
}

WordPress does not have an enqueue function for enqueueing HTML imports, but we can hook into the wp_head hook which outputs into the <head> element of the page.

<?php
//functions.php

add_action( 'wp_enqueue_scripts', 'sp_theme_enqueue_styles' );
function sp_theme_enqueue_styles() {
  wp_enqueue_style( 'parent-style', get_template_directory_uri() . '/style.css' );
  wp_enqueue_style( 'polymer', get_stylesheet_directory_uri() . '/bower_components/webcomponentsjs/webcomponents-lite.min.js' );
}

add_action( 'wp_head', 'include_polymer_elements' );
function include_polymer_elements() {
  ?>

  <link rel="import"
        href="<?php echo get_stylesheet_directory_uri() ?>/bower_components/polymer/polymer.html">
  <link rel="import"
        href="<?php echo get_stylesheet_directory_uri() ?>/bower_components/paper-input/paper-input.html">
  <?php
}

That's all we needed to start using Polymer elements in WordPress. Now let's create a WordPress widget so we can take this out for a test ride.

Registering a Widget

In order to create a new widget, we will create a new child class from the WP_Widget class and then register it with the widgets_init hook.

Create a new folder in your child theme, name it lib, and add it a file named sitepoint-map-widget.php.

mkdir lib
cd lib
touch sitepoint-map-widget.php

Copy the following into that file:

<?php 
// lib/sitepoint-map-widget.php

class SitepointMapWidget extends WP_Widget {

  function __construct() {
    // Instantiate the parent object
    parent::__construct( false, 'Google Paper Input' );
  }

  function widget( $args, $instance ) {
    echo '<paper-input raised always-float-label label="Floating label"></paper-input>';
  }
}

All we did here is create a new child class of WP_Widet and called the parent constructor in order to give the widget a custom name. Additionally, the widget function is the one that does the actual output. For now, we will simply output a <paper-input> element, which is an element from the paper-input-elements collection.

Last but not least, we need to include this new PHP file at the top of our functions.php file:

<?php
// functions.php
require_once( 'lib/sitepoint-map-widget.php' );

// ...

and then register a widget at the end of the file:

<?php
// functions.php

// ...

add_action( 'widgets_init', 'sp_register_widgets' );
function sp_register_widgets() {
  register_widget( 'SitepointMapWidget' );
}

Now we can go into the admin dashboard of WordPress. From the main menu, go into Appearance > Widgets, and there you should see a widget named Google Paper Input on the left.

Drag and drop it into the Main Sidebar section to the right, above the rest of the default widgets from the SitePoint Base theme.

Now you can visit the homepage, and on the right side right above the search box, you will see a material design input with a label.

And thus we have concluded Polymer's Hello, World! example. We've covered a lot of ground already—installing Polymer, integrating it with WordPress and including a sample widget, all in just a few lines of code—but in the next section we will take this further and implement our Google Map component.

Continue reading %Using Polymer in WordPress: Build a Custom Google Maps Component%

by Almir Bijedic via SitePoint