Aspen Shortcodes and Widgets Plugin Documentation -- Version 1.0

Table of Contents

Plugin Summary

The Aspen Shortcodes and Widgets Plugin provides a collection of shortcodes to allow you to easily add extra content and features to your regular content. These shortcodes will work with almost any WordPress theme. Some of the shortcodes (e.g., [aspen_show_posts]) have some optimizations to work with the Aspen Theme and the Aspen S&W theme.

While these shortcodes should prove useful with most any theme, one of the goals of these shortcodes is to provide an alternative to users of the Aspen S&W theme. This plugin supports most Weaver II shortcodes (but not Weaver II Pro shortcodes), allowing for a smooth transition from Weaver II to other themes.

Importat Note about Shortcode Names

In this documentation, all the shortcodes are described using the [aspen_xxxx] name of the shortcode. Using the [aspen_] prefix will help to be sure there are no conflicts with other, similar shortcodes. If you wish, you can check the "Use generic names" option on the OPTIONS tab, and all the shortcodes will respond to just the main part of the name - [show_posts] instead of [aspen_show_posts].

And for Weaver II compatibilitty, all the shortcodes have an equivalent [weaver_xxx] form.

Aspen Shortcodes Admin Page

This plugin has just a few options, all found on the Aspen Shortcodes admin page under the WordPress dashboard Appearance section.

OPTIONS - general options

Slider - options for the Slider

Video - options for Videos

Shortcode Summary

[aspen_slider] - Flexible, responsive slider

The Aspen [aspen_slider] shortcode is based on the bxSlider jQuery slider script. This elegant and powerful tool allows you to generate sliders of almost any size, with any content - images, videos, even arbitrary HTML. While it is easy to use the associated Aspen S&W shortcodes, you can also use native HTML as shown in the examples on the bxSlider site.

Aspen Slider Shortcodes

The plugin provides several shortcodes to enable you to build a slider:

Examples

Basic Example

This example uses the header images included with the Apsen theme. (If you are using aspen, you can copy/paste the example to see a working slider.)

[aspen_slider id=bxslider]
    [aspen_slide]<img alt="" src="/wp-content/themes/aspen/images/headers/maroon-bells.jpg" />
    [/aspen_slide]
    [aspen_slide]<img alt="" src="/wp-content/themes/aspen/images/headers/mountain-stream.jpg" />
    [/aspen_slide]
    [aspen_slide]<img alt="" src="/wp-content/themes/aspen/images/headers/mum.jpg" />[/aspen_slide]
    [aspen_slide]<img alt="" src="/wp-content/themes/aspen/images/headers/sopris.jpg" />[/aspen_slide]
[/aspen_slider]

Pager Example 

[aspen_slider id=bxslider-pg pagerCustom=#pager]
    [aspen_slide]<img alt=""
      src="/wp-content/themes/aspen/images/headers/maroon-bells.jpg" />[/aspen_slide]
    [aspen_slide]<img alt=""
      src="/wp-content/themes/aspen/images/headers/mountain-stream.jpg" />[/aspen_slide]
    [aspen_slide]<img alt=""
      src="/wp-content/themes/aspen/images/headers/mum.jpg" />[/aspen_slide]
    [aspen_slide]<img alt=""
      src="/wp-content/themes/aspen/images/headers/sopris.jpg" />[/aspen_slide]
[/aspen_slider][aspen_slider_pager id=bxslider-pg pagerCustom=#pager]
    [aspen_slider_index]<img alt=""
      src="/wp-content/themes/aspen/images/headers/maroon-bells-thumbnail.jpg" />[/aspen_slider_index]
    [aspen_slider_index]<img alt=""
      src="/wp-content/themes/aspen/images/headers/mountain-stream-thumbnail.jpg" />[/aspen_slider_index]
    [aspen_slider_index]<img alt=""
      src="/wp-content/themes/aspen/images/headers/mum-thumbnail.jpg" />[/aspen_slider_index]
    [aspen_slider_index]<img alt=""
       src="/wp-content/themes/aspen/images/headers/sopris-thumbnail.jpg" />[/aspen_slider_index]
[/aspen_slider_pager]

Eliminate Pager Dots

You can eliminate the row of pager dots below the slider by adding pager=false to the parameter list on [aspen_slider] or [aspen_slider_options].

Eliminate Previous and Next buttons

You can eliminate the left and right arrow buttons on a slider by adding nextSelector=#none1 and nextSelector=#none2 to the parameter list on [aspen_slider] or [aspen_slider_options]. There are other things you can do with the previous and next links described on the bxSlider site.

Example using [aspen_slider_options] and HTML

You can use straight HTML for your sliders as used in the examples on the bxSlider site by using the [aspen_slider_options] shortcode to setup the required jQuery bxSlider scripts. The above simple example can equivalently be generated like this:

[aspen_slider_options id=bxslider css="#bxslider{margin:0;}"]
<ul id="bxslider">
    <li><img alt="" src="/wp-content/themes/aspen/images/headers/maroon-bells.jpg" /></li>
    <li><img alt="" src="/wp-content/themes/aspen/images/headers/mountain-stream.jpg" /></li>
    <li><img alt="" src="/wp-content/themes/aspen/images/headers/mum.jpg" /></li>
    <li><img alt="" src="/wp-content/themes/aspen/images/headers/sopris.jpg" /></li>
</ul>

Note: because of a quirk with WP site structure, you need to add the css="#bxslider{margin:0;}" as an option with many themes.

Example full width Header slideshow with auto play

In Aspen and Weaver II, you can make a slideshow in the Header area by adding an [aspen_slider] shortcode to the Site Header Insert Code or Pre-Header code areas. (Other themes may allow you to add shortcode to the header area, but it is uncommon.) This is an example of just the opening [aspen_slider] to do that:

[aspen_slider id=headerslider noborder=true pager=false nextSelector='#none1' prevSelector='#none2' mode=fade auto=true randomStart=true]

bxSlider Options

The following options are supported as paramaters to [aspen_slider] and [aspen_slider_options]. They are more completely described at bxSlider.com.

Technical note: To use any of these options, add them to either the [aspen_slider] or [aspen_slider_options] shortcodes. They will be then used to generate the appropriate $('#slider-id').bxSlider({options:value}); code used to invoke the bxSlider script for each slider. When used with the [aspen_slider] shortcode, you should use the corresponding [aspen_slide] shortcodes. If used with the [aspen_slider_options] shortcode, you can then use the <ul> and <li> slider code as found in the bxSlider examples.

GENERAL
PAGER
CONTROLS
AUTO
CAROUSEL

[aspen_show_posts] Shortcode

The [aspen_show_posts] is a very powerful tool for displaying posts from within your pages or from a text widget. Among other possibilities, it can be used to get a magazine style layout on your pages. This shortcode is intended to display a relatively small number of selected posts. It does not split posts into multiple pages like a blog page does. If you need selective display of many posts, the Page with Post page template is the better choice.

Which posts are displayed are controlled by the filtering options provided as parameters of the shortcode. Below is a summary of all parameters, shown with default values. You don't need to supply every option when you add the [aspen_show_posts] to your own content. There may seem to be an overwhelming set of options for this shortcode, but it gives you many options for displaying specific posts within a static page.

The default global settings for various post display options will be used unless overridden with a value in the shortcode. If there are more posts than 'number' that match the filter, only the first 'number' posts will be displayed. For example, if you had a "news" category, you could set cats="news" and number="1" and display just the most recent news post.

Summary

[aspen_show_posts cats="" tags="" author="" author_id="" single_post="" post_type= "" orderby="date" sort="DESC" number="5" show="full" hide_title="" hide_top_info="" hide_bottom_info="" show_featured_image="" hide_featured_image="" show_avatar="" show_bio="" excerpt_length="" style="" class="" header="" header_style="" header_class="" more_msg="" left=0 right=0 clear=0]

You can enclose the option values in either double or single quotation marks. If there is just one value, you don't need any quotation marks. If you don't include an option, the default value will be used. For most option, the default value is an empty string, which means that option won't be used to filter for posts, or that the global formatting from the Main Options settings will be used.

Important Note: [aspen_show_posts] will work on pages, widget areas, and even from within most posts. The only thing you need to be careful about when using this in a post is to avoid including the current post in posts that would be displayed by the shortcode. For example, don't use the shortcode inside a post that is in "Category A" to display other posts from "Category A". This creates an endless nesting situation (technically, called infinite recursion) that will likely fail with the "white screen of death". But don't worry - that can't happen from regular pages and widget areas, and not from most posts, either. But you can't use it within a post to show "similar" posts from the same category, for example.

Filtering Options

These options are used to filter or select which set of posts are displayed. Default value in {}'s.

Formatting Options

These options control how posts displayed by [aspen_show_posts] are formatted, and which parts of a post are displayed. These options will override any other settings for posts. If you don't set a particular option, then the formatting will be controlled first by any per post settings, then by any options specified in the Main Options admin tab.

Using in a Sidebar

This shortcode has been designed to use in a sidebar using the standard Text widget. There is special CSS styling that reduces the margins on the featured image thumbnail. If you provide the posts you want to show in the sidebar a featured image, you can get quite attractive post excerpts in the sidebar. For example, putting this in a text widget in one of your sidebars: 
[aspen_show_posts cats='new' show_featured_image='1' show='excerpt' excerpt_length='25' number='2']

will display the latest two posts from the 'news' category. The featured image will be shown in the upper left corner.

CSS styling

The group of posts will be wrapped with a <div> with called .atw-show-posts. You can add a class to that by providing a 'class=classname' option, where you use the name with a period in the CSS in the <HEAD> Section, but just the classname for the [aspen_show_posts] option.

You can also provide inline styling by providing a 'style=value' option where value is whatever styling you need, each terminated with a semi-colon (;).

These CSS rules are pre-defined, but can be overridden using the <HEAD> Section of the Advanced Options tab in Aspen and Weaver II themes, or by a custom CSS plugin such as found in JetPack. The element you're most likely to want to change is the margin-bottom. That determines how much space is added after each post.

.atw-show-posts .hentry {
    margin-top: 0px; margin-right: 0px; margin-bottom: 4px; margin-left: 0px;
}
.widget-area .atw-show-posts .hentry {
    margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px;
}
.widget-area .atw-show-posts .hentry {
    margin-bottom: 0px;
}
.widget-area .atw-show-posts .attachment-thumbnail {
    float: left; margin-right: 2px; margin-bottom: 0px; padding: 2px;
}

Example of Two Columns

This example demonstrates how to add two columns of posts on a page. This example will display the first 5 posts in the left column, and the last 5 posts in the right column. 

[aspen_show_posts sort="DESC" number="5" left=1]
[aspen_show_posts sort="ASC" number="5" right=1 clear=1]

[aspen_tab_group] - content in tabs

Alternative names: [weaver_tab_group], [tab_group]

Show content displayed on tabbed pages.

Shortcode usage:

[aspen_tab_group border_color=black page_min_height=200px]
    [aspen_tab title='tab one']This is the content found on first tab.[/aspen_tab]
    [aspen_tab title='tab two']And we have more content for the second tab.[/aspen_tab]
    [aspen_tab title='last tab']And this is the last tab. There could be more.[/aspen_tab]
[/aspen_tab_group]

Short code parameters

You can supply values for these parameters to control the look of the tabbed section.

[aspen_header_image] Shortcode

The [aspen_header_image] shortcode allows you display the current header image wherever you want. For example, you can get the header image into the Header Widget Area by using this shortcode in a text widget. The current standard or mobile header image will be displayed. Only the <img ... > is displayed -- the image will not be wrapped in a link to the site.

Shortcode usage: [aspen_header_image h='size' w='size' style='inline-style']

  1. w='size' h='size' - By default, no height or image properties are included with the header <img ... >, which will result in an image scaled to fit into whatever the natural width of the enclosing HTML container is (the content area, a text widget, etc.). You may specify an explicit value (usually in px) for the height and width of the image.
  2. style='inline-style-rules' - Allows you to add inline style to wrap output of the shortcode. Don't include the 'style=' or wrapping quotation marks. Do include a ';' at the end of each rule. The output will look like style="your-rules;" - using double quotation marks.

[aspen_html]

The Aspen S&W [aspen_html] shortcode allows you to add arbitrary HTML to your post and page content. The main purpose of this shortcode is to get around the auto paragraph and line break and other HTML stripping functionality of the WordPress editor.

Shortcode usage: [aspen_html html-tag args='parameters']

  1. html-tag - The first parameter to the shortcode must be present, and must be a standard HTML tag - p, br, or span, for example. You just supply the tag - no quotation marks, no '=', just the tag. The shortcode provides the < and >. If you need a wrapping HTML tag (e.g., span and /span), use two shortcodes:
    [aspen_html span args='style="color:red"']content to make red[aspen_html /span]
  2. args='parameters' - Allows you to specify arbitrary parameters for your HTML tag. See the example above.

[div]text[/div]

The Aspen S&W [div] shortcode allows easily add HTML <div> tags to your post and page content. The main purpose of this shortcode is to get around need to switch to the HTML editor view when you need to wrap your content in a <div>.

This will work exactly like a standard HMTL <div> tag. It supports 'id', 'class', and 'style' parameters, which are the most useful. Instead of wrapping your text in <div> tags, wrap them like this (the Visual view will work just fine):
[div style="font-size:20px;']This content will be large.[/div]

Shortcode usage: [div id='class_id' class='class_name' style='style_values']text[/div]

  1. id='class_id' class='class_name' style='style_values' - Allows you to specify id, class, and style for the <div>. See the example above.

iframe - [aspen_iframe]

The [aspen_iframe] shortcode allows you easily display the content of an external site. You simply have to specify the URL for the external site, and optionally a height. This shortcode automatically generates the correct HTML <iframe> code.

Shortcode usage: [aspen_iframe src='http://example.com' height=600 percent=100 style="style"]

  1. src='http://example.com' - The standard URL for the external site.
  2. height=600 - Optional height to allocate for the site - in px. Default is 600.
  3. percent=100 - Optional width specification in per cent. Default is 100%.
  4. style="style" - Optional style values. Added to <iframe> tag as style="values".

[aspen_show_if_mobile] / [aspen_hide_if_mobile]

The [aspen_show_if_mobile] and [aspen_hide_if_mobile]shortcodes allow you to selectively display content depending if the visitor is using a standard browser or a mobile device browser. You might want to disable a video on for mobile devices, for example.

Shortcode usage: [aspen_show_if_mobile type='mobile']content to show[/aspen_show_if_mobile]

You bracket the content you want to selectively display with [aspen_show_if_mobile] or [aspen_hide_if_mobile] and closing [/aspen_show_if_mobile] or [/aspen_hide_if_mobile] tags. That content can contain other shortcodes as needed.

The type argument can specify 'mobile' which includes all mobile devices (not tablets), 'touch' which includes touch sensitive mobile devices (e.g., small screen phones),'smalltablet' for small screen tablets (e.g. Kindle Fire), 'tablet' which includes only tablets such as the iPad, or 'any' which will include any mobile device. The default is 'mobile'.

[aspen_show_if_logged_in] / [aspen_hide_if_logged_in]

The [aspen_show_if_logged_in] and [aspen_hide_if_logged_in]shortcodes allow you to selectively display content depending if the visitor is logged in or not.

Shortcode usage: [aspen_show_if_logged_in]content to show[/aspen_show_if_logged_in]

You bracket the content you want to selectively display with [aspen_show_if_logged_in] or [aspen_hide_if_logged_in] and closing tags [/aspen_show_if_logged_in] or [/aspen_hide_if_logged_in]. That content can contain other shortcodes as needed.

[aspen_site_title], [aspen_site_desc]

The [aspen_site_title] and [aspen_site_desc] shortcodes allow you display the current site title and site tagline. (The site tagline was formerly called the site description, thus the name of the shortcode.) This can be useful in a text widget in the Header Widget Area, for example.

Note: If you want to position the content of a text widget within the a cell of the Header Widget Area, you could use the following example:

[aspen_site_title style='font-size:150%;position:absolute;padding-left:20px;padding-top:30px;']

Shortcode usage: [aspen_site_title style='inline-style'] [aspen_site_desc style='inline-style']

  1. style='inline-style-rules' - Allows you to add inline style to wrap output of the shortcode. Don't include the 'style=' or wrapping quotation marks. Do include a ';' at the end of each rule. The output will look like style="your-rules;" - using double quotation marks.

[aspen_bloginfo arg='name' style='your css']

This shortcode can be used to access the WordPress function 'get_bloginfo($arg)'. This will return a number of useful strings depending on the value. All the supported values are listed at http://code.wordpress.org/Function_Reference/get_bloginfo. Some useful values include 'stylesheet_directory' and 'template_directory'. You can wrap the bloginfo output with css added to a <span style="your css">.

Video - [aspen_vimeo], [aspen_youtube]

Aspen S&W supports specialized shortcodes to display video. While there are other ways to embed video, the Aspen S&W versions have two important features. First, they will auto adjust to the width of your content, including the mobile view. Second, they use the latest iframe/HTML5 interface provided by YouTube and Vimeo.

Specifying Video Display Size for both shortcodes

Aspen S&W supports a common set of options for both the YouTube and Vimeo shortcodes to support displaying your videos with a specific width and correct height. By default, your videos will be displayed using the full width of the content area being used (percent=100). The percent= parameter is used to specify the width you want.

The height of the video is automatically determined based on the width and the display ratio of the particular video. By default, Aspen S&W will assume a widescreen 9:16 ratio (height is width*0.5625). If you specify 'sd=1', then standard def ratio is assumed (3:4 ratio - height is width*0.75). If you have a custom sized video clip, you may also specify an exact ratio (e.g., 3:9, or ratio=.333). Both Vimeo and YouTube will accept videos with custom ratios, but they must be generated correctly without any letterboxing to display correctly.

Finally, you may specify if the video should be centered or no within the display area using "center=0" to not center (centering is on by default).

Note - if you want to display more than one video horizontally, use "center=0" and specify an appropriate percentage to fit all the videos.

Parameters in Common

Vimeo

[aspen_vimeo vimeo-url id=videoid sd=0 percent=100 ratio=0.5625 center=1 color=#hex
   autoplay=0 loop=0 portrait=1 title=1 byline=1]

This will display Vimeo videos. At the minimum, you can provide the standard http://vimeo.com/nnnnn link, or just the video ID number (which is part of the Vimeo Link). The other Vimeo specific options include:

YouTube

[aspen_youtube youtube-url id=videoid sd=0 percent=100 ratio=0.5625 center=1 rel=1 https=0 privacy=0 {youtube options}]

This will display YouTube videos. At the minimum, you can provide the standard http://youtu.be/xxxxxx share link (including the options YouTube lets you specify), the long format share link, or just the video ID number using the id=videoid parameter (which is part of the YouTube Link). The other YouTube specific options include:

In addition to the above [aspen_youtube] options, the shortcode also supports most standard YouTube options. These are more fully described on the YouTube Embedded Player Parameters page.

The supported options, with Aspen S&W's default values include:

'autohide' = '1' . . . . . . 0: always show controls; 1: autohide controls; 2: autohide progress bar
'autoplay' = '0' . . . . . . 1: auto play; 0: don't
'border' = '0' . . . . . . . . 0: no border; 1: border using color1 and color2 (don't seem to work)
'color' = not set . . . . . . progress bar color - red or white
'color1' = not set . . . . . RGB hex value for border color
'color2' = not set . . . . . RGB hex value for control bar bg
'controls' = '1' . . . . . . . 0: hide player controls
'disablekb' = '0' . . . . . . 1: disable keyboard controls
'egm' ='0' . . . . . . . . . . . 1: enable "Enhanced Genie Menu"
'hd' = '0' . . . . . . . . . . . . 1: enable HD playback by default
'iv_load_policy' = '1' . . . 1: show annotations; 3: don't show; 2: discontinued support
'loop' = '0' . . . . . . . . . . . 1: loop video
'modestbranding' = '0' . .1: hide YouTube logo - will still show label in upper right corner
'origin' = not set . . . . . . . See YouTube docs
'playlist' = not set . . . . . . Comma separated list of videoIDs to play (id/url video played 1st)
'showinfo' = '1' . . . . . . . 0: hide video title
'showsearch' = '1' . . . . . 0: hide video searchbox
'start' = not set . . . . . . . start vide this number of seconds from start
'theme' = 'dark' . . . . . . . dark or light - display theme for player
'wmode' = 'transparent' . Keeps video behind menu bars, etc. Other values available - see YouTube

Widget Summary

Aspen Login Widget

This simple widget shows a login in link, or a welcome, Site Admin, and Log out choice if the user is logged in.

Aspen Per Page Text

This widget will work like a text widget, but the title and content are defined by custom fields set on a Per Page basis. For any page, define the Custom Field atw_pp_titleif you want a title, and define Custom Fieldatw_pp_text as the content. Content can include arbitrary text, HTML, and shortcodes. The text will not automatically add paragraphs. The widget will display only if the custom fields are defined when that page is displayed. (This widget won't display on the default blog or other archive-like pages.)

Aspen Text 2

This widget lets you add two columns of text. It is most useful in wide widget areas such as a content top or bottom widget area, or a wide footer widget area.

 


The Aspen Shortcodes and Widgets Plugin and this document are © 2013, Bruce E. Wampler. Web Site - AspenTheme.com