WP Quadratum – Display Your Last Foursquare Checkin On WordPress

What Is WP Quadratum?

WP Quadratum is a WordPress plugin to display your last Foursquare checkin as a map widget in the sidebar or embedded in a post or page, fully authenticated via OAuth 2.0.

What Does It Do?

This plugin allows you to display your last Foursquare checkin as a map widget on the sidebar or embedded via a shortcode in a post or page of your WordPress powered site.

You can configure WP Quadratum to …

  1. Associate your WordPress powered site with your Foursquare account using OAuth 2.0, which keeps your personal information safe and secure.
  2. Choose which map provider you want your checkin shown on; you can choose from:
    1. Nokia Maps
    2. Google Maps
    3. OpenStreetMap from CloudMade
    4. OpenStreetMap from OpenLayers
  3. Add your maps API key(s) for your chosen map provider; Nokia Maps, Google Maps and CloudMade maps all require API keys.
  4. Add your authentication credentials for Nokia Maps, either within the plugin’s settings and options or via the WP Nokia Auth plugin.
  5. Choose the width and height of the widget and map on the sidebar.
  6. Choose the zoom level of the map display.
  7. Choose whether to show private checkins on the map.

The strapline text containing the venue name, venue URL and timestamp of your last Foursquare checkin can be customised via the plugin’s filters. See the Filter Support And Usage section for more information.

The current version of this plugin allows you to associate a single Foursquare account with your WordPress site; associating multiple Foursquare accounts, one per user account is not currently supported.

How Do I Download WP Quadratum?

To download or install WP Quadratum on your WordPress powered site, either search for WP Quadratum from the WordPress Dashboard or go to plugin’s page on the official WordPress plugin repository.

If you want to fork the source code of the plugin, you can find it on the plugin’s GitHub page at https://github.com/vicchi/wp-quadratum.

What’s New?

WP Quadratum v1.2.0 was released 06/11/12.

Full Documentation

Installation

  1. You can install WP Quadratum automatically from the WordPress admin panel. From the Dashboard, navigate to the Plugins / Add New page and search for “WP Quadratum” and click on the “Install Now” link.
  2. Or you can install WP Quadratum manually. Download the plugin Zip archive and uncompress it. Copy or upload the wp-quadratum folder to the wp-content/plugins folder on your web server.
  3. Activate the plugin. From the Dashboard, navigate to Plugins and click on the “Activate” link under the entry for WP Quadratum.
  4. Configure your Foursquare credentials; from the Dashboard, navigate to the Settings / WP Quadratum page or click on the “Settings” link from the Plugins page on the Dashboard.
  5. To display your Foursquare checkins, WP Quadratum needs to be authorised to access your Foursquare account information; this is a simple, safe and secure 3 step process. WP Quadratum never sees your account login information and cannot store any personally identifiable information.
  6. Step 1. Register this WordPress site as a Foursquare application on the Foursquare OAuth Consumer Registration page. If you’re not currently logged into your Foursquare account, you’ll need to login with the Foursquare account whose checkins you want WP Quadratum to display. The Application Name is a label you want to use to identify this connection to your Foursquare account. The Application Web Site is the URL of your WordPress site. The Callback URL will be provided for you and will be along the lines of http://www.yoursite.com/wp-content/plugins/wp-quadratum/includes/wp-quadratum-callback.php (this is just an example, don’t use this URL). Once you have successfully registered your site, you’ll be provided with two keys, the Client ID and the Client Secret.
  7. Step 2. Copy and paste the supplied Client ID and Client Secret into the respective WP Quadratum setting fields. Click on the “Save Changes” button to preserve them.
  8. Step 3. You should now be authorised and ready to go; click on the Connect to Foursquare button.
  9. Choose your mapping provider. From the Maps tab, select the map provider from the Maps Provider drop down.
  10. If your chosen mapping provider requires an API key or keys, enter them as requested. If you don’t have an API key, each maps provider tab has a link to the provider’s site where you can sign up and obtain your API key.
  11. If you have selected Nokia Maps as your map provider:
    1. If you have the WP Nokia Auth plugin installed and configured, your Nokia Maps API keys will be shown in read-only form
    2. If you don’t have the WP Nokia Auth plugin installed and configured, you can enter your Nokia Maps API keys to give you, amongst other benefits, an increased per month transaction limit. Click on the Save Changes button to save your credentials.
  12. Add and configure a WP Quadratum Widget. From the Dashboard, navigate to Appearance / Widgets and drag the WP Quadratum Widget to your desired widget area.
  13. You can configure the widget’s title, with widget’s width and map height in px, the map zoom level and whether to show private checkins or not. Click on the Save button to preserve your changes.

Screenshots

  1. Settings and Options: Foursquare Tab; Client ID and Client Secret entered
  2. Settings and Options: Foursquare Tab; Client ID and Client Secret saved
  3. Settings and Options: Foursquare Tab; Successfully authenticated with Foursquare
  4. Settings and Options: Maps Tab; Nokia Maps without WP Nokia Auth installed and active
  5. Settings and Options: Maps Tab; Nokia Maps with WP Nokia Auth installed and active
  6. Settings and Options: Maps Tab; CloudMade Maps
  7. Settings and Options: Maps Tab; Google Maps
  8. Settings and Options: Maps Tab; OpenLayers Maps
  9. Settings and Options: Defaults Tab
  10. Settings and Options: Colophon Tab
  11. Settings and Options: Widget settings
  12. Sample Widget: with Nokia Maps
  13. Sample Widget: with CloudMade Maps
  14. Sample Widget: with Google Maps
  15. Sample Widget: with OpenLayers Maps

Settings and Options: Foursquare Tab; Client ID and Client Secret entered

Settings and Options: Foursquare Tab; Client ID and Client Secret saved

Settings and Options: Foursquare Tab; Successfully authenticated with Foursquare

Settings and Options: Maps Tab; Nokia Maps without WP Nokia Auth installed and active

Settings and Options: Maps Tab; Nokia Maps with WP Nokia Auth installed and active

Settings and Options: Maps Tab; CloudMade Maps

Settings and Options: Maps Tab; Google Maps

Settings and Options: Maps Tab; OpenLayers Maps

Settings and Options: Defaults Tab

Settings and Options: Colophon Tab

Settings and Options: Widget settings

Sample Widget: with Nokia Maps

Sample Widget: with CloudMade Maps

Sample Widget: with Google Maps

Sample Widget: with OpenLayers Maps

Frequently Asked Questions

How do I get help or support for this plugin?

In short, very easily. But before you read any further, take a look at Asking For WordPress Plugin Help And Support Without Tears before firing off a question. In order of preference, you can ask a question on the WordPress support forum; this is by far the best way so that other users can follow the conversation. You can ask me a question on Twitter; I’m @vicchi. Or you can drop me an email instead. I can’t promise to answer your question but I do promise to answer and do my best to help.

Is there a web site for this plugin?

Absolutely, it’s the page you’re reading,  the WP Quadratum home page which always contains the latest information. There’s also the official WordPress plugin repository page and the source for the plugin is on GitHub as well.

I have multiple authors on my site; can I have a widget for each author’s Foursquare account?

In the current version, no. In the current version, you can link a single Foursquare account with your WordPress site (multi-site or network sites may work, assuming each site is for a single user but I haven’t tested this). The plugin is currently designed to support a WordPress site which is used for a personal blog (in other words, exactly the way my site is set up). Future versions of the plugin may support this if people ask for this feature (assuming anyone apart from myself actually uses it!).

Nokia Maps? Really?

Yes. Really. At the time of writing (April 2012) 196 countries, 75M Places, 2.4M map changes a day. That sort of really. All available through a set of developer friendly APIs.

OK. Nokia Maps. I get it. But why register?

The Nokia Location APIs work if you don’t register. But they work even better and you can do even more if you do register. Take transactional limits. Unregistered users of the Location APIs get 1 million transactions over a lifetime. 1 million sounds a lot but it soon mounts up. Registered users get 2 million transactions. Per month. Plus a whole lot more.

Why are you so pro Nokia Maps?

A disclaimer is in order. I work for Nokia’s Location & Commerce group, that produces Nokia Maps. I see what goes into the map and what gets displayed. I’m very pro Nokia Maps for just this reason.

What about other maps providers? Google or OpenStreetMap?

WP Quadratum uses Mapstraction to support multiple maps providers. If Nokia Maps isn’t your thing, you can choose from maps from Google or from OpenStreetMap via CloudMade or OpenLayers.

But what about Bing Maps, MapQuest or CloudMade’s Leaflet?

Right now, all of these maps providers are supported by Mapstraction but they have issues when the sidebar’s widget map is so small (200px by 200px by default). As and when these issues are resolved in Mapstraction, they’ll be supported by a future release of the plugin.

Can I change the format of the strapline that appears under the checkin map?

Yes. The wp_quadratum_strapline filter is for just this purpose. The filter is passed the default strapline as well as the URL to the Foursquare venue checked in at, the name of the venue and the date and time of the checkin as a UNIX timestamp. See the Filter Support And Usage section for more information.

I want to amend/hack/augment this plugin; can I do the same?

Totally; this plugin is licensed under the GNU General Public License v2 (GPLV2). See http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt for the full license terms.

Where does the name WP Quadratum come from?

WP Quadratum is named after both the Latin words quattor, meaning four and quadratum, meaning square.

What’s Changed?

The current version is 1.2 (2012.11.06)

v1.2.0

  • Released: 2012.11.06
  • Added: Support for the wp_quadratum_strapline filter.
  • Added: Enqueue non-minified versions of the plugin’s CSS and JS files if WP_DEBUG or WPQUADRATUM_DEBUG are defined.
  • Other: Updated to latest versions of WP_PluginBase and WP_MXNHelper.
  • Other: Moved all submodule classes/libraries from the plugin’s root directory to /includes.

v1.1.0

  • Released: 2012.07.01
  • Added: Support for Nokia, CloudMade, Google and OpenLayers maps via Mapstraction
  • Added: Split plugin settings and options into Foursquare, Maps, Defaults and Colophon tabs
  • Added: [wp_quadratum] shortcode to allow a checkin map to be embedded in posts and pages.
  • Fixed: Support for Internet Explorer compatibility for Nokia Maps.

v1.0.2

  • Summary: Minor fixes to widget HTML structure
  • Fixed: Non W3C/HTML4 compliant widget code which caused the map not to be displayed when viewed with Internet Explorer

v1.0.1

  • Summary: Minor fixes to PHP base class.
  • Fixed: An issue with an old version of WP_PluginBase, the PHP class which WP Quadratum extends.

v1.0

  • First version of WP Quadratum released