At the time this plugin was first created, it seemed there was no easy way to share lists of gathered links on a WordPress blog. This plugin provides the shortcode ‘links’. This shortcode displays a list of all links having specified characteristics in your post, for example all links in a specific link category. By default it includes a Facebook Like button for every link, but this can be disabled. The shortcode follows a customizable template to display your links. Below you will find more information on how that works.
If you have comments, questions or feedback about this plugin, please use the forum on wordpress.org to contact us.
You can download the plugin from wordpress.org or add it from within your wordpress admin page by searching for “links shortcode”.
The Links Shortcode “manual”
There are basically three configurable sections when using the Links shortcode plugin.
The rest of this page goes into a little bit more detail on how to use the links template using these three sections. Also it describes how to use the Links shortcode in excerpts. It is work in progress, but I hope it is already useful. Apart from the three configurable sections, the following topics will be addressed:
- Optional elements in templates
- Examples of templates
- Known issues with this plugin for which I could use your help
The Links shortcode
A shortcode in WordPress is a code between [ and ] which is interpreted by WordPress or a WordPress plugin and replaced by content accordingly. The Links shortcode plugin replaces the [[links]] shortcode by the links which you manage in the “Links” section of the WordPress admin interface. Without changing default settings or template it will show a list of all links with their title, description and a Facebook like button. The title will link to your link’s url.
Like some other shortcodes, the Links shortcode accepts options. For example:
[[links category_name="Blogroll"]]
This option limits the list of links shown to only the links that are in the category named “Blogroll”.
The following options are available with their defaults:
- fblike: Show the facebook Like button (default ‘1’, to disable set to any value other than ‘1’)
- fbrecommend: Show the Facebook Recommend botton (default ”, to enable set to ‘1’)
- orderby: Order the links by (default ‘name’). Use the value ‘order’ to order links by order specified with ‘My Link Order’ plugin.
- order: How to order, ASC or DESC (default ‘DESC’)
- limit: Limit the number of links shown (default ‘-1’, which means no limit)
- category: Comma separated list of link category ID’s
- category_name: Category name of a catgeory of links to show. Overrides category parameter.
- hide_invisible: Hide links marked as not visible (default ‘1’, yes)
- include: Comma separated list of numeric link IDs to include. If ‘include’ is used, the category, category_name, and exclude parameters are ignored.
- exclude: Comma separated list of numeric link IDs to exclude.
- search: Shows all links matching this search string. It searches url, link name and link description.
So, the following example will show only 5 links from the category blogroll and a Facebook recommend button per link.
[[links category_name="Blogroll" fbrecommend="1" limit="5"]]
Default settings
Because it can be quite cumbersome to repeat the different options when you use multiple Links shortcodes throughout your blog, the plugin offers a settings page which can be found under the Settings menu in the WordPress admin interface.
These default settings can be overruled on the shortcode itself, as described in the previous section.
Links shortcode template
As mentioned earlier, the plugin uses a template to display links. On the settings page this template can be changed.
The template consists of three sections. These are marked as follows:
- How to display the links?
- Provide an optional text or html to display before the links
- Provide an optional text or html to display after the links
The most important section is the first one. In this section you can specify how each link will be displayed. The interesting thing is that you can do that using a syntax that includes something that looks like shortcodes. A template consists of HTML and link properties. Each property of a link can be inserted anywhere in your template. Each property looks like this: [[link_property]].
The following properties are available: [link_url], [link_name], [link_image], [link_target], [link_category], [link_description], [link_visible], [link_owner], [link_rating], [link_rel], [link_notes], [link_rss], [fb_button] and [date]. The properties do not have options like some normal shortcodes do.
NB: The [date] property is a special property that is derived from the link name. If the Name starts with a date, formatted as: yyyy-mm-dd followed by ‘:’, a separate property for the date is available.
NB: For advanced users: When using ‘Andy’s Link Last Edited Meta Box‘, you can use an extra field [link_updated] to display the date a link was last updated. Otherwise this field will be empty.
NB: Due to the way links logic is implemented in WordPress, some properties, like the [link_category] might not be available at all times. (I plan to dive into this later.)
Optional elements in templates
For cases in which a link does not have a certain property defined, like a link_image, the Links shortcode template provides a mechanism to use alternative HTML code.
The format is as follows:
[optional xxx||yyy]
If xxx contains a property that is not available for a certain link, the alternative HTML code yyy is displayed instead. If no HTML code should be displayed instead, leave yyy empty:
[optional xxx||]
For example, the following will display the description of a link followed by a line break, but if the link does not have a description also no line break is displayed:
[optional [link_description]
||]
Examples of templates
A list of links
To show all links in a list with a Facebook like button, use the following main template:
NB: For compatibility reasons, in the example above in case you choose not to include a Facebook button, the plugin will automatically correct the DIV class from ‘links_sc_fb’ to ‘links_sc’ for optimal spacing. For this template, leave the ‘before’ and ‘after’ template fields empty.
Links in a table
To show all links in a table with images in a separate column at the left if available, use the following main template:
[optional ||]
Enter the following in the ‘before’ field:
Known issues
Shortcode shows nothing: Template erased
In some cased the Links shortcode template has been found to be erased (made empty) randomly, resulting in links not to be shown anymore. If you encounter this issue, please send me a list of all plugins you use and any other information that could be of help to me in solving this problem.
[link_category] not shown
Due to the way links logic is implemented in WordPress, some properties, like the [link_category] might not be available at all times. I plan to dive into this later, but if you have any suggestions on why and how, please let me know.
Shortcodes in excerpts
This is not really an issue, it is behavior by design in WordPress: Normally shortcodes are not processed when displaying post excerpts (the small summary of your post). If you want to use the Links shortcode (or any other shortcode) in excerpts, add the following two lines to your functions.php file of your template:
add_filter( 'the_excerpt', 'shortcode_unautop'); add_filter( 'the_excerpt', 'do_shortcode');