MT-Upcoming Documentation

ABOUT MT-UPCOMING

MT-Upcoming is a Movable Type plug-in that interfaces with Upcoming, the social events calendar. To use MT-Upcoming most effectively, you should have an Upcoming account and use the site to track which events you are interested in or plan to attend. MT-Upcoming will then be able to show that information on your Movable Type weblog. The plug-in can also be used to show scheduled events for a particular city or venue.

REQUIREMENTS

MT-Upcoming is supported on Movable Type 3.2, 3.1/3.0 and 2.661.

INSTALLATION

To install MT-Upcoming, download the plug-in and uncompress it. The following files are included:

mt-upcoming.pl
mt-upcoming/mt-upcoming.cgi
mt-upcoming/tmpl/mt-upcoming.tmpl
mt-upcoming/LICENSE
mt-upcoming/CHANGELIST
mt-upcoming/WebService/...

Upload or copy these files into the plugins/ directory and (for MT 3.0 or MT 3.1) set the permissions on mt-upcoming.cgi to 755. If you want to remove MT-Upcoming, delete mt-upcoming.pl and the mt-upcoming/ directory from plugins/, remove the MT-Upcoming tags from your templates and re-build your site.

LICENSE

MT-Upcoming is released under the Artistic License. The text of this license can be found in LICENSE in the release, and is available at http://www.opensource.org/licenses/artistic-license.php. MT-Upcoming is copyright © 2005 Greg Knauss.

CAVEATS

Where to Use MT-Upcoming: MT-Upcoming has the potential to make several calls to the Upcoming API each time <MTUpcomingSearch> or <MTUpcomingWatchlist> is used. In order not to flood Upcoming with requests, you can do one of two things:

• Do not use MT-Upcoming tags on often-repeated templates like the Individual Entry Archive. Doing so can potentially produce hundreds or thousands of API calls each time a blog is re-built — this will get the API key used for those queries suspended by Upcoming. Instead, use the MT-Upcoming tags on single-use but heavily trafficked templates like Main Index.
• Make sure that you have the Digest::MD5 Perl module installed on your system. If Digest::MD5 is available, MT-Upcoming will cache responses from the Upcoming API and re-use them, allowing often-repeated templates like the Individual Entry Archive to only request information from Upcoming once. (A version of Digest::MD5 that does not require a compiler to install can be downloaded here. After unpacking, simply upload the Digest directory into Movable Type’s extlib/ directory and MT-Upcoming will begin caching.

Updating MT-Upcoming’s Listings: MT-Upcoming will only re-generate its listings when the template that contains its tags are used in a re-build, not when changes are made on Upcoming. This is important to keep in mind, and another reason to only use MT-Upcoming in often-rebuilt templates like Main Index.

Alternately, you can use the MT-Rebuild plug-in to automatically re-build your site on a regular basis. This will cause any changes made at Upcoming to be reflected on your site with the next automatic re-build.

Where to Find *_ids: A handful of the attributes to, and responses from, <MTUpcomingSearch> are numeric identifiers instead of textual names. These identifiers can be discovered by using the Upcoming API’s metro.getCountryList, metro.getStateList, metro.getList, venue.getList and user.getList calls.

INTERFACE

For Movable Type 3.2, MT-Upcoming uses the integrated plug-in settings editor accessable from the Main Menu by clicking “Plugins,” then the “Show Settings” link in the “MT-Upcoming” section.

For Movable Type 3.0 or 3.1, MT-Upcoming offers a plug-in settings editor, accessable from the “Configure Active Plugins” section of the Main Menu. You must have Blog Create permission in Movable Type to access it.

For Movable Type 2.661, users do not have access to a plug-in settings interface and must specify their settings on the tags, defined below.

With either the MT 3.0/3.1 or 3.2 interface, you can define a default Upcoming username, password and API key to use for all the MT-Upcoming tags. If you use the interface to define any or all of these values, you do not need to specify them on the tags themselves, even if they are required. If you do specify the values on the tags, they over-ride the values define by this interface.

The intention of allowing secure Upcoming information to be set via an interface is to add some small measure of security. If the Upcoming password is set on a tag, then anybody with Template Edit access will be able to see it. By using the interface, it can be limited to Movable Type users with Blog Create permission.

EXAMPLES

The following code will display an Upcoming user’s watchlist, indicating which events he’s interested in, where they are occuring and if the user is attending or not:

<h2>My Upcoming Events</h2>
<ul>
 <MTUpcomingWatchlist>
  <li>
   <a href="http://upcoming.org/event/<MTUpcomingEventId />"><b><MTUpcomingEventName /></b></a>
   @
   <a href="http://upcoming.org/venue/<MTUpcomingVenueId />"><MTUpcomingVenueName /></a>
   on
   <MTUpcomingEventStartDate format="%m/%d/%Y" />
    <MTUpcomingEventIfEndDate> -
     <MTUpcomingEventEndDate format="%m/%d" />
    </MTUpcomingEventIfEndDate>
    <MTUpcomingWatchlistIfStatusAttend>
     (I'll see you there!)
    </MTUpcomingWatchlistIfStatusAttend>
  </li>
 </MTUpcomingWatchlist>
</ul>

The following code will display the next twenty events occuring in Los Angeles tagged with “music”:

<h2>L.A. Music Events</h2>
<ul>
 <MTUpcomingSearch metro_id="1" tags="music" per_page="20">
  <li>
   <a href="http://upcoming.org/event/<MTUpcomingEventId />"><<b>MTUpcomingEventName /></b></a>
   @
   <a href="http://upcoming.org/venue/<MTUpcomingVenueId />"><MTUpcomingVenueName /></a>
   on
   <MTUpcomingEventStartDate format="%m/%d/%Y" />
  </li>
 </MTUpcomingSearch>
</ul>

TAGS

• MTUpcomingWatchlist
  A container tag that interates thorugh each event in an Upcoming user’s watchlist, repeating its contents for each. Any of the <MTUpcomingEvent*> and <MTUpcomingVenue*> tags may be used inside it, as well as the <MTUpcomingWatchlist*> tags. To alter the default behavior of <MTUpcomingWatchlist>, you may use the following attributes:
  • api_key = “api_key” (Required)
    An Upcoming API key. The default is the value set via the MT-Upcoming interface.
  • username = “username” (Required)
    The Upcoming username for the owner of the watchlist. The default is the value set via the MT-Upcoming interface.
  • password = “password” (Required)
    The password for the username above. The default is the value set via the MT-Upcoming interface. Be aware that this value will be visible by anyone with permission to edit your Movable Type templates.
  • none = “text” (Optional)
    The text to use if there are no events that match the search criteria. The default is No upcoming events.
  • lastn = “N” (Optional)
    Only display the last N events. This attribute differs from per_page by limiting the display, while per_page limits the request. The default is to use no limit.
  • offset = “N” (Optional)
    Skip the first N events before displaying. The default is 0.
  • separator = “text” (Optional)
    The text to include between each event. The default is nothing.
  • separatorfirst = “text” (Optional)
    The text to include between the first event and the second. The default is whatever separator is defined as.
  • separatorlast = “text” (Optional)
    The text to include between the second-to-last event and the last. The default is whatever separator is defined as.
  • min_date = “YYYY-MM-DD” (Optional)
    The minimum date to return watchlisted events for. The default is the date of the first event.
  • max_date = “YYYY-MM-DD” (Optional)
    The maximum date to return watchlisted events for. If excluded, the last watchlisted event is sent.
• MTUpcomingWatchlistStatus
  The status of the current <MTUpcomingWatchlist>-iterated event: “attend” or “watch”.
• MTUpcomingWatchlistIfStatusWatch
  A conditional tag that returns its contents if the current <MTUpcomingWatchlist>-iterated event has a status of “watch.”
• MTUpcomingWatchlistIfStatusAttend
  A conditional tag that returns its contents if the current <MTUpcomingWatchlist>-iterated event has a status of “attend.”
• MTUpcomingSearch
  A container tag that interates through the results of a search, repeating its contents for each. Any of the <MTUpcomingEvent*> and <MTUpcomingVenue*> tags may be used inside it. The search is defined by the attributes below — each attribute acting as a filter. Exclude them all to return every event, include multiple to narrow a search.
  • api_key = “api_key” (Required)
    An Upcoming API key. The default is the value set via the MT-Upcoming interface.
  • none = “text” (Optional)
    The text to use if there are no events that match the search criteria. The default is No upcoming events.
  • lastn = “N” (Optional)
    Only display the last N events. This attribute differs from per_page by limiting the display, while per_page limits the request. The default is to use no limit.
  • offset = “N” (Optional)
    Skip the first N events before displaying. The default is 0.
  • separator = “text” (Optional)
    The text to include between each event. The default is nothing.
  • separatorfirst = “text” (Optional)
    The text to include between the first event and the second. The default is whatever separator is defined as.
  • separatorlast = “text” (Optional)
    The text to include between the second-to-last event and the last. The default is whatever separator is defined as.
  • username = “username” (Optional)
    An Upcoming username. The default is the value set via the MT-Upcoming interface. If this attribute is defined (along with password), private as well as public events will be included in the results. Set username="" if you do not want to return private events even if this value is defined via the MT-Upcoming interface.
  • password = “password” (Optional)
    The password to the Upcoming username above. The default is the value set via the MT-Upcoming interface. If this attribute is defined (along with username), private as well as public events will be included in the results. Set password="" if you do not want to return private events even if this value is defined via the MT-Upcoming interface.
  • search_text = “text” (Optional)
    Text to search for in event titles and descriptions. The default is none.
  • country_id = “ID” (Optional)
    The numeric identifier for the country to search. The default is all.
  • state_id = “ID” (Optional)
    The numeric identifier for the state to search. The default is all.
  • metro_id = “ID” (Optional)
    The numeric identifier for the metro to search. The default is all.
  • venue_id = “ID” (Optional)
    The numeric identifier for the venue to search. The default is all.
  • min_date = “YYYY-MM-DD” (Optional)
    The minimum date for which to return results. The default is today.
  • max_date = “YYYY-MM-DD” (Optional)
    The maximum date for which to return results. The default is forever into the future.
  • tags = “tag [,tag,…]” (Optional)
    The tags an event must be associated with to be returned. The default is all.
  • per_page = “N” (Optional)
    The maximum number of results to return. The default and maximum is 100.
  • page = “N” (Optional)
    The “page” of results to return, where the size of each page is defined by per_page above. The default is 1.

• MTUpcomingEventId
  The numeric identifier of an event.

• MTUpcomingEventName
  The name of an event.

• MTUpcomingEventDescription
  The description of an event.

• MTUpcomingEventStartDate, MTUpcomingEventStartTime
  The start time and date of an event. Both tags offer both time and date, and the standard Movable Type format attribute applies.

• MTUpcomingEventEndDate, MTUpcomingEventEndTime
  The end time and date of an event. Both tags offer both time and date, and the standard Movable Type format attribute applies. If an event does not have an end date, these tags return nothing.

• MTUpcomingEventPersonal
  Returns 1 if an event is private, 0 otherwise.

• MTUpcomingEventPublic
  Returns 1 if an event is public, 0 otherwise.

• MTUpcomingEventSelfPromotional
  Returns 1 if an event is marked as self-promotional, 0 otherwise.

• MTUpcomingEventDatePosted
  The date the event was entered into Upcoming. The standard Movable Type format attribute applies.

• MTUpcomingEventIf*
  Each of the above tags also has a conditional version, named <MTUpcomingEventIf*>. If a textual or non-zero value is present for the tag, then the If version will include its contents. For example:

  Event Date:
  <MTUpcomingStartDate />
  <MTUpcomingEventIfEndDate>
   through <MTUpcomingEventEndDate />
  </MTUpcomingEventIfEndDate>

• MTUpcomingVenueId
  The numeric identifier of an venue.

• MTUpcomingVenueName
  The name of an venue.

• MTUpcomingVenueAddress
  The address of an venue.

• MTUpcomingVenueCity
  The city of an venue.

• MTUpcomingVenueZip
  The postal code of an venue.

• MTUpcomingVenuePhone
  The phone number of an venue.

• MTUpcomingVenueUrl
  The URL of an venue’s Web site.

• MTUpcomingVenueDescription
  The description of an venue.

• MTUpcomingVenueUserId
  The numeric identifier of the Upcoming user who entered the venue information.

• MTUpcomingVenuePrivate
  Returns 1 if a venue is private, 0 otherwise.

• MTUpcomingVenuePublic
  Returns 1 if a venue is public, 0 otherwise.

• MTUpcomingVenueIf*
  Each of the above tags also has a conditional version, named <MTUpcomingVenueIf*>. If a textual or non-zero value is present for the tag, then the If version will include its contents. For example:

  <!-- Only show public venues -->
  Location:
  <MTUpcomingVenueIfPublic>
   <MTUpcomingVenueName />
  </MTUpcomingVenueIfPublic>
  <MTUpcomingVenueIfPrivate>
   [It's a secret!]
  </MTUpcomingVenueIfPrivate>

Copyright © 2005 Greg Knauss. All Rights Reserved.