John James Jacoby

<p>This plugin is a library to connect your BuddyPress powered website to the XML or JSON Foursquare API.</p>


BP Foursquare API

An API to connect BuddyPress to Foursquare.

vicchi

<p>This plugin allows you to display your last Swarm checkin as a map widget on the sidebar or embedded via a shortcode in a post or page of your WordPress powered site.</p>
<p>Setting and options include:</p>
<ol>
<li>Associate your WordPress powered site with your <a href="https://foursquare.com/" rel="nofollow ugc">Foursquare</a> account using <a href="http://oauth.net/2/" rel="nofollow ugc">OAuth 2.0</a>, which keeps your personal information safe and secure.</li>
<li>Choose which map provider you want your checkin shown on; you can choose from:
<ol>
<li><a href="http://developer.here.com/javascript_api" rel="nofollow ugc">HERE Maps</a></li>
<li><a href="https://developers.google.com/maps/documentation/javascript/" rel="nofollow ugc">Google Maps v3</a></li>
<li><a href="http://msdn.microsoft.com/en-us/library/gg427610.aspx" rel="nofollow ugc">Bing Maps v7</a></li>
<li><a href="http://www.openstreetmap.org" rel="nofollow ugc">OpenStreetMap</a> from <a href="http://leafletjs.com/" rel="nofollow ugc">Leaflet</a></li>
<li><a href="http://www.openstreetmap.org" rel="nofollow ugc">OpenStreetMap</a> from <a href="http://openlayers.org" rel="nofollow ugc">OpenLayers</a></li>
<li><a href="" rel="nofollow ugc">OpenStreetMap</a> from <a href="http://developer.mapquest.com/web/products/open/sdk" rel="nofollow ugc">MapQuest</a></li>
</ol>
</li>
<li>Add your maps API key(s) for your chosen map provider; HERE, Google, Bing and MapQuest maps all require API keys.</li>
<li>Choose the width and height of the widget and map on the sidebar. The width and height can be specified either as pixels (<code>px</code>) or as a percentage.</li>
<li>Choose the zoom level of the map display.</li>
</ol>
<p>The <em>strapline</em> text containing the venue name, venue URL and timestamp of your last Swarm checkin can be customised via the plugin’s filters. See the <em>Filter Support And Usage</em> section for more information.</p>
<p>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.</p>
<h3>Shortcode Support And Usage</h3>
<p>WP Quadratum supports two shortcodes and three shortcode aliases; <code>[wp_quadratum_map]</code> to expand the shortcode in a post or page and replace it with the checkin map and <code>[wp_quadratum_locality]</code> to allow you to embed aspects of your last checkin in a post or page.</p>
<h4>[wp_quadratum_map]</h4>
<p>Adding this shortcode to the content of a post or page as content, expands the shortcode and replaces it with a checkin map.</p>
<p>The shortcode also supports multiple <em>attributes</em> which allow you to customise the way in which the shortcode is expanded into the checkin map:</p>
<ul>
<li>the <code>width</code> attribute</li>
<li>the <code>width_units</code> attribute</li>
<li>the <code>height</code> attribute</li>
<li>the <code>height_units</code> attribute</li>
<li>the <code>zoom</code> attribute</li>
</ul>
<p>** The “width” Attribute **</p>
<p>The <code>width</code> attribute, in conjunction with the <code>height</code> attribute specifies the width of the map to be inserted into a post or page. If omitted, the map width defaults to a value of <code>300</code>.</p>
<p>** The “width_units” Attribute **</p>
<p>The <code>width_units</code> attribute, specifies how the value specified in the <code>width</code> attribute should be interpreted. Valid values for this attribute as <code>px</code> and <code>%</code>, denoting that the <code>width</code> attribute should be interpreted in pixels or as a percentage respectively. If omitted, this attribute defaults to a value of <code>px</code>.</p>
<p>** The “height” Attribute **</p>
<p>The <code>height</code> attribute, in conjunction with the <code>width</code> attribute specifies the height of the map to be inserted into a post or page. If omitted, the map height defaults to a value of <code>300</code>.</p>
<p>** The “height_units” Attribute **</p>
<p>The <code>height_units</code> attribute, specifies how the value specified in the <code>height</code> attribute should be interpreted. Valid values for this attribute as <code>px</code> and <code>%</code>, denoting that the <code>height</code> attribute should be interpreted in pixels or as a percentage respectively. If omitted, this attribute defaults to a value of <code>px</code>.</p>
<p>** The “zoom” Attribute **</p>
<p>The <code>zoom</code> attribute specifies the zoom level to be used when displaying the checkin map. If omitted, the zoom level defaults to a value of <code>16</code> which is roughly analogous to a neighbourhood zoom.</p>
<h4>[wp_quadratum]</h4>
<p>The <code>[wp_quadratum]</code> shortcode is an alias for the <code>[wp_quadratum_map]</code> shortcode and has the same functionality.</p>
<h4>[wpq_map]</h4>
<p>The <code>[wpq_map]</code> shortcode is an alias for the <code>[wp_quadratum_map]</code> shortcode and has the same functionality.</p>
<h4>[wp_quadratum_locality]</h4>
<p>Adding this shortcode to the content of a post or page, expands the shortcode and replaces it with information about your last Foursquare checkin. The information to be displayed is selected by the shortcode’s <code>type</code> attribute, which allows you to select the venue name, address, region, postal code, coordinates, timezone or timezone offset.</p>
<p>By default, the <code>[wp_quadratum_locality]</code> shortcode and the <code>[wpq_locality]</code> alias are disabled. This is because not all Foursquare venues contain the full scope of locality elements that the shortcode supports (the minimum requirements for a Foursquare venue are name, category and coordinates). To backfill any missing venue elements, WP Quadratum uses a <em>reverse geocoding</em> service from <a href="http://www.factual.com/" rel="nofollow ugc">Factual</a> to supply the missing information.</p>
<p>To enable the <code>[wp_quadratum_locality]</code> shortcode, from the Dashboard navigate to <em>Settings / WP Quadratum</em> and click on the <em>Shortcodes</em> tab. Select the <em>Enable Locality Shortcode Usage</em> checkbox and the <em>Factual OAuth Settings</em> meta-box will appear. You’ll then need to sign up for a <a href="https://www.factual.com/api-keys/request" rel="nofollow ugc">Factual API key</a> after which you’ll be given an <em>OAuth Key</em> and <em>OAuth Secret</em>. Copy and paste these into the <em>Factual OAuth</em> text fields and click on <em>Save Shortcode Settings</em>. You’ll now be able to use the <code>[wp_quadratum_locality]</code> shortcode or its alias.</p>
<p><strong>The “type” Attribute</strong></p>
<p>The <code>type</code> attribute specifies the element of your last Foursquare checkin that is to be displayed in a post or page and can take one of the following values:</p>
<ul>
<li><code>venue</code> – the name of the last Foursquare venue you checked into.</li>
<li><code>address</code> – the street address of the venue; not including the region, locality or postal code.</li>
<li><code>region</code> – the region of the venue; the geographic context of the region will vary from country to country but is roughly analogous to the venue’s city.</li>
<li><code>postcode</code> – the postal code of the venue, if the country or region supports postal codes.</li>
<li><code>coordinates</code> – the geographic coordinates of the venue, in the form latitude,longitude.</li>
<li><code>timezone</code> – the timezone name of the time of the checkin, such as <code>Europe/London</code>.</li>
<li><code>tzoffset</code> – the offset from GMT of the time of the checkin, in the form GMT[-+]hours, such as GMT-1 or GMT+2.</li>
<li><code>locality</code> – the locality of the venue; the geographic context of the locality will vary according to country, but is roughly analogous to the town or neighbourhood.</li>
</ul>
<p>If the <code>type</code> attribute is not supplied, or if the value of this attribute is not one of the above values, <code>type="locality"</code> will be assumed. The shortcode’s replacement value can be modified via the plugin’s <code>wp_quadratum_locality</code> filter; see the <em>Filter Support and Usage</em> section for more information.</p>
<h4>[wpq_locality]</h4>
<p>The <code>[wpq_locality]</code> shortcode is an alias for the <code>[wp_quadratum_locality]</code> shortcode and has the same functionality.</p>
<h3>Filter Support And Usage</h3>
<p>WP Quadratum supports three filters, which are described in more detail below. The plugin’s filters allow you to:</p>
<ul>
<li>change the descriptive text that appears immediately below the map when displayed via the plugin’s widget or shortcode.</li>
<li>gain access to the checkin metadata that is returned from the Foursquare API</li>
<li>change the output of the [wp_quadratum_locality]` shortcode</li>
</ul>
<h4>wp_quadratum_checkin</h4>
<p>Allow a filter hook function to gain access to the checkin metadata that is returned from the Foursquare API and which is used to build the checkin map and strapline. It’s important to note that the implementation of this filter isn’t strictly a WordPress filter per se. The user defined hook function is passed only the checkin metadata. Any changes made to the metadata will not be reflected in the output of the plugin’s or shortcode’s map, nor will any return value from the hook function be honoured by the plugin. The filter will be called before the <code>wp_quadratum_strapline</code> filter, if used, allowing you to store the checkin contents and use them within the <code>wp_quadratum_strapline</code> filter hook.</p>
<p>The contents of the checkin data this filter can access are a <code>Checkin Response</code> object, which is documented on the <a href="https://developer.foursquare.com/docs/responses/checkin" rel="nofollow ugc">Foursquare Developer Site</a>.</p>
<p><em>Example:</em> Store the contents of the Foursquare checkin that the plugin will be to display the checkin map.</p>
<pre><code>$last_checkin = null;
add_filter('wp_quadratum_checkin', store_last_checkin, 10, 1);
function store_last_checkin($checkin) {
    $last_checkin = $checkin;
}
</code></pre>
<h4>wp_quadratum_strapline</h4>
<p>Applied to the strapline that is displayed via the plugin’s widget or shortcode. The strapline is the text that appears immediately below the checkin map.</p>
<p><em>Example:</em> Change the date and time formatting in the strapline</p>
<pre><code>add_filter('wp_quadratum_strapline', 'format_strapline', 10, 2);
function format_strapline($content, $params) {
    // $params = array (
    //      'venue-url' => '4Sq venue url for checkin',
    //      'venue-name' => 'checkin venue name',
    //      'checked-in-at' => 'timestamp of checkin'
    //  );

    $strapline = '<h5>Last seen at <a href="' . $params['venue-url'] . '" target="_blank">' . $params['venue-name'] . '</a> on ' . date('l jS \of F Y h:i:s A', $params['checked-in-at']) . '</h5>';
    return $strapline;
}
</code></pre>
<h4>wp_quadratum_locality</h4>
<p>Applied to the replacement content of the <code>[wp_quadratum_locality]</code> shortcode immediately before the shortcode is replaced. The filter’s hook function is passed two arguments; the shortcode’s value and corresponding <code>type</code> attribute.</p>
<p><em>Example:</em> Wrap each invocation of the <code>[wp_quadratum_locality]</code> shortcode in a <code>div</code> whose class includes the attribute type.</p>
<pre><code>add_filter('wp_quadratum_locality', 'format_locality', 10, 2);
function format_locality($value, $type) {
    $class = 'wp-quadratum-locality-' . $type;
    return '<div class="' . $class . '">' . $value . '</div>';
}
</code></pre>


WP Quadratum

Display your last Swarm checkin as a map widget in the sidebar or embedded in a post or page, fully authenticated via OAuth 2.0.

BP Foursquare API vs WP Quadratum