WordPress Shortcodes

This page should document all major [shortcodes] set up to work on Global Voices sites.

What's a shortcode? Shortcodes are words wrapped in square brackets that you put into a post, page or text widget that get replaced at load time by some complex content or HTML. Default WordPress shortcodes include [caption] which gets used when you insert a photo with a text caption into a post.

[WordPress Shortcodes] added by the GV Plugin to various GV sites. These aren't part of WordPress, they are things added by Jeremy Clarke.

Most GV content does not require these shortcodes, they are mostly designed for special occasions and special pages that are only created once for each site.

BEWARE VISUAL EDITOR

The examples below in grey boxes are wrapped by the wiki in HTML <pre> tags. If you copy them and paste them into the HTML view of WordPress then nothing bad will happen. If you paste them into the Visual editor though than anything could happen! So please be careful and only paste these using the HTML editor or else just type them in yourself.

If you ever have strange results with shortcodes remember to check how they look in the HTML view and that they aren't accidentally wrapped in some wierd HTML.

[gvavatar]

[gvavatar] Shows the avatar of just one user. The avatar links to their full profile page and floats next to text.

Gvavatar-screenshot

Example Uses

[gvavatar id="12"]

Shows the avatar of the user with user_id 12.
[gvavatar name="ethan-zuckerman" size="120"] Shows the avatar of the user with the exact login name of ‘Ethan Zuckerman’ and resizes the image to 120px square.

Arguments

id A user id. You can tell a user id by looking at the ‘edit user’ url of a user.

name Login name of a user. This is their login name that is present in their author URL.

size Size in pixels of the image. Default is 96px. Avatars shouldn't be more than 240px, and should always be a multiple of 24.

[gvuserlist]

[gvuserlist] is replaced with a listing of authors from the current site. It supports several formats for full bios, summaries, avatars and just links. You can also show a subset of users by limiting their number or filtering for activity or whether they have avatars.

Example Uses

[gvuserlist] Default arguments show all users in the ‘summary’ type (show avatar, name and post count).
[gvuserlist type="avatars" has_avatar='1' limit='16']

Show “avatar” format (just author photos in a grid) and use has_avatar='1′ to ONLY show authors that have uploaded an avatar (avoids generic placeholder avatar). Also set limit='16’ so that a maximum of 16 avatars will be shown.
[gvuserlist type="text" active='no'] Show ‘text’ type which is just usernames and limit results to inactive users (haven't posted in the last 90 days).

Gv-ar-userlist

[gvuserlist] showing ‘summary’ type listing.

Arguments

type – Which format to use. Choices are:

  • profile Full bio with avatar, name, bio and various links (not recommeded).
  • summary Avatar, name and post count.
  • avatars Show only avatars linked to the author pages.
  • names Simple text list of user's names linking to their author pages.

active – “yes” or “no”. Yes will limit the list to only authors with a post published in the last 90 days, no will show only users that haven't posted in the last 90 days. This is useful for showing active users prominentely (‘summary’ type) while showing older users more efficiently (‘names’ type). Default is to show all users regardless of active status.

has_avatar Setting this to 1 will limit results to users that have uploaded an avatar, useful for lists of sample users to avoid generic icons.

has_post Set to “0” to include all users even if they haven't posted. Default only shows users with at least one post.

user_ids Comma-separated list of user ID numbers (found in a user's edit profile URL), e.g. user_ids=”1,6,14″ Only these users will be shown.

limit Maximum number of users to show. Default shows all users that match other criteria.

random Default false. Set random='1′ to shuffle results before display.

size Avatar size in pixels. Applies to ‘avatars’ format ONLY. Note that display size depends on the container, so this is really “maximum” size.

separator – text to show between links in ‘names’ format. Default is “, ” (i.e. they are separated by commas”).

[gvuser]

[gvuser] is replaced with the profile of a single user on the current site. It is just like [gvuserlist] described above but for one user at a time.

Gvuser-shortcode

[gvuser] shortcode used in a sidebar widget

Example Uses

[gvuser name='ethanzuckerman'] Display user profile for user with login name ‘ethanzuckerman’. Default arguments show user in the ‘summary’ type (avatar, name and post count).
[gvuser id='12' type="profile"] Show the user with ID 12 (find user IDs in the URL of their ‘edit user’ link) and use the profile format (avatar, name and full bio).

Arguments

id User ID of a user to show.

name Login name of a user to show.

type – Which format to use (same as [gvuserlist] see above). Default is ‘summary’ (avatar, name and post count)

[gv_map]

[gv_map] is replaced with a map of geolocated posts from the site. It uses the Geo Mashup plugin to load a Google map that can show the current post's location or other posts that are nearby or related.

Gv-map-demo

Single post map generated from [gv_map map_content='single' align='right' size='small']

Example Uses

[gv_map] Display a map. This example is missing map_content so it will guess which type of map to show, this is not recommended.
[gv_map map_content='single'] Displays map with a pin for the coordinates of the current post (map_content='single’). By default maps are the width of their container.
[gv_map map_content='global' align='right'] Align the post right like an image, it will be 50% width. Will show a global map because of map_content='global’
[gv_map map_content='single']This is a caption that will show below the map[/gv_map]

Show the current post map by adding a caption between the [gv_map] and [/gv_map] tags.

Arguments

map_content Map type:

  • global – All posts
  • single – Current post only
  • contextual – Other posts loaded on this page.

size Control height of map, default “medium”.

  • small
  • large

align Float the map left or right at 50% width like an image. Default full width.

  • right
  • left

caption Show a text caption below map. Caption can also be set between the [gv_map] and [/gv_map] tags where links can be added.

zoom Amount of map to show from 0-20, Default is “auto”. Very tricky to get right.

limit Max number of pins to show in map.

max_width Max-width in px or % for container. Limit the maximum width to a specific amount.

map_type Visual tile set. Default is in site configuration or G_NORMAL_MAP.

  • G_NORMAL_MAP
  • G_SATELLITE_MAP
  • G_HYBRID_MAP
  • G_PHYSICAL_MAP

[gvinlinerss]

[gvinlinerss] displays headlines or excerpts of items from an RSS or Atom feed. It has many options to control display. It has the same basic settings as the GV Banner RSS widget, but for use inside post or page content.

Gvinlinerss-shortcode-example

Example uses

[gvinlinerss feed_url="https://advocacy.globalvoicesonline.org/feed/" count="10" show_excerpts="1"] Show a feed with 10 items and show excerpts as well as the default titles and dates.
[gvinlinerss feed_url="https://globalvoicesonline.org/feed/" show_dates="0" hide_title="1"] Show a feed but hide dates on headlines and the heading above the widget.

Arguments

feed_url The url of an RSS feed. Mandatory

count How many posts to show. Default: 5

show_excerpts Set show_excerpts=”1″ to show the first couple lines of item content after item titles. Default “0” (headlines only).

show_dates Set show_dates=”0″ to hide the date on each feed item. Default “1”.

show_featured_image Set show_featured_image=”0″ to hide thumbnails/featured-images if they are present in feed. Default “1”.

rss_icon Set rss_icon=”0″ to hide the orange RSS icon in the heading. Default “1”.

title Optional title to display in heading above feed items. Default is site name from the feed itself.

link_title Set link_title=”0″ to disable the link on the heading to the site_url. Default is “1” (make heading a link)

hide_title Set hide_title=”1″ to hide the top heading completely. This inherently overrides the ‘rss_icon’, ‘title’ and ‘link_title’ arguments because the title won't be showing.

site_name Optional site name to override title from aggregated feed. Should describe the source site, and can be different from ‘title’ if title is not the same as the site's actual name. Used in link hover text.

site_url Optional site home url to override the one in the aggregated feed. This should point to the non-RSS homepage of aggregated items. Note that RSS feeds for categories will have the homepage, not the category homepage, as the default URL, so if you are aggregating a category feed you should set the site_url manually to the category listing URL.

banner_url Optional url of a banner image (gif/png/jpg)to show above headlines. Should be 425px wide by 65px high. Right-half of the banner will be cut off when window is thin, so important stuff should be in the left-250px

[gvpages]

Gvpages

[gvpages] shortcode showing children of Special Coverage

[gvpages] Will show a listing of WordPress ‘pages’ based on the criteria given and display options. By default it shows all pages on the site in “post summary” format (title, featured image, excerpt).

Example Uses

[gvpages orderby="modified" show_thumbnail="0"]

Show all pages, but hide thumbnails.

[gvpages parent="self" count="5" orderby="modified"]

Show children of the current page, but only the first 5. Order them by their last modified date.

[gvpages page_ids="17, 18, 22"]

Show a list of specific pages using their post_id's.

[gvpages parent="self" orderby="menu_order" order="ASC"]

Show all children of the current page, sorted by their “menu_order” value, which can be controlled by the Simple Page Ordering plugin and with order=”ASC” so that they are sorted in the correct ascending order.

Arguments

parent Default none. Set parent=”self” to show children of the current page, otherwise pass a post_id to show children of that page.

page_ids Default none. Comma-separated list of post_id's for pages to show, like page_id=”1,9,33″. Only these pages will show.

count How many pages to show. Leave empty to show all pages that fit the other criteria.

show_excerpt Default 1. Set to 0 to hide excerpts.

excerpt_length How many words to show in content excerpts. Default is 30.

show_thumbnail Default 1. Set to 0 to hide featured images.

format Default ‘excerpt’. Set to ‘headline’ to use alternate formatting (recommended to use show_excerpt=0 and show_thumbnail=0 together for same effect).

orderby How to sort the pages, default ‘date’. Can be any of the following:

  • date – Date page was published.
  • modified – Date last updated.
  • title – Titles alphabetically.
  • menu_order – “Order” setting from Page Attributes box in editor.
  • parent – Page Parent for children pages.
  • rand – Random order

order Which way to sort based on orderby. Can only be ASC or DESC. Default is DESC which works well with orderby='modified’, use ASC instead for best results with orderby='menu_order’.

[gvrsslist]

Gv-rsslist

[gvrsslist] showing region categories.

[gvrsslist] will be replaced with a list of category rss feeds of a certain type. It always requires the taxonomy_slug argument to work, otherwise it will show an error. The output is shown in two columns to fit more items in a smaller space.

Example Uses

[gvrsslist taxonomy_slug="regions"]

Show all region categories and their rss feeds.

Arguments

taxonomy_slug – Must be part of the site's taxonomy. For the main GV site the acceptable slugs are:

  • regions
  • countries
  • topics
  • special
  • type

[gvtaxonomylist]

[gvtaxonomylist] will be replaced with a list of category/taxonomy terms. It always requires the taxonomy argument (like ‘category’ or ‘gv_geo’) to work, otherwise it will show an error. The output is shown in two columns to fit more items in a smaller space.

Example Uses

[gvtaxonomylist taxonomy='topics'] Show a list of all topic categories.

Arguments

taxonomy_slug – Natural or registered public taxonomy. For the main GV site the acceptable slugs are:

  • regions
  • countries
  • topics
  • special
  • type
  • categories

format – Format string:

  • list (default)
  • toggle-menu
  • text
  • collapsed

children_format – Format for sublistings of child terms with grandchildren (see Format options)

show_children – Whether to do full sub listings of children and their children.

get_terms_args – Optional array of arguments to pass to get_public_taxonomy_terms, overrides taxonomy definitions.

title – Override default title text.

hide_title Hide title entirely, default false.

column_count – How many columns to display for immediate children, default 1.

children_column_count – How many columns to display in sublists

[gvicon]

[gvicon] will be replaced with an inline text icon generated by the icon font used by the rest of the GV theme. The icons flow normally with text and should work as if they were a symbol typed with a keyboard.

Example Uses

[gvicon icon="twitter"] Show the ‘twitter’ icon at the default size (16px, should fit in a normal line of text).
[gvicon icon="feed2" align='right' size='48'] Show the ‘feed2′ icon (a variant of RSS icon of which there are two) aligned right (so it floats like an image) and 48px tall.

Arguments

icon – Slug name of the icon to show. See demo page which lists all options, the actual “slug” you need is the name of the icon without “icon-“, so to get “icon-bubble” you would use [gvicon icon='bubble']

size – Size of the icon in pixels. Default is 16px which should work when mixed into normal text. Use multiples of 12 when possible (24, 36, 48).

align – Float the icon like an image. Options: “right” or “left”. Default none (inline).

[gv_stats_page]

 

Gv-stats-screenshot

[gv_stats_page] showing Lingua Translation stats for all_time.

[gv_stats_page] will be replaced with a page of stats about posting on the site. It always requires the type parameter or it will fail. The resulting page will include the specifiedtime_periods (see below) as well as a form that can be used to specify a custom time period or date.

[gv_stats_page] should be used on it's own on a page, with an explanation at the top as to what the stats represent. It is best to choose a single time_period to show by default, and allow users to choose any other periods they want to know about.

Example Uses

[gv_stats_page type=”gv_stats_lingua_translations” time_periods=”all_time”] Show stats for the ‘gv_stats_lingua_translations’ report type (number of translations per site) with only one time_period “all_time” which shows all posts ever.

Arguments

type – Must be a valid stats_page_type from the gv_stats plugin. Current choices:

  • gv_stats_posts – All posts on the site per time period.
  • gv_stats_comments – Number of comments for each time period.
  • gv_stats_regions – Number of posts per Region category.
  • gv_stats_topics – Number of posts per Topic category.
  • gv_stats_languages – Number of posts per Language category.
  • gv_stats_groups – Number of posts by each editorial group.
  • gv_stats_lingua_translations – Number of translations by each Lingua site.
  • gv_stats_lingua_sources – Number of original “source” posts by each Lingua site.

time_periods – Time periods to show when the page is first loaded (other time periods can be selected from the form by the user). If left empty the default time_periods for the chosen stats type will be used, but you should always specify some. The value of time_periodsshould be either a single time_period code, or a comma separated list with no spaces like:

time_periods="this_month,this_year,all_time"

Current time_periods choices:

  • today
  • 1_day_ago i.e. Yesterday
  • 2_days_ago
  • this_week i.e. The week so far since Monday.
  • 1_week_ago i.e The week ending on the most recent Sunday.
  • 2_weeks_ago
  • this_month
  • 1_month_ago
  • 2_months_ago
  • 3_months_ago
  • past_6_months
  • past_year i.e. previous 365 days
  • this_year i.e. since January 1 this year
  • last_year i.e. Jan-Dec of the last calendar year.
  • all_time

[gv_stats_block]

[gv_stats_block] functions almost exactly like [gv_stats_page] but only shows a single time_period and does not include the form for viewing other periods. Like [gv_stats_page] it always requires the type parameter or it will fail. A single time_period is also mandatory.

Example Uses

[gv_stats_block type=”gv_stats_posts” time_period=”this_year”] Show stats for the ‘gv_stats_posts’ report type (All posts on the site) for the ‘this_year’ time period, which covers all posts since January 1 of this year.

Arguments

type – Must be a valid stats_page_type from the gv_stats plugin. See choices in [gv_stats_page] docs above.

time_period – Must be a valid time_period from the gv_stats plugin. See choices in [gv_stats_page] docs above.

[gvpaypal]

Gv-donate-button

A French donate button created with [gvpaypal]

[gvpaypal] will be replaced with a paypal donation button that will direct funds to GV. The text will automatically be the localized version of “Donate to Global Voices”, which can be overridden using the ‘text’ option.

The shortcode will also attempt to automatically set the ‘lang’ value for you based on the language of your lingua site. You can still set it manually if you want. PayPal also tries to detect the language of the browser and use that, so hopefully your readers will see a localized PayPal interface even if you don't.

Example Uses

[gvpaypal] Show the default donation button linking to paypal where the user can choose their own donation.
[gvpaypal text="Give us some love!"] Default paypal button but with alternate text.
[gvpaypal lang="fr" img="http://site.com/custom_image.jpg"] Link to French version of paypal).
[gvpaypal button_id="XXXXXXXXX"] Use a specific saved button (NOT FOR LINGUA)

Arguments

lang ISO code (fr, ar, es) to control the Paypal interface. If they do not support your language then English will be used.

text Button text to override default “Donate to Global Voices”

button_id Alphanumeric Paypal “saved button” ID to override the default.

[gv_instagram_feed]

[gv_instagram_feed] is replaced with the “feed” for an Instagram account, which ultimately means: show an embed of the most recent image. A  username argument is required to function.

Note: Don't use this to embed a specific Instagram post, instead see our Embedding Instagram instructions on the WordPress Posting Guide.

Example Uses

[gv_instagram_feed username='globalvoicesonline']

Show the “feed” (most recent post) from an Instagram account. By default hidecaption is true so the caption and like/comments buttons will be hidden.

[gv_instagram_feed username='globalvoicesonline' hidecaption="0"]

Show the same “feed” (latest post) but with hidecaption disabled, so the caption shows along with the like and comments buttons.

Arguments

username Instagram username who's latest post will be shown. (mandatory)

hidecaption Optionally set to 0. By default hidecaption="1" which hides the caption, comments and likes. The default is to hide captions because they can be very long and make the size unpredictable. If you know the captions will be reasonable set hidecaption="0"

[gv_twitter_follow_button]

[gv_twitter_follow_button] is replaced with a button to follow a Twitter account. By default it uses the Twitter account for the site, but if you pass a user argument, it will show that specific user instead.

Example Uses

[gv_twitter_follow_button]

Show follow button for the site (e.g. ). By default size is large and format is button.

[gv_twitter_follow_button user='jeremyclarke' format="link"]

Show a follow button for ‘jeremyclarke’ twitter user and use the link format.

Arguments

user Twitter username to display (defaults to sitewide value set in GV Settings)

format Displays as “button” by default, “link” also available.

size Default “large”, “small” and “medium” also available, but are not that much smaller.

[toc] and [no_toc]

These shortcodes are part of the Table of Contents plugin we use, which usually generates an automatic table of contents at the top of the post if there are several headings present.

[toc] will cause the ToC to be shown wherever you put the shortcode, rather than in the default location.

[no_toc] disables the ToC entirely, regardless of the number of headings in the article. Put [no_toc] anywhere you want in the post text, it will be invisible to readers.