Shortcodes
From Global Voices Wiki
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.
Contents |
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.
[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.
Example uses
[gvinlinerss feed_url="http://simianuprising.com/feed/" count="10" show_excerpts="1" title="Recent posts from Simian Uprising RSS"]
Show the titles and excerpts of 10 items from that feed. The heading above the box will say "Recent posts from Simian Uprising RSS" instead of the default title from the feed itself.
[gvinlinerss feed_url="http://solanasaurus.com/feed/" site_name="Solana Larsen" hide_title="1"]
Show headlines only for items in this feed. The site name was specifically set to override the title from the feed, and the heading above the widget will not be shown.
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="1" to display the date on each feed item. Default "0".
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] Will show a listing of WordPress 'pages' based on the criteria given. It can show excerpts or just titles.
Example Uses
[gvpages parent="self" orderby="modified" excerpt_length="25"]
Show all children of the current page. Order them by their last modified date and show excerpts (the default format value) limited to 25 words. Because no count is set all pages that are children of the current one will be returned.
[gvpages format="links" count="5" orderby="rand"]
Show only 5 pages in link format (a <ul>). They will be selected randomly from all pages.
Arguments
format "links" or "excerpt" (excerpt is default). Links will show only the titles of each page linked to the page. Excerpt will show any post-thumbnail, the title and an excerpt of the content.
parent Get only the children of this page. Usually a page id (from the edit url of a page), though if parent="self" then children of the current page will be returned.
count How many pages to show. Leave empty to show all pages that fit the other criteria.
excerpt_length How many words to show in content excerpts. Default is 30. This is ignored for format="list".
orderby How to sort the pages, can be any of the following:
- modified
- author
- title
- menu_order
- parent,rand
order Which way to sort based on orderby. Can only be ASC or DESC
[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 use the user_filter argument to select a specific set of authors.
Example Uses
[gvuserlist type="summary" user_filter="active=no"]
Show summaries (avatar + postcount + joined date) of all users who are not active (posted recently).
[gvuserlist type="profile" user_filter="avatar=any"]
Show a full profile for each user (name, avatar, bio, post count) and filter the list of users to only show those who have some kind of avatar.
Arguments
type - Which format to use. Choices are:
- profile Elaborate bio section with avatar, name, bio and various links.
- summary Small section with avatar, name, post count and joined date.
- avatars Show only avatars linked to the author pages.
- names Simple text list of user's names linking to their author pages.
after - text to show between links in 'names' format. Default is ", " (i.e. they are separated by commas").
user_filter - Filter arguments to limit the users to certain criteria.
- active=yes and active=no will limit the list to users who are or aren't 'active' based on how recently they've posted (currently this means people who have or haven't posted in the last 90 days). This can be useful for separating users into two groups and giving more prominence to those who have been posting recently. To show profiles of only users who have posted in the last 90 days use:
[gvuserlist type="profile" user_filter="active=yes"]
- avatar=any will only show authors who have uploaded an or have a gravatar. This is useful if the goal is to show photos of users, as it will avoid showing empty avatar boxes. This is especially important with the 'avatars' type! To show avatars of only users who HAVE an avatar use this:
[gvuserlist type="avatars" user_filter="avatar=any"]
- Multiple Filters? You can add multiple filters using the & symbol in between. So if you wanted users with avatars who are also active then you would add the following in the shortcode user_filter="active=yes&avatar=any"
[gvavatar]
[gvavatar] Shows the avatar of just one user. The avatar links to their full profile page.
Example Uses
[gvavatar id="12"]
Shows the avatar of the user with user_id 12.
[gvavatar name="Solana Larsen" size="35"]
Shows the avatar of the user with the exact login name of 'Solana Larsen' and resizes the image to 35px 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 75px. Local avatars should be max 75px, but Gravatars can be larger.
[gvbadges]
[gvbadges] Is replaced with a set of badges we want people to add to their sites along with easily copyable html code for adding our badges to their sites. It works based on 'sets' of badges defined by the theme's functions.php file (ask jer about this).
Example uses
[gvbadges id="general"]
Show badges and html code for the 'general' set, which has a plain GV logo or a language-specific one for Lingua.
[gvbadges id="contributors"]
Show badges and html code for badges in the 'contributors' set, which has the "Author" and "Editor" badges.
Arguments
id The slug name of a set of badges.
[gvrsslist]
[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 result is two lists <ul class="rss-list"> of category names and links to their RSS feeds. They should be styled to form two columns.
Example Uses
[gvrsslist taxonomy_slug="regions"]
Show all region categories and their rss feeds.
[gvrsslist taxonomy_slug="special" show_jss="true"]
Show Special Topic categories as well as their JSS 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
show_jss - If set to true this will also add links to JSS pages for each category. Only use this if JSS is enabled on the site.
[gv_stats_page]
[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 specified time_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_periods should 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_periods="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_periods - Must be a valid time_period from the gv_stats plugin. See choices in [gv_stats_page] docs above.
[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.
NOTE on old [gvpaypaldonate] shortcode
Previously we used [gvpaypaldonate] but that shortcode has been phased out, if you have it in your site please switch it to [gvpaypal] instead, using the arguments outlined above.
[gvflattr]
[gvflattr] will be replaced with a Flattr donation button that will direct funds to GV.
The default button will use the site's home URL, title and description as the object being "flattred". Entering a custom URL, title AND description will make the button use that profile instead.
Example Uses
[gvflattr]
Show the default flattr button linking to profile of site homepage.
[gvflattr button="compact"]
Same default button but with compact style, smaller and more horizontal.
[gvflattr url="http://advocacy.globalvoicesonline.org" title="Global Voices Advocacy" description="{Description should be a short paragraph about the object being flattred.}"]
Shows a Flattr button which will flattr a different/specific URL. All three of url, title, and description must be passed in together to point the button to a particular URL.
Arguments
button Type of button to show. Default is "large" version with big number bubble above button. Use compact to get the thin, horizontal button layout.
url Alternative URL to be flattred. Must be used with title and description.
title Title of alternative URL to be flattred. Must be used with url and description.
description Description of alternative URL to be flattred. Must be used with url and title.
[gvgooglemap]
[gvgooglemap] will be replaced with an embedded Google Map based on the 'src' attribute, which should be the "Link" to a Google Map. You can also define 'width' and 'height' values to control display of the map.
Always test the embed to make sure it looks right. You may have to play with zoom level and placement to make it look good!
Any use of [gvgoooglemap] should be accompanied by a text link to the map in case the embed fails.
Example Uses
[gvgooglemap src="http://maps.google.ca/maps?x=YZABC"]
Show default display of the map at the url specified by src.
[gvgooglemap src="http://maps.google.ca/maps?x=YZABC" height="600px"]
Same map but set to be 600px tall instead of default 350px.
Arguments
src URL of the map to embed. Use the "Link" button in Google maps to get the appropriate URL.
width Default 400. Width of the embed in pixels.
height Default 350. Height of the embed in pixels.
[gvgcal]
gvgcal is a simple shortcode that gets replaced with the "dates and events calendar" Google Calendar embed used on GV English. It shouldn't be used anywhere other than that.
[gvconconform]
[gvconconform] is a simple shortcode designed to be replaced with the sign up form for constant contact. It isn't localized and should only be used on English GV.
