# Action Streams Template Author Guide #

The Action Streams plugin provides a full suite of template tags for
publishing action stream data however you wish.

## Examples ##

See both the examples provided in the
`plugins/ActionStreams/doc/example_templates` directory, as well as the
default template set in `plugins/ActionStreams/blog_tmpl` for a turnkey
solution you can disassemble.

## The minimal list ##

The simplest way to list actions is to use the markup provided by the recipe
authors with the `mt:StreamAction` tag. To list the most recent actions by all
a blog's authors, use the template code:

    <ul>
        <mt:ActionStreams>
            <li><mt:StreamAction></li>
        </mt:ActionStreams>
    </ul>

Action Streams also provides CSS and service icons for showing from what
service each action came from. If you include that CSS, use the
`action-streams` and `service-icon` classes, as in this markup:

    <!-- inside the <head> -->
    <link rel="stylesheet" type="text/css"
        href="<mt:StaticWebPath>plugins/ActionStreams/css/action-streams.css">
    <!-- styles for any extra Action Stream plugins you install -->
    <style type="text/css">
        <mt:ProfileServices extra="1"><mt:if name="icon_url">
        .service-<mt:var name="type"> {
            background-image: url(<mt:var name="icon_url">);
        }
        </mt:if></mt:ProfileServices>
    </style>

    <!-- in your list -->
    <div class="action-streams">
        <ul class="action-streams-list">
            <mt:ActionStreams>
            <li class="service-icon service-<mt:var name="service_type">">
                <mt:StreamAction>
            </li>
            </mt:ActionStreams>
        </ul>
    </div>

This will show all the icons for the plugin's known profile services on the
published actions.

## Custom templates ##

Sometimes the default `<mt:StreamAction>` output doesn't fit, and you want to
specify the markup yourself. You might be making a recent photos widget, using
`<mt:ActionStreams stream="photos">` to list only photos, in which case you'd
want to show only the thumbnails from those actions, not the wordy text you
get from `<mt:StreamAction>`.

You can fully specify the markup used for actions using the other template
tags supplied by the plugin. In a recent photos widget, you might want to show
only linked thumbnails. You would write in your template:

    <div class="widget-photos">
        <h3>Recent Photos</h3>
        
        <ul>
        <mt:ActionStreams stream="photos">
        <li>
            <a href="<mt:StreamActionURL>"
                title="<mt:StreamActionTitle escape="html">">
                <img src="<mt:StreamActionThumbnailURL>"></a>
        </li>
        </mt:ActionStreams>
        </ul>
    </div>

See later in this document for documentation on the provided template tags.

## Customizing based on type ##

You may also want to customize only *some* action templates. For example, you
might use Google Reader's sharing feature to keep a feed of your favorite
podcasts. By default, those actions would show up as:

    <li>
        Melody shared <a href="...">Favorite Podcast episode #7</a>
        from <a href="...">Favorite Podcast</a>
    </li>

Instead, you could *conditionally* use different template code for those
Google Reader actions, using the `<mt:If>` tag:

    <mt:ActionStreams>
        <li>
        <mt:If name="action_type" eq="googlereader_links">
        
            <mt:AuthorDisplayName escape="html">
            saved <a href="<mt:StreamActionURL escape="html">">
                <mt:StreamActionTitle escape="html">
            </a>
            as a favorite episode of
            <a href="<mt:StreamActionVar name="source_url" escape="html">">
                <mt:StreamActionVar name="source_title" escape="html">
            </a>
        
        <mt:Else>
            <mt:StreamAction>
        </mt:If>
        </li>
    </mt:ActionStreams>

Then all your shared Google Reader items will be customized, but your Digg
links and Flickr photos will display as normal. You can customize multiple
actions by specifying test attributes on another `<mt:Else>` tag:

    <mt:If name="action_type" eq="googlereader_links">
        <!-- shared on google reader -->
    <mt:Else name="action_type" eq="digg_links">
        <!-- dugg on digg -->
    <mt:Else>
        <!-- everything else -->
    </mt:If>

See the documentation for `<mt:ActionStreams>` for the variables it sets to
help you customize your templates.

## Rolling actions up ##

When there are multiple actions of the same type in a row, the display can be
repetitive and boring:

    <li>Melody saved <a href="...">some photo</a> as a favorite photo</li>
    <li>Melody saved <a href="...">this puppy</a> as a favorite photo</li>
    <li>Melody saved <a href="...">a kitten</a>   as a favorite photo</li>
    <li>Melody saved <a href="...">omg lol!!</a>  as a favorite photo</li>

By slightly complicating your template code, you can "roll up" these similar
actions into one single display item:

    <li>
        Melody saved <a href="...">some photo</a>,
        <a href="...">this puppy</a>, <a href="...">a kitten</a>, and
        <a href="...">omg lol!!</a> as favorite photos
    </li>

The `<mt:StreamActionRollup>` tag allows you to peek ahead in the actions
loop, producing an inner mini-loop over the next several actions if they are
of the same type.

    <mt:If name="action_type" eq="flickr_favorites">
    
        <mt:StreamActionRollup>
            <mt:If name="__first__">
                <mt:AuthorDisplayName escape="html"> saved
            <mt:Else name="__last__">
                and
            <mt:Else>
                ,
            </mt:If>
            
            <a href="<mt:StreamActionURL escape="html">">
                <mt:StreamActionTitle escape="html">
            </a>
            
            <mt:If name="__last__">
                as favorite photos
            </mt:If>
        <mt:Else>
            <!-- no sequential Flickr favorites to roll up -->
            <mt:StreamAction>
        </mt:StreamActionRollup>
    
    </mt:Else>
        <!-- not a Flickr favorite -->
        <mt:StreamAction>
    </mt:If>

See below for full documentation on the `<mt:StreamActionRollup>` tag and its
available arguments.

## Tag reference ##

Action Streams provides template tags for displaying profiles authors have
entered and the action data collected from those services.

### Selecting authors ###

Both the `<mt:ActionStreams>` and `<mt:OtherProfiles>` tags take several
options for picking whose actions or profiles to show.

If one of the below author selecting attributes is used, it specifies the
authors. Otherwise, if the tag is used in an author context (such as on an
author archive page, inside an `<mt:Authors>` tag, in an entry context, or on
an MT Pro profile page), that one author is selected. Otherwise, if the tag is
used in a blog context (most of the time), all the authors who can post to
that blog are selected.

The tag attributes for selecting authors are:

#### `author_ids` ####

A list of the numeric IDs of authors to select, separated by commas.

#### `display_names` ####

A list of the full display names of authors to select, separated by commas.

#### `authors` ####

A list of the login usernames of authors to select, separated by commas.

### `mt:ProfileServices` ###

Loops over all the profile services defined in the system, providing variables
you can use to publish information about them. The available variables are:

* `type`, the registry key/ID for the service
* `label`, the service's name
* `icon_url`, the URL to the icon representing the service
* `ident_label`, a label describing what an identifier for this service
  represents; if not present, the identifier is a "Username"
* `ident_example`, an example identifier for this service; if not present,
  "melody" is a possible example
* `ident_suffix`, a string to append to an identifier for this service to hint
  what the profile identifier is; for example, the Vox identifier is one's
  `.vox.com` domain name, so the `ident_suffix` would be ".vox.com"

Attributes supported by this tag are:

#### `extra` ####

If specified and true, only profile services implemented by other MT plugins
besides Action Streams are listed.

### `mt:OtherProfiles` ###

Lists a particular user's profiles on other services. Properties of each
profile can then be shown using the `<mt:OtherProfileVar>` tag.

See "Selecting authors" above for attributes used to select whose profiles to
show. Note that even if more than one author is selected, only one author's
profiles will be listed.

The tag's other possible attributes are:

#### `type` ####

A type of service for which to list profiles. Only profiles for services the
`service_type` of which match the specified type are shown. Common service
types are:

* `contact` (AIM, Yahoo! Messenger, etc)
* `blog` (Vox, Tumblr, the Website service, etc)
* `photos` (Flickr, Smugmug, etc)
* `video` (Vimeo, YouTube, etc)
* `links` (Delicious, Digg, etc)
* `status` (Pownce, Twitter, etc)
* `network` (Facebook, MySpace, etc)

### `mt:OtherProfileVar` ###

Provides a property of the current author profile, available in an
`<mt:OtherProfiles>` loop. Available attributes are:

#### `name` (required) ####

The property of the selected profile to show. The possible values are:

* `type`, the registry key/ID for the profile service
* `label`, the human readable (for example, "Flickr Profile")
* `ident`, the author's identifier for the current profile
* `uri`, the URL of the author's profile on the remote service

### `mt:ActionStreams` ###

Shows the specified actions collected for the specified authors. (See
"Selecting authors" above for how to specify authors.) Use the other
`mt:StreamAction`*`Something`* tags to show information about each action.

The attributes supported by this tag are:

#### `service` ####

The ID of the service from which to show actions. Service IDs are the keys
used in their service definitions; for example, Twitter's ID is `twitter`, and
Delicious' ID is `delicious`.

For services with multiple streams, limiting only by `service` without a
`stream` will list all actions from all of those streams. For example,
`service="flickr"` will list both Flickr photos and Flickr favorites.

#### `stream` ####

The ID of the stream from which to show actions. Stream IDs are the keys used
in their recipe definitions; for example, the stream of Delicious links has
the ID `links`, and the stream of Flickr photos has the ID `photos`.

Because similar streams for all services use the same stream IDs, you can use
the `stream` attribute independent of `service` to slice for similar actions
across services. For example, you can specify `stream="photos"` to get photo
events across services, or `stream="favorites"` for a multi-source list of
favorites.

To list actions from one particular stream only, use both `service` and
`stream`.

#### `limit` ####

The number of actions at most to show. If fewer actions are available in the
selected set of actions, fewer will be shown.

#### `days` ####

The number of days of actions at most to show, as determined at publish time
from the actions' creation times (`created_on` fields). If fewer actions are
available in the selected set of actions, fewer will be shown.

#### `sort_by` ####

The field by which to order the selected actions. By default, actions are
ordered by the `created_on` field (that is, the time when the action occurred
or was first found). You cannot sort by any of your streams' additional
fields, even when limiting actions to those streams.

#### `direction` ####

The direction in which to order the selected actions. Possible values are
`descend` and `ascend`. By default, actions are ordered in descending order
(`descend`).

### `mt:StreamAction` ###

Provides the recipe authors' suggested markup for the action in context.
Attributes supported by this tag are:

#### `name` ####

The name of the author whose action this is. If not given, the author's
nickname is used. Note that by specifying an empty name (that is, `name=""`),
the name will be omitted from the `StreamAction` result.

### `mt:StreamActionTitle` ###

Returns the title of the web asset associated with the current stream action.

### `mt:StreamActionURL` ###

Returns the URL of the web asset associated with the current stream action.

### `mt:StreamActionThumbnailURL` ###

Returns the URL of an image thumbnail representing the web asset associated
with the current stream action. Not all streams provide thumbnails, so this
tag may evaluate to an empty string.

### `mt:StreamActionDate` ###

Provides the date when the action occurred or was discovered. See Movable
Type's documentation of the `<mt:Date>` tag for available attributes.

### `mt:StreamActionModifiedDate` ###

Provides the date when the action was last changed. See Movable Type's
documentation of the `<mt:Date>` tag for available attributes.

### `mt:StreamActionTags` ###

Provides a loop of the tags associated with the current stream action. Not all
streams provide tags (even when the associated web asset has them). Use the
Movable Type `<mt:TagName>` template tag to display the text of the tag.

### `mt:StreamActionVar` ###

Returns the value of a specified property of the current stream action. The
available attributes are:

#### `name` (required) ####

The name of the action property to return. What properties are available for
an action depends on its stream. Check the plugin's documentation or stream
recipe for the available fields.

### `mt:StreamActionRollup` ###

When in an `<mt:ActionStreams>` loop, provides an inner loop of the next
several actions that are of the same type. For example, if in the middle of 20
random actions are five actions for links posted to Delicious,
`StreamActionRollup` provides a loop of just those five actions.

When a roll-up loop is used, the similar actions are automatically consumed
from the outer loop. In the above example, if a template uses
`StreamActionRollup` to roll up the five Delicious links, the next iteration
of the outer `ActionStreams` loop will skip ahead five actions to the first
action that was *not* a Delicious link.

If there are no similar actions to consume, `StreamActionRollup` renders the
template code in its `<mt:Else>` block instead, in the context of the single
action from the outer `ActionStreams` loop. That is, you can use the regular
template code you would use for a single action of that type in this
`<mt:Else>` section.

Attributes available on `StreamActionRollup` are:

#### by ####

The criteria on which to determine whether actions are similar. Possible
criteria are:

* `day`, the date on which the action occurred, in the currently publishing
  blog's time zone
* `service`, the profile service from which this action was collected, such as
  `digg`, `flickr`, or `vox`
* `stream`, the type of stream to which this action belongs, such as `links`
  or `photos`
* `action`, the particular action stream to which the action belongs; that is,
  the combination of `service` and `stream`

You can combine criteria by listing them together, delimited with commas. The
default behavior if `by` is not given is to roll up by `day, action`.

#### glue ####

If given, the `glue` value is added between the result of each iteration of
the loop. That is, the `glue` is inserted between the result of the loop for
each similar action.
