readme.textile

July 21, 2016 ยท View on GitHub

h1. arc_meta

A "Textpattern":http://textpattern.com/ plugin for meta tags to improve site SEO and social marketing. arc_meta adds meta fields to your article, section and category forms.

Please note that this is a beta release for Textpattern 4.6!

h2. Requirements

  • Textpattern 4.6
  • PHP 5.3+

For earlier versions of Textpattern please use the 1.x versions of the plugin.

h2. Installation

To install go to the 'plugins' tab under 'admin' and paste the plugin code (found in the dist directory of this repository) into the 'Install plugin' box, 'upload' and then 'install'.

h2. Upgrading from v1.x to v2.x

If you are upgrading from an older 1.x version of the plugin I strongly recommend you backup your database beforehand. The latest version makes use of Textpattern's default meta description columns and the plugin will migrate descriptions from the arc_meta table before dropping the column from the plugin's table used by previous versions on installation.

When migrating data over to the core Textpattern tables it will first check that there is no existing data in the Textpattern description columns so as to not overwrite this data. It will only migrate descriptions where no meta description has been set in the core tables.

While this has been fully tested during the plugin's development you should still backup first. It is also recommended that you test the upgrade on a staging version of your site before applying to a live production version. If you encounter problems please log an issue.

h2. Usage

All of the following tags should be used within your templates' @@ tag.

h3. arc_meta_title

Outputs an SEO friendly @@ tag.

bc. <txp:arc_meta_title />

h4. Attributes

The @arc_meta_title@ tag attributes override the defaults. To set the default patterns used for the @@ tag goto the plugin's options page.

  • title -- use this to override the title tag's content
  • article_title -- sets the pattern for article page titles
  • comment_title -- sets the pattern for comment page titles
  • search_title -- sets the pattern for search results page titles
  • category_title -- sets the pattern for category page titles
  • section_title -- sets the pattern for section page titles
  • homepage_title -- sets the pattern for the homepage title
  • type -- override the content type for the title

h4. Title Tokens

To set a pattern for a page title you can use the following tokens:-

  • @%a@ -- article title, can only be used on article and comment pages
  • @%s@ -- section name, can be used on article and section pages
  • @%c@ -- category name, can be used on category pages
  • @%n@ -- site's name, can be used on all pages
  • @%t@ -- site's slogan, can be used on all pages
  • @%q@ -- search query, can be used on search results page

For example, you could define the pattern for an article page as:-

bc. %a | %n (%t)

This would output something like:-

bc. Welcome to Your Site! | My site (My pithy slogan)

h4. Examples

h5. Example Using the @section_title@ Attribute

bc. <txp:arc_meta_title section_title='%n / %s' />

Outputs on an 'Articles' section page:-

bc. My site / Articles

h5. Example Using the @title@ Attribute

bc. <txp:arc_meta_title title='Hello World' />

Outputs:-

bc. Hello World

h3. arc_meta_description

Outputs a meta description tag when a description has been set.

bc. <txp:arc_meta_description />

h4. Attributes

  • description -- overrides the description set using arc_meta's description field on the article Write page or section/category edit page
  • type -- override the content type for the meta description

h3. arc_meta_robots

Outputs a meta robots tag when robots have been set. When a site is in testing or debugging mode it will automatically output a 'noindex, nofollow' tag with your actual setting as a comment immediately after the tag for reference.

bc. <txp:arc_meta_robots />

h4. Attributes

  • robots -- overrides the robots instructions set using the meta robots field on the article Write page or section/category edit page
  • type -- override the content type for the robots meta data

h3. arc_meta_keywords

Outputs a meta keywords tag when keywords have been set (only works for articles).

bc. <txp:arc_meta_keywords />

h4. Attributes

  • keywords -- overrides the keywords set using the meta keywords field on the article Write page

h3. arc_meta_canonical

Specify the page's canonical URL. See Google's "Specify Your Canonical":http://googlewebmastercentral.blogspot.com/2009/02/specify-your-canonical.html for an explanation.

bc. <txp:arc_meta_canonical />

h4. Attributes

  • url -- overrides the default URL

h3. arc_meta_open_graph

Outputs meta tags for using Facebook Open Graph.

bc. <txp:arc_meta_open_graph />

Just including the above tag in your templates' @@ tag will output tags for the following:-

  • og:site_name -- your site name from your preferences
  • og:title -- the article's title, section name or category name
  • og:description -- your page's meta description
  • og:url -- your page's canonical URL
  • og:image -- the article's image

You can override the default values of any of these by passing a value to one of the tag's attributes defined below. To disable one of the tags just pass an empty attribute value (e.g. @title=''@).

h4. Attributes

  • site_name
  • title
  • description
  • url
  • image

h3. arc_meta_twitter_card

Outputs meta tags for using Twitter Cards.

bc. <txp:arc_meta_twitter_card />

Just including the above tag in your templates' @@ tag will output tags for the following:-

  • twitter:card -- 'summary' by default, can also be set to 'photo' for image content or 'player' for videos
  • twitter:title -- the article's title, section name or category name
  • twitter:description -- your page's meta description
  • twitter:url -- your page's canonical URL
  • twitter:image -- the article's image

You can override the default values of any of these by passing a value to one of the tag's attributes defined below.

To start using Twitter cards you will need to authorise them for your domain by "validating and applying":https://dev.twitter.com/docs/cards/validation/validator on the Twitter website. You will need to supply Twitter with a few details including the URL of a page with a complete Twitter card. It can take several days for Twitter to authorise your site.

h4. Attributes

  • card
  • title
  • description
  • url
  • image

h3. arc_meta_organization

Outputs Knowledge Graph social profiles script tag for an organisation.

bc. <txp:arc_meta_organization />

h4. Attributes

  • name -- Organisation's name
  • logo -- URL to organisation's logo (required, will throw an error if not set)
  • facebook -- URL to Facebook page
  • gplus -- URL to Google+ page
  • twitter -- URL to Twitter account

h3. arc_meta_person

Outputs Knowledge Graph social profiles script tag for a person.

bc. <txp:arc_meta_person />

h4. Attributes

  • name -- Person's name
  • logo -- URL to person's picture
  • facebook -- URL to Facebook page
  • gplus -- URL to Google+ page
  • twitter -- URL to Twitter account

h2. Admin

h3. Article Write Page

The plugin will add title and description fields to the Meta options. Use these to set your article's meta data.

If you set a title here it will be used in place of the article's title when replacing the @%a@ token for the @arc_meta_title@ tag.

The description will be used for the @arc_meta_description@ tag and for the descriptions used by the @arc_meta_open_graph@ and @arc_meta_twitter_card@ tags.

h3. Section and Category Pages

The plugin will add meta title and meta description fields to the section and category edit forms.

If you set a title here it will be used in place of the section's/category's name when replacing the ==%s/%c== token for the @arc_meta_title@ tag. When editing the homepage section the meta title will replace any pattern defined for the page title.

The description will be used for the @arc_meta_description@ tag and for the descriptions used by the @arc_meta_open_graph@ and @arc_meta_twitter_card@ tags.

h3. Plugin Options

From the plugin's options page you can set the default patterns used for the arc_meta_title tag. These can all be overridden when the tag is included in your page templates, but it may be easier to set the default patterns if you want to change the ones that come with the plugin when installed.

h2. Translations

The admin interface of this plugin has been translated into French thanks to "Nicolas Morand":https://github.com/NicolasGraph.