Index: /branches/release-41/lib/MT/Template/ContextHandlers.pm =================================================================== --- /branches/release-41/lib/MT/Template/ContextHandlers.pm (revision 2728) +++ /branches/release-41/lib/MT/Template/ContextHandlers.pm (revision 2742) @@ -1075,4 +1075,12 @@ ########################################################################### +=head2 string_format + +An alias for the 'sprintf' modifier. + +=cut + +########################################################################### + =head2 sprintf @@ -1228,15 +1236,15 @@ =over 4 -=item html +=item * html Similar to the 'encode_html' modifier. Escapes special characters as HTML entities. -=item url +=item * url Similar to the 'encode_url' modifier. Escapes special characters using a URL-encoded format (ie, " " becomes "%20"). -=item javascript or js +=item * javascript or js Similar to the 'encode_js' modifier. Escapes special characters such @@ -1244,5 +1252,5 @@ in a JavaScript string. -=item mail +=item * mail A very simple email obfuscation technique. @@ -1455,4 +1463,59 @@ ########################################################################### +=head2 TemplateNote + +A function tag that always returns an empty string. This tag is useful +for placing simple notes in your templates, since it produces nothing. + +B + + <$mt:TemplateNote note="Hi, mom!"$> + +=for tags templating + +=cut + +########################################################################### + +=head2 Ignore + +A block tag that always produces an empty string. This tag is useful +for wrapping template code you wish to disable, or perhaps annotating +sections of your template. + +B + + + The API key for the following tag is D3ADB33F. + + +=for tags templating + +=cut + +########################################################################### + +=head2 IfStatic + +Returns true if the current publishing context is static publishing, +and false otherwise. + +=for tags templating, utility + +=cut + +########################################################################### + +=head2 IfDynamic + +Returns true if the current publishing context is dynamic publishing, +and false otherwise. + +=for tags templating, utility + +=cut + +########################################################################### + =head2 App:Listing @@ -1526,10 +1589,10 @@ =over 4 -=item type (optional) +=item * type (optional) The C object type the listing is processing. If unset, will use the contents of the C variable. -=item loop (optional) +=item * loop (optional) The source of data to process. This is an array of hashes, similar @@ -1537,5 +1600,5 @@ variable is used instead. -=item empty_message (optional) +=item * empty_message (optional) Used when there are no rows to output for the listing. If not set, @@ -1544,5 +1607,5 @@ found. -=item id (optional) +=item * id (optional) Used to construct the DOM id for the listing. The outer C
tag @@ -1551,5 +1614,5 @@ attribute). -=item listing_class (optional) +=item * listing_class (optional) Provides a custom class name that can be applied to the main @@ -1557,14 +1620,14 @@ that is always applied). -=item action (optional; default 'script_url' variable) +=item * action (optional; default 'script_url' variable) Supplies the 'action' attribute of the C
tag produced. -=item hide_pager (optional; default '0') +=item * hide_pager (optional; default '0') Controls whether the pagination controls are shown or not. If unspecified, pagination is shown. -=item show_actions (optional; default '1') +=item * show_actions (optional; default '1') Controls whether the actions associated with the object type @@ -1677,9 +1740,9 @@ =over 4 -=item mode +=item * mode Maps to a '__mode' argument. -=item type +=item * type Maps to a '_type' argument. @@ -1741,15 +1804,15 @@ =over 4 -=item bar_position (optional; default "top") +=item * bar_position (optional; default "top") Assigns a CSS class name indicating whether the control is above or below the listing or edit form it is associated with. -=item hide_pager +=item * hide_pager Assign either 1 or 0 to control whether the pagination controls are displayed or not. -=item form_id +=item * form_id Associates the pagition controls and item action widget with the @@ -1793,5 +1856,5 @@ =over 4 -=item id (optional) +=item * id (optional) If specified, will be used as the 'id' attribute for the outermost C
@@ -1799,29 +1862,29 @@ variable instead. -=item label (required) +=item * label (required) The label to display above the widget. -=item label_link (optional) +=item * label_link (optional) If specified, this link will wrap the label for the widget. -=item label_onclick +=item * label_onclick If specified, this JavaScript code will be assigned to the 'onclick' attribute of a link tag wrapping the widget label. -=item class (optional) +=item * class (optional) If unspecified, will use the id of the widget. This class is included in the 'class' attribute of the outermost C
tag for the widget. -=item header_action - -=item can_close (optional; default "0") +=item * header_action + +=item * can_close (optional; default "0") Identifies whether widget may be closed or not. -=item tabbed (optional; default "0") +=item * tabbed (optional; default "0") If specified, the widget will be assigned an attribute that gives it @@ -1932,13 +1995,13 @@ =over 4 -=item id (optional) - -=item class (optional; default "info") - -=item rebuild (optional) +=item * id (optional) + +=item * class (optional; default "info") + +=item * rebuild (optional) Accepted values: "all", "index". -=item can_close (optional; default "1") +=item * can_close (optional; default "1") =back @@ -2063,30 +2126,30 @@ =over 4 -=item action (optional) +=item * action (optional) Identifies the URL to submit the form to. If not given, will use the current application URI. -=item method (optional; default "POST") +=item * method (optional; default "POST") Supplies the C method. "GET" or "POST" are the typical values for this, but will accept any HTTP-compatible method (ie: "PUT", "DELETE"). -=item object_id (optional) +=item * object_id (optional) Populates a hidden 'id' field in the form. If not given, will also use any 'id' template variable defined. -=item blog_id (optional) +=item * blog_id (optional) Populates a hidden 'blog_id' field in the form. If not given, will also use any 'blog_id' template variable defined. -=item object_type (optional) +=item * object_type (optional) Populates a hidden '_type' field in the form. If not given, will also use any 'type' template variable defined. -=item id (optional) +=item * id (optional) Used to form the 'id' element of the HTML C tag. If not specified, @@ -2094,10 +2157,10 @@ determined object_type. -=item name (optional) +=item * name (optional) Supplies the C name attribute. If unspecified, will use the C attribute, if available. -=item enctype (optional) +=item * enctype (optional) If assigned, sets an 'enctype' attribute on the C tag using the value @@ -2175,13 +2238,13 @@ =over 4 -=item id (required) +=item * id (required) A unique identifier for this group of settings. -=item class (optional) +=item * class (optional) If specified, applies this CSS class to the C
tag produced. -=item shown (optional; default "1") +=item * shown (optional; default "1") Controls whether the C
is initially shown or not. If hidden, @@ -2230,23 +2293,23 @@ =over 4 -=item id (required) +=item * id (required) Each application setting tag requires a unique 'id' attribute. This id should not be re-used within the template. -=item required (optional; default "0") +=item * required (optional; default "0") Controls whether the field is displayed with visual cues that the field is a required field or not. -=item label +=item * label Supplies the label phrase for the setting. -=item show_label (optional; default "1") +=item * show_label (optional; default "1") Controls whether the label portion of the setting is shown or not. -=item shown (optional; default "1") +=item * shown (optional; default "1") Controls whether the setting is visible or not. If specified, adds @@ -2254,15 +2317,15 @@ setting. -=item label_class (optional) +=item * label_class (optional) Allows an additional CSS class to be applied to the label of the setting. -=item content_class (optional) +=item * content_class (optional) Allows an addtional CSS class to be applied to the contents of the setting. -=item hint (optional) +=item * hint (optional) Supplies a "hint" phrase that provides inline instruction to the user. @@ -2270,21 +2333,21 @@ forces it to display. -=item show_hint (optional; default "0") +=item * show_hint (optional; default "0") Controls whether the inline help 'hint' label is shown or not. -=item warning +=item * warning Supplies a warning message to the user regarding the use of this setting. -=item show_warning +=item * show_warning Controls whether the warning message is shown or not. -=item help_page +=item * help_page Identifies a specific page of the MT help documentation for this setting. -=item help_section +=item * help_section Identifies a section name of the MT help documentation for this setting. @@ -2408,29 +2471,29 @@ =over 4 -=item var (optional) +=item * var (optional) If assigned, the current 'index' of the loop is assigned to this template variable. -=item from (optional; default "0") - -=item start +=item * from (optional; default "0") + +=item * start Identifies the starting number for the loop. -=item to - -=item end +=item * to + +=item * end Identifies the ending number for the loop. Either 'to' or 'end' must be specified. -=item step (optional; default "1") - -=item increment +=item * step (optional; default "1") + +=item * increment Provides the amount to increment the loop counter. -=item glue (optional) +=item * glue (optional) If specified, this string is added inbetween each block of the loop. @@ -2442,26 +2505,26 @@ =over 4 -=item __first__ +=item * __first__ Assigned 1 when the loop is in the first iteration. -=item __last__ +=item * __last__ Assigned 1 when the loop is in the last iteration. -=item __odd__ +=item * __odd__ Assigned 1 when the loop index is odd, 0 when it is even. -=item __even__ +=item * __even__ Assigned 1 when the loop index is even, 0 when it is odd. -=item __index__ +=item * __index__ Holds the current loop index value, even if the 'var' attribute has been given. -=item __counter__ +=item * __counter__ Tracks the number of times the loop has run (starts at 1). @@ -2597,7 +2660,7 @@ =over 4 -=item name - -=item var +=item * name + +=item * var Declares a variable to test. When none of the comparison attributes are @@ -2605,5 +2668,5 @@ a "true" value, meaning if it is assigned a non-empty, non-zero value. -=item tag +=item * tag Declares a MT tag to execute; the value of which is used for testing. @@ -2613,5 +2676,5 @@ If tag passes through the logical result of that conditional tag. -=item op +=item * op If specified, applies the specified mathematical operator to the value @@ -2621,29 +2684,29 @@ =over 4 -=item + or add +=item * + or add Addition. -=item - or sub +=item * - or sub Subtraction. -=item ++ or inc +=item * ++ or inc Adds 1 to the given value. -=item -- or dec +=item * -- or dec Subtracts 1 from the given value. -=item * or mul +=item * * or mul Multiplication. -=item / or div +=item * / or div Division. -=item % or mod +=item * % or mod Issues a modulus operator. @@ -2651,40 +2714,40 @@ =back -=item value +=item * value Used in conjunction with the 'op' attribute. -=item eq +=item * eq Tests whether the given value is equal to the value of the 'eq' attribute. -=item ne +=item * ne Tests whether the given value is not equal to the value of the 'ne' attribute. -=item gt +=item * gt Tests whether the given value is greater than the value of the 'gt' attribute. -=item lt +=item * lt Tests whether the given value is less than the value of the 'lt' attribute. -=item ge +=item * ge Tests whether the given value is greater than or equal to the value of the 'ge' attribute. -=item le +=item * le Tests whether the given value is less than or equal to the value of the 'le' attribute. -=item like +=item * like Tests whether the given value matches the regex pattern in the 'like' attribute. -=item test +=item * test Uses a Perl (or PHP under Dynamic Publishing) expression. For Perl, this @@ -2969,4 +3032,15 @@ ########################################################################### +=head2 Unless + +A conditional tag that is the logical opposite of the L tag. All +attributes supported by the L tag are also supported for this tag. + +=for tags templating + +=cut + +########################################################################### + =head2 Loop @@ -2981,12 +3055,12 @@ =over 4 -=item name - -=item var +=item * name + +=item * var The template variable that contains the array of hashref data to process. -=item sort_by (optional) +=item * sort_by (optional) Causes the data in the given array to be resorted in the manner @@ -3000,5 +3074,5 @@ sort_by="key reverse"; sort_by="value numeric" -=item glue (optional) +=item * glue (optional) If specified, this string will be placed inbetween each "row" @@ -3012,26 +3086,26 @@ =over 4 -=item __first__ +=item * __first__ Assigned when the loop is in the first iteration. -=item __last__ +=item * __last__ Assigned when the loop is in the last iteration. -=item __odd__ +=item * __odd__ Assigned 1 when the loop is on odd numbered rows, 0 when even. -=item __even__ +=item * __even__ Assigned 1 when the loop is on even numbered rows, 0 when odd. -=item __key__ +=item * __key__ When looping over a hashref template variable, this variable is assigned the key currently in context. -=item __value__ +=item * __value__ This variable holds the value of the array or hashref element @@ -3138,4 +3212,6 @@ An alias for the 'Var' tag, and considered deprecated in favor of 'Var'. +=for tags deprecated + =cut @@ -3150,5 +3226,5 @@ =over 4 -=item name (or var) +=item * name (or var) Identifies the template variable. The 'name' attribute supports a variety @@ -3175,5 +3251,5 @@ -=item op +=item * op Along with the 'value' attribute, this allows the application of @@ -3181,5 +3257,5 @@ are supported). -=item value +=item * value If provided with the 'op' attribute, provides the operand for the @@ -3190,5 +3266,5 @@ is useful for setting variables as well. -=item function +=item * function For array template variables, this attribute supports: @@ -3196,13 +3272,13 @@ =over 4 -=item pop +=item * pop Takes an element from the end of the array (last element). -=item shift +=item * shift Takes an element from the front of the array (index 0). -=item count +=item * count Returns the number of elements in the array template variable. @@ -3214,10 +3290,10 @@ =over 4 -=item delete +=item * delete Only valid when used with the 'key' attribute, or if a key is present in the variable name. -=item count +=item * count Returns the number of keys present in the hash template variable. @@ -3225,21 +3301,21 @@ =back -=item index +=item * index Identifies an element of an array template variable. -=item key +=item * key Identifies a key of a hash template variable. -=item default +=item * default If the variable is undefined or empty, this value will be output instead. -=item to_json +=item * to_json Formats the variable in JSON notation. -=item glue +=item * glue For array template variables, this attribute is used in joining the @@ -3437,5 +3513,5 @@ =over 4 -=item tag or name +=item * tag or name If either 'name' or 'tag' are specified, tests the entry in context @@ -3553,5 +3629,5 @@ =over 4 -=item glue +=item * glue A text string that is used to join each of the items together. For example @@ -3561,14 +3637,14 @@ would print out each tag name separated by a comma and a space. -=item type +=item * type The kind of object for which to show tags. By default the entry tags are shown. -=item sort_by +=item * sort_by The tag object column on which to order the tags. Common values are name and rank. By default tags are sorted by name. -=item sort_order +=item * sort_order The direction in which to sort tags by the sort_by field. Possible values @@ -3576,10 +3652,10 @@ when sorted by name and descending order when sorted by other columns. -=item limit +=item * limit A number of tags to show. If given, only the first tags as ordered by sort_by and sort_order are shown. -=item top +=item * top A number of tags to show. If given, only the given number of tags with @@ -3817,5 +3893,5 @@ =over 4 -=item max (optional; default "6") +=item * max (optional; default "6") Allows a user to specify the upper bound of the scale. @@ -3931,6 +4007,6 @@ To avoid printing out the leading text when no entry tags are assigned you -can use the EntryIfTagged conditional block to first test for entry tags -on the entry. You can also use the EntryIfTagged conditional block with +can use the L conditional block to first test for entry tags +on the entry. You can also use the L conditional block with the tag attribute to test for the assignment of a particular entry tag. @@ -3939,9 +4015,9 @@ =over 4 -=item glue +=item * glue A text string that is used to join each of the items together. For example: - <$MTTagName$> + <$mt:TagName$> would print out each tag name separated by a comma and a space. @@ -3951,5 +4027,5 @@ B -The following code can be used anywhere MTEntries can be used. It prints +The following code can be used anywhere L can be used. It prints a list of all of the tags assigned to each entry returned by L glued together by a comma and a space. @@ -3995,4 +4071,12 @@ ########################################################################### +=head2 TagLabel + +An alias for the 'TagName' tag. + +=cut + +########################################################################### + =head2 TagName @@ -4003,5 +4087,5 @@ =over 4 -=item normalize (optional; default "0") +=item * normalize (optional; default "0") If specified, outputs the "normalized" form of the tag. A normalized @@ -4011,5 +4095,5 @@ =over 4 -=item quote (optional; default "0") +=item * quote (optional; default "0") If specified, causes any tag with spaces in it to be wrapped in quote @@ -4229,7 +4313,7 @@ =over 4 -=item type - -=item archive_type +=item * type + +=item * archive_type The archive type to test for, case-insensitively. See L for @@ -4276,5 +4360,5 @@ =over 4 -=item type or archive_type +=item * type or archive_type Specifies the name of the archive type you wish to check to see if it is enabled. @@ -4354,5 +4438,5 @@ =over 4 -=item var (optional) +=item * var (optional) Supplies a variable name to use for assigning the contents of the @@ -4387,13 +4471,13 @@ =over 4 -=item module +=item * module The name of a template module in the current blog. -=item widget +=item * widget The name of the widget in the current blog to include. -=item file +=item * file The path to an external file on the system. The path can be absolute or @@ -4402,5 +4486,5 @@ includes like that found in PHP. -=item identifier +=item * identifier For selecting Index templates by their unique identifier. @@ -4411,10 +4495,10 @@ filename to load. -=item blog_id (optional) +=item * blog_id (optional) Used to include a template from another blog in the system. Use in conjunction with the module, widget or identifier attributes. -=item global (optional; default "0") +=item * global (optional; default "0") Forces an Include of a globally defined template even if the @@ -4422,5 +4506,5 @@ (For module, widget and identifier includes.) -=item ssi (optional; default "0") +=item * ssi (optional; default "0") If specified, causes the include to be handled as a server-side @@ -4443,15 +4527,15 @@ Suitable for module, widget or identifier includes. -=item cache (optional; default "0") +=item * cache (optional; default "0") Enables caching of the contents of the include. Suitable for module, widget or identifier includes. -=item key or cache_key (optional) +=item * key or cache_key (optional) Used to cache the template module. Used in conjunction with the 'cache' attribute. Suitable for module, widget or identifier includes. -=item ttl (optional) +=item * ttl (optional) Specifies the lifetime in seconds of a cached template module. Suitable @@ -4791,5 +4875,5 @@ =over 4 -=item format +=item * format A required attribute that defines the template with a string of specifiers. @@ -4801,13 +4885,13 @@ =over 4 -=item %a +=item * %a The entry's author's display name passed through the dirify global filter. Example: melody_nelson -=item %-a +=item * %-a The same as above except using dashes. Example: melody-nelson -=item %b +=item * %b For individual archive mappings, this returns the basename of the entry. By @@ -4816,42 +4900,42 @@ entry screen. Example: my_summer_vacation -=item %-b +=item * %-b Same as above but using dashes. Example: my-summer-vacation -=item %c +=item * %c The entry's primary category/subcategory path, built using the category basename field. Example: arts_and_entertainment/tv_and_movies -=item %-c +=item * %-c Same as above but using dashes. Example: arts-and-entertainment/tv-and-movies -=item %C +=item * %C The entry's primary category label passed through the dirify global filter. Example: arts_and_entertainment -=item %-C +=item * %-C Same as above but using dashes. Example: arts-and-entertainment -=item %d +=item * %d 2-digit day of the month. Example: 09 -=item %D +=item * %D 3-letter language-dependent abbreviation of the week day. Example: Tue -=item %e +=item * %e A numeric entry ID padded with leading zeroes to six digits. Example: 000040 -=item %E +=item * %E The entry's numeric ID. Example: 40 -=item %f +=item * %f Archive filename with the specified extension. This can be used instead of @@ -4859,57 +4943,57 @@ Example: entry_basename.html or index.html -=item %F +=item * %F Same as above but without the file extension. Example: filename -=item %h +=item * %h 2-digit hour on a 24-hour clock with a leading zero if applicable. Example: 09 for 9am, 16 for 4pm -=item %H +=item * %H 2-digit hour on a 24-hour clock without a leading zero if applicable. Example: 9 for 9am, 16 for 4pm -=item %i +=item * %i The setting of the IndexBasename configuration directive with the default file extension appended. Example: index.html -=item %I +=item * %I Same as above but without the file extension. Example: index -=item %j +=item * %j 3-digit day of year, zero-padded. Example: 040 -=item %m +=item * %m 2-digit month, zero-padded. Example: 07 -=item %M +=item * %M 3-letter language-dependent abbreviation of the month. Example: Sep -=item %n +=item * %n 2-digit minute, zero-padded. Example: 04 -=item %s +=item * %s 2-digit second, zero-padded. Example: 01 -=item %x +=item * %x File extension with a leading dot (.). If a file extension has not been specified a blank string is returned. Example: .html -=item %y +=item * %y 4-digit year. Example: 2005 -=item %Y +=item * %Y 2-digit year with zero-padding. Example: 05 @@ -5028,17 +5112,17 @@ B -=item template +=item * template The name of the index template. -=item identifier +=item * identifier A template identifier. -=item entry_id +=item * entry_id The numeric system ID of the entry. -=item with_index (optional; default "0") +=item * with_index (optional; default "0") If not set to 1, remove index filenames (by default, index.html) @@ -5118,5 +5202,5 @@ =over 4 -=item version (optional; default "0") +=item * version (optional; default "0") If specified, also outputs the version (same as L). @@ -5214,9 +5298,9 @@ =over 4 -=item tag +=item * tag A tag which is evaluated and tested for non-emptiness. -=item name or var +=item * name or var A variable whose contents are tested for non-emptiness. @@ -5264,9 +5348,9 @@ =over 4 -=item tag +=item * tag A tag which is evaluated and tested for non-zeroness. -=item name or var +=item * name or var A variable whose contents are tested for non-zeroness. @@ -5425,23 +5509,23 @@ =over 4 -=item var or name +=item * var or name Identifies the name of the template variable. See L for more information on the format of this attribute. -=item value +=item * value The value to assign to the variable. -=item op (optional) +=item * op (optional) See the L tag for more information about this attribute. -=item prepend (optional) +=item * prepend (optional) If specified, places the contents at the front of any existing value for the template variable. -=item append (optional) +=item * append (optional) If specified, places the contents at the end of any existing value @@ -5450,5 +5534,5 @@ =back -=for tags templating +=for tags deprecated =cut @@ -5466,19 +5550,19 @@ =over 4 -=item var or name (required) +=item * var or name (required) Identifies the name of the template variable. See L for more information on the format of this attribute. -=item op (optional) +=item * op (optional) See the L tag for more information about this attribute. -=item prepend (optional) +=item * prepend (optional) If specified, places the contents at the front of any existing value for the template variable. -=item append (optional) +=item * append (optional) If specified, places the contents at the end of any existing value @@ -5504,5 +5588,5 @@ =over 4 -=item var or name (required) +=item * var or name (required) Identifies the name of the template variable. See L for more @@ -5896,5 +5980,13 @@ } -=for tags search +########################################################################### + +=head2 MaxResults + +Deprecated in favor of L. + +=for tags deprecated + +=cut ########################################################################### @@ -5903,5 +5995,5 @@ Returns the value of the C or C configuration -setting. Use C because MaxResults is considered deprecated. +setting. Use C because MaxResults is considered deprecated. =for tags search, configuration @@ -6048,40 +6140,40 @@ =over 4 -=item display_name +=item * display_name Specifies a particular author to select. -=item lastn +=item * lastn Limits the selection of authors to the specified number. -=item sort_by (optional) +=item * sort_by (optional) Supported values: display_name, name, created_on. -=item sort_order (optional; default "ascend") +=item * sort_order (optional; default "ascend") Supported values: ascend, descend. -=item roles +=item * roles A comma separated list of roles used to select users by. eg: "Author, Commenter". -=item need_entry (optional; default "1") +=item * need_entry (optional; default "1") Identifies whether the author(s) must have published an entry to be included or not. -=item status (optional; default "enabled") +=item * status (optional; default "enabled") Supported values: enabled, disabled. -=item namespace +=item * namespace Used in conjunction with the "min*", "max*" attributes to select authors based on a particular scoring mechanism. -=item min_score +=item * min_score If 'namespace' is also specified, filters the authors based on @@ -6089,5 +6181,5 @@ to consider the author for inclusion. -=item max_score +=item * max_score If 'namespace' is also specified, filters the authors based on @@ -6095,5 +6187,5 @@ to consider the author for inclusion. -=item min_rank +=item * min_rank If 'namespace' is also specified, filters the authors based on @@ -6101,5 +6193,5 @@ to consider the author for inclusion. -=item max_rate +=item * max_rate If 'namespace' is also specified, filters the authors based on @@ -6107,5 +6199,5 @@ to consider the author for inclusion. -=item min_count +=item * min_count If 'namespace' is also specified, filters the authors based on @@ -6113,5 +6205,5 @@ to consider the author for inclusion. -=item max_count +=item * max_count If 'namespace' is also specified, filters the authors based on @@ -6504,5 +6596,5 @@ ########################################################################### -=head2 AuthorIconURL +=head2 AuthorAuthIconURL Returns URL to a small (16x16) image represents in what authentication @@ -6516,5 +6608,5 @@ =over 4 -=item size (optional; default "logo_small") +=item * size (optional; default "logo_small") Identifies the requested size of the logo. This is an identifier, @@ -6676,5 +6768,5 @@ =over 4 -=item blog_ids +=item * blog_ids This attribute allows you to limit the set of blogs iterated over by @@ -6741,4 +6833,25 @@ ########################################################################### +=head2 IfBlog + +A conditional tag that produces its contents when there is a blog in +context. This tag is useful for situations where a blog may or may not +be in context, such as the search template, when a search is conducted +across all blogs. + +B + + +

Search results for <$mt:BlogName$>:

+ +

Search results from all blogs:

+ + +=for tags blogs + +=cut + +########################################################################### + =head2 BlogID @@ -6889,5 +7002,5 @@ =over 4 -=item no_colon (optional; default "0") +=item * no_colon (optional; default "0") If specified, will produce the timezone without the ":" character @@ -6925,9 +7038,9 @@ =over 4 -=item locale (optional; default "0") +=item * locale (optional; default "0") If assigned, will format the language in the style "language_LOCALE" (ie: "en_US", "de_DE", etc). -=item ietf (optional; default "0") +=item * ietf (optional; default "0") If assigned, will change any '_' in the language code to a '-', conforming @@ -6965,5 +7078,5 @@ =over 4 -=item exclude_port (optional; default "0") +=item * exclude_port (optional; default "0") Removes any specified port number if this attribute is set to true (1), @@ -6971,5 +7084,5 @@ www.somedomain.com:8080). -=item signature (optional; default "0") +=item * signature (optional; default "0") If set to 1, then this template tag will instead return a unique signature @@ -7014,5 +7127,5 @@ =over 4 -=item exclude_port (optional; default "0") +=item * exclude_port (optional; default "0") If set, exclude the port number from the CGIHost. @@ -7038,5 +7151,16 @@ =head2 BlogCategoryCount -=for tags multiblog, count, blogs +Returns the number of categories associated with a blog. This +template tag supports the multiblog template tags. + +This template tag also supports all of the same filtering mechanisms +defined by the mt:Categories tag allowing users to retrieve a count +of the number of comments on a blog that meet a certain criteria. + +B + + <$mt:BlogCategoryCount$> + +=for tags multiblog, count, blogs, categories =cut @@ -7179,5 +7303,5 @@ =over 4 -=item with_index (optional; default "0") +=item * with_index (optional; default "0") If specified, forces the trailing "index" filename to be left on any @@ -7309,5 +7433,5 @@ =over 4 -=item lastn (optional) +=item * lastn (optional) Allows you to limit the number of entries output. This attribute @@ -7319,10 +7443,10 @@ This would publish the 5 most recent entries, ordered by their titles. -=item limit (optional) +=item * limit (optional) Similar to the C attribute, but limits output based on whichever sort order is in use. -=item sort_by (optional; default "authored_on") +=item * sort_by (optional; default "authored_on") Accepted values are: C, C, C<ping_count>, @@ -7335,5 +7459,5 @@ field basename you wish to sort on). -=item sort_order (optional) +=item * sort_order (optional) Accepted values are 'ascend' and 'descend'. The default is the order @@ -7341,5 +7465,5 @@ screen. -=item field:I<basename> +=item * field:I<basename> Permits filtering entries based on a custom field defined (available @@ -7354,5 +7478,5 @@ (checkbox field) checked. -=item namespace (optional) +=item * namespace (optional) The namespace attribute is used to specify which scoring namespace @@ -7364,9 +7488,9 @@ of recommend/favorite votes that have been made. -=item class_type (optional; default 'entry') +=item * class_type (optional; default 'entry') Accepted values are 'entry' and 'page'. -=item offset (optional) +=item * offset (optional) Accepted values are any non-zero positive integers, or the keyword @@ -7375,5 +7499,5 @@ the request. -=item category or categories (optional) +=item * category or categories (optional) This attribute allows you to filter the entries based on category @@ -7401,5 +7525,5 @@ <mt:Entries categories="NOT Family"> -=item include_subcategories (optional) +=item * include_subcategories (optional) If this attribute is specified in conjunction with the category (or @@ -7407,5 +7531,5 @@ of the identified category/categories to be included as well. -=item tag or tags (optional) +=item * tag or tags (optional) This attribute functions similarly to the C<category> attribute, but @@ -7413,5 +7537,5 @@ described for category selection. -=item author (optional) +=item * author (optional) Accepts an author's username to filter entry selection. @@ -7421,5 +7545,5 @@ <mt:Entries author="Melody"> -=item id (optional) +=item * id (optional) If specified, selects a single entry matching the given entry ID. @@ -7427,25 +7551,25 @@ <mt:Entries id="10"> -=item min_score (optional) - -=item max_score (optional) - -=item min_rate (optional) - -=item max_rate (optional) - -=item min_count (optional) - -=item max_count (optional) +=item * min_score (optional) + +=item * max_score (optional) + +=item * min_rate (optional) + +=item * max_rate (optional) + +=item * min_count (optional) + +=item * max_count (optional) Allows filtering of entries based on score, rating or count. Each of the attributes require the C<namespace> attribute. -=item scored_by (optional) +=item * scored_by (optional) Allows filtering of entries that were scored by a particular user, specified by username. Requires the C<namespace> attribute. -=item days (optional) +=item * days (optional) Limits the selection of entries to a specified number of days, @@ -7457,5 +7581,5 @@ published. -=item recently_commented_on (optional) +=item * recently_commented_on (optional) Selects the list of entries that have received published comments @@ -7469,5 +7593,5 @@ received comment. -=item unique +=item * unique If specified, this flag will cause MT to keep track of which entries @@ -7491,5 +7615,5 @@ from the first Entries tag. -=item glue (optional) +=item * glue (optional) Specifies a string that is output inbetween published entries. @@ -7652,4 +7776,5 @@ } else { my @cats = cat_path_to_category($category_arg, [ \%blog_terms, \%blog_args ], $class_type); +use Data::Dumper; die Dumper({ terms => \%blog_terms, args => \%blog_args, cats => \@cats, arg => $category_arg }); if (@cats) { $cats = \@cats; @@ -8201,4 +8326,97 @@ } +########################################################################### + +=head2 DateHeader + +A container tag whose contents will be displayed if the entry in context +was posted on a new day in the list. + +B<Example:> + + <mt:Entries> + <mt:DateHeader> + <h2><$mt:EntryDate format="%A, %B %e, %Y"$></h2> + </mt:DateHeader> + <!-- display entry here --> + </mt:Entries> + +=for tags entries + +=cut + +########################################################################### + +=head2 DateFooter + +A container tag whose contents will be displayed if the entry in context +is the last entry in the group of entries for a given day. + +B<Example:> + + <mt:Entries> + <!-- display entry here --> + <mt:DateFooter> + <hr /> + </mt:DateFooter> + </mt:Entries> + +=for tags entries + +=cut + +########################################################################### + +=head2 EntriesHeader + +The contents of this container tag will be displayed when the first +entry listed by a L<Entries> tag is reached. + +=for tags entries + +=cut + +########################################################################### + +=head2 EntriesFooter + +The contents of this container tag will be displayed when the last +entry listed by a L<Entries> tag is reached. + +=for tags entries + +=cut + +########################################################################### + +=head2 PagesHeader + +The contents of this container tag will be displayed when the first page +listed by a L<Pages> tag is reached. + +B<Example:> + + <mt:Pages glue=", "> + <mt:PagesHeader> + The following pages are available: + </mt:PagesHeader> + <a href="<$mt:PagePermalink$>"><$mt:PageTitle$></a> + </mt:Pages> + +=for tags pages + +=cut + +########################################################################### + +=head2 PagesFooter + +The contents of this container tag will be displayed when the last page +listed by a L<Pages> tag is reached. + +=for tags pages + +=cut + # returns an iterator that supplies entries, in the order of last comment # date (descending) @@ -8326,5 +8544,5 @@ =over 4 -=item convert_breaks (optional; default "1") +=item * convert_breaks (optional; default "1") Accepted values are '0' and '1'. Typically, this attribute is @@ -8332,5 +8550,5 @@ text based on the text formatting option for the entry. -=item words (optional) +=item * words (optional) Accepts any positive integer to limit the number of words @@ -8414,5 +8632,5 @@ =over 4 -=item generate (optional) +=item * generate (optional) If specified, will draw content from the "main" text field of @@ -8518,5 +8736,5 @@ =over 4 -=item flag (required) +=item * flag (required) Accepts one of: 'allow_pings', 'allow_comments'. @@ -8560,15 +8778,15 @@ =over 4 -=item no_generate (optional) +=item * no_generate (optional) If the excerpt field is empty, this flag will prevent the generation of an excerpt using the main text of the entry. -=item words (optional; default "40") +=item * words (optional; default "40") Controls the length of the auto-generated entry excerpt. Does B<not> limit the content when the excerpt field contains content. -=item convert_breaks (optional; default "0") +=item * convert_breaks (optional; default "0") When set to '1', applies the text formatting filters on the excerpt @@ -8622,4 +8840,6 @@ usernames.> +=for tags deprecated + =cut @@ -8659,4 +8879,6 @@ favor of L<EntryAuthorDisplayName>.> +=for tags deprecated + =cut @@ -8697,5 +8919,5 @@ =over 4 -=item spam_protect (optional; default "0") +=item * spam_protect (optional; default "0") If specified, this will apply a light obfuscation of the email address, @@ -8744,14 +8966,14 @@ =over 4 -=item new_window +=item * new_window If specified, the published link is given a C<target> attribute of '_blank'. -=item show_email (optional; default "0") +=item * show_email (optional; default "0") If set, will allow publishing of an email address if the URL field for the author is empty. -=item spam_protect (optional) +=item * spam_protect (optional) If specified, this will apply a light obfuscation of any email address @@ -8759,10 +8981,10 @@ address (C<:>, C<@>, and C<.>) into HTML entities. -=item type (optional) +=item * type (optional) Accepted values: C<url>, C<email>, C<archive>. Note: an 'archive' type requires publishing of "Author" archives. -=item show_hcard (optional; default "0") +=item * show_hcard (optional; default "0") If present, adds additional CSS class names to the link tag published, @@ -8935,5 +9157,5 @@ ########################################################################### -=head2 EntryTrackbackLink +=head2 EntryTrackbackData Outputs the TrackBack RDF block that allows for TrackBack @@ -8945,10 +9167,10 @@ =over 4 -=item comment_wrap (optional; default "1") +=item * comment_wrap (optional; default "1") If enabled, will enclose the RDF markup inside an HTML comment tag. -=item with_index (optional; default "0") +=item * with_index (optional; default "0") If specified, will leave any "index.html" (or appropriate index @@ -9041,7 +9263,7 @@ =over 4 -=item type (optional) - -=item archive_type (optional) +=item * type (optional) + +=item * archive_type (optional) Identifies the archive type to use when creating the link. For instance, @@ -9094,5 +9316,5 @@ =over 4 -=item separator (optional) +=item * separator (optional) Accepts either "-" or "_". If unspecified, the raw basename value is @@ -9150,10 +9372,10 @@ =over 4 -=item type or archive_type (optional) +=item * type or archive_type (optional) Specifies an alternative archive type to use instead of the individual archive. -=item valid_html (optional; default "0") +=item * valid_html (optional; default "0") When publishing entry permalinks for non-individual archive templates, an @@ -9164,5 +9386,5 @@ valid HTML. -=item with_index (optional; default "0") +=item * with_index (optional; default "0") If assigned, will retain any index filename at the end of the permalink. @@ -9270,5 +9492,5 @@ =over 4 -=item glue (optional) +=item * glue (optional) If specified, this string is placed in between each result from the loop. @@ -9381,4 +9603,6 @@ Outputs a link to the MT Comment script to allow signing in to a TypeKey configured blog. B<NOTE: This is deprecated in favor of L<SignInLink>.> + +=for tags deprecated =cut @@ -9417,4 +9641,6 @@ a blog. B<NOTE: This tag is deprecated in favor of L<SignOutLink>.> +=for tags deprecated + =cut @@ -9442,4 +9668,14 @@ } +########################################################################### + +=head2 CommentFields + +A deprecated tag that formerly published an entry comment form. + +=for tags deprecated + +=cut + sub _hdlr_comment_fields { my ($ctx, $args, $cond) = @_; @@ -9565,10 +9801,10 @@ =over 4 -=item ts (optional) +=item * ts (optional) If specified, will use the given date as the date to publish. Must be in the format of "YYYYMMDDhhmmss". -=item relative (optional) +=item * relative (optional) If specified, will publish the date using a phrase, if the date is @@ -9578,18 +9814,18 @@ =over 4 -=item relative="1" +=item * relative="1" Supports display of one duration: moments ago; N minutes ago; N hours ago; N days ago. For older dates in the same year, the date is shown as the abbreviated month and day of the month ("Jan 3"). For older dates, the year is added to that ("Jan 3 2005"). -=item relative="2" +=item * relative="2" Supports display of two durations: less than 1 minute ago; N seconds, N minutes ago; N minutes ago; N hours, N minutes ago; N hours ago; N days, N hours ago; N days ago. -=item relative="3" +=item * relative="3" Supports display of two durations: N seconds ago; N seconds, N minutes ago; N minutes ago; N hours, N minutes ago; N hours ago; N days, N hours ago; N days ago. -=item relative="js" +=item * relative="js" When specified, publishes the date using JavaScript, which relies on a @@ -9598,5 +9834,5 @@ =back -=item format (optional) +=item * format (optional) A string that provides the format in which to publish the date. If @@ -9607,76 +9843,76 @@ =over 4 -=item %Y +=item * %Y The 4-digit year. Example: "1999". -=item %m +=item * %m The 2-digit month (zero-padded). Example: for a date in September, this would output "09". -=item %d +=item * %d The 2-digit day of the month (zero-padded). Example: "05". -=item %H +=item * %H The 2-digit hour of the day (24-hour clock, zero-padded). Example: "18". -=item %M +=item * %M The 2-digit minute of the hour (zero-padded). Example: "09". -=item %S +=item * %S The 2-digit second of the minute (zero-padded). Example: "04". -=item %w +=item * %w The numeric day of the week, in the range C<0>-C<6>, where C<0> is C<Sunday>. Example: "3". -=item %j +=item * %j The numeric day of the year, in the range C<0>-C<365>. Zero-padded to three digits. Example: "040". -=item %y +=item * %y The two-digit year, zero-padded. Example: %y for a date in 2008 would output "08". -=item %b +=item * %b The abbreviated month name. Example: %b for a date in January would output "Jan". -=item %B +=item * %B The full month name. Example: "January". -=item %a +=item * %a The abbreviated day of the week. Example: %a for a date on a Monday would output "Mon". -=item %A +=item * %A The full day of the week. Example: "Friday". -=item %e - -The numeric day of the month (space-padded). Example: "08". - -=item %I +=item * %e + +The numeric day of the month (space-padded). Example: " 8". + +=item * %I The two-digit hour on a 12-hour clock padded with a zero if applicable. Example: "04". -=item %k +=item * %k The two-digit military time hour padded with a space if applicable. Example: " 9". -=item %l +=item * %l The hour on a 12-hour clock padded with a space if applicable. @@ -9685,5 +9921,5 @@ =back -=item format_name (optional) +=item * format_name (optional) Supports date formatting for particular standards. @@ -9691,9 +9927,9 @@ =over 4 -=item rfc822 +=item * rfc822 Outputs the date in the format: "%a, %d %b %Y %H:%M:%S Z". -=item iso8601 +=item * iso8601 Outputs the date in the format: "%Y-%m-%dT%H:%M:%SZ". @@ -9701,14 +9937,14 @@ =back -=item utc (optional) +=item * utc (optional) Converts the date into UTC time. -=item offset_blog_id (optional) +=item * offset_blog_id (optional) Identifies the ID of the blog to use for adjusting the time to blog time. Will default to the current blog in context if unset. -=item language (optional) +=item * language (optional) Used to force localization of the date to a specific language. @@ -9851,8 +10087,8 @@ ########################################################################### -=head2 Comments TBD +=head2 Comments A container tag which iterates over a list of comments on an entry or for a -blog. By default, all comments in context (e.g on an entry or in a blog) are +blog. By default, all comments in context (e.g. on an entry or in a blog) are returned. When used in a blog context, only comments on published entries are returned. @@ -9862,33 +10098,62 @@ =over 4 -=item lastn +=item * lastn Display the last N comments in context where N is a positive integer. B<NOTE: lastn required in a blog context.> -=item offset - -=item sort_by - -=item sort_order +=item * offset (optional; default "0") + +Specifies a number of comments to skip. + +=item * sort_by (optional) + +Specifies a sort column. + +=item * sort_order (optional) Specifies the sort order and overrides the General Settings. Recognized values are "ascend" and "descend." -=item namespace - -=item min_score - -=item max_score - -=item min_rate - -=item max_rate - -=item min_count - -=item max_count - -=item scored_by +=item * namespace + +Used in conjunction with the "min*", "max*" attributes to +select comments based on a particular scoring mechanism. + +=item * min_score + +If 'namespace' is also specified, filters the comments based on +the score within that namespace. This specifies the minimum score +to consider the comment for inclusion. + +=item * max_score + +If 'namespace' is also specified, filters the comments based on +the score within that namespace. This specifies the maximum score +to consider the comment for inclusion. + +=item * min_rank + +If 'namespace' is also specified, filters the comments based on +the rank within that namespace. This specifies the minimum rank +to consider the comment for inclusion. + +=item * max_rate + +If 'namespace' is also specified, filters the comments based on +the rank within that namespace. This specifies the maximum rank +to consider the comment for inclusion. + +=item * min_count + +If 'namespace' is also specified, filters the comments based on +the count within that namespace. This specifies the minimum count +to consider the comment for inclusion. + +=item * max_count + +If 'namespace' is also specified, filters the comments based on +the count within that namespace. This specifies the maximum count +to consider the comment for inclusion. =back @@ -10269,4 +10534,14 @@ ########################################################################### +=head2 CommentName + +Deprecated in favor of the L<CommentAuthor> tag. + +=for tags deprecated + +=cut + +########################################################################### + =head2 CommentAuthor @@ -10321,28 +10596,28 @@ =over 4 -=item show_email (optional; default "0") +=item * show_email (optional; default "0") Specifies if the comment author's email can be displayed. -=item show_url (optional; default "1") +=item * show_url (optional; default "1") Specifies if the comment author's URL can be displayed. -=item new_window (optional; default "0") +=item * new_window (optional; default "0") Specifies to open the link in a new window by adding C<target="_blank"> to the anchor tag. See example below. -=item default_name (optional; default "Anonymous") +=item * default_name (optional; default "Anonymous") Used in the event that the commenter did not provide a value for their name. -=item no_redirect (optional; default "0") +=item * no_redirect (optional; default "0") Prevents use of the mt-comments.cgi script to handle the comment author link. -=item nofollowfy (optional) +=item * nofollowfy (optional) If assigned, applies a C<rel="nofollow"> link relation to the link. @@ -10416,5 +10691,5 @@ =over 4 -=item spam_protect (optional; default "0") +=item * spam_protect (optional; default "0") =back @@ -10528,4 +10803,74 @@ ########################################################################### +=head2 CommentPreviewEmail + +A deprecated tag, replaced with L<CommentEmail>. + +=for tags deprecated + +=cut + +########################################################################### + +=head2 CommentPreviewBody + +A deprecated tag, replaced with L<CommentBody>. + +=for tags deprecated + +=cut + +########################################################################### + +=head2 CommentPreviewAuthorLink + +A deprecated tag, replaced with L<CommentAuthorLink>. + +=for tags deprecated + +=cut + +########################################################################### + +=head2 CommentPreviewURL + +A deprecated tag, replaced with L<CommentURL>. + +=for tags deprecated + +=cut + +########################################################################### + +=head2 CommentPreviewDate + +A deprecated tag, replaced with L<CommentDate>. + +=for tags deprecated + +=cut + +########################################################################### + +=head2 CommentPreviewAuthor + +A deprecated tag, replaced with L<CommentAuthor>. + +=for tags deprecated + +=cut + +########################################################################### + +=head2 CommentPreviewIP + +A deprecated tag, replaced with L<CommentIP>. + +=for tags deprecated + +=cut + +########################################################################### + =head2 CommentBody @@ -10534,5 +10879,5 @@ =over 4 -=item autolink (optional) +=item * autolink (optional) If unspecified, any plaintext links in the comment body will be @@ -10541,5 +10886,5 @@ override the blog preference. -=item convert_breaks (optional) +=item * convert_breaks (optional) By default, the comment text is formatted according to the comment text @@ -10548,5 +10893,5 @@ applied. -=item words (optional) +=item * words (optional) Limits the length of the comment body to the specified number of words. @@ -10704,9 +11049,9 @@ =over 4 -=item label or text (optional) +=item * label or text (optional) A custom phrase for the link (default is "Reply"). -=item onclick (optional) +=item * onclick (optional) Custom JavaScript code for the onclick attribute. By default, this @@ -10744,5 +11089,5 @@ =over 4 -=item pad +=item * pad If specified, zero-pads the ID to 6 digits. Example: 001234. @@ -10764,4 +11109,16 @@ =head2 CommentReplies + +A block tag which iterates over a list of reply comments to the +in context. + +B<Example:> + + <mt:Comment> + <mt:CommentReplies> + <mt:CommentsHeader>Replies to the comment:</mt:CommentsHeader> + <$mt:CommentBody$> + </mt:CommentReplies> + </mt:Comment> =for tags comments, loop @@ -10842,4 +11199,22 @@ =head2 CommentRepliesRecurse +Recursively call the block with the replies to the comment in context. This +tag, when placed at the end of loop controlled by MTCommentReplies tag will +cause them to recursively descend into any replies to comments that exist +during the loop. + +B<Example:> + + <mt:Comments> + <$mt:CommentBody$> + <mt:CommentReplies> + <mt:CommentsHeader><ul></MTCommentsHeader> + <li><$mt:CommentID$> + <$mt:CommentRepliesRecurse$> + </li> + <mt:CommentsFooter></ul></mt:CommentsFooter> + </mt:CommentReplies> + </mt:Comments> + =for tags comments @@ -10915,4 +11290,26 @@ ########################################################################### +=head2 CommentsHeader + +The contents of this container tag will be displayed when the first +comment listed by a L<Comments> or L<CommentReplies> tag is reached. + +=for tags comments + +=cut + +########################################################################### + +=head2 CommentsFooter + +The contents of this container tag will be displayed when the last +comment listed by a L<Comments> or L<CommentReplies> tag is reached. + +=for tags comments + +=cut + +########################################################################### + =head2 IfCommentParent @@ -10967,5 +11364,8 @@ =head2 CommenterNameThunk -=for tags comments +Used to populate the commenter_name Javascript variable. Deprecated in +favor of the L<UserSessionState> tag. + +=for tags deprecated =cut @@ -10992,4 +11392,18 @@ =head2 CommenterUsername +This template tag returns the username of the current commenter in context. +If no name exists, then it returns an empty string. + +B<Example:> + + <mt:Entries> + <h1><$mt:EntryTitle$></h1> + <mt:Comments> + <a name="comment-<$mt:CommentID$>"></a> + <p><$mt:CommentBody$></p> + <cite><a href="/profiles/<$mt:CommenterID$>"><$mt:CommenterUsername$></a></cite> + </mt:Comments> + </mt:Entries> + =for tags comments @@ -11004,10 +11418,10 @@ ########################################################################### -=head2 UserSessionCookieTimeout +=head2 UserSessionState Returns a JSON-formatted data structure that represents the user that is currently logged in. -=for tags comments +=for tags comments, authentication =cut @@ -11028,5 +11442,7 @@ =head2 UserSessionCookieTimeout -=for tags comments +Returns the value of the C<UserSessionCookieTimeout> configuration setting. + +=for tags comments, configuration, authentication =cut @@ -11041,5 +11457,10 @@ =head2 UserSessionCookiePath -=for tags comments +Returns the value of the C<UserSessionCookiePath> configuration setting. + +The C<UserSessionCookiePath> may also use MT tags. If it does, they will +be evaluated for the blog in context. + +=for tags comments, configuration, authentication =cut @@ -11068,5 +11489,12 @@ =head2 UserSessionCookieDomain -=for tags comments +Returns the value of the C<UserSessionCookieDomain> configuration setting, +or the domain name of the blog currently in context. Any "www" subdomain +will be ignored (ie, "www.sixapart.com" becomes ".sixapart.com"). + +The C<UserSessionCookieDomain> may also use MT tags. If it does, they will +be evaluated for the blog in context. + +=for tags comments, configuration, authentication =cut @@ -11096,7 +11524,15 @@ ########################################################################### -=head2 UserSessionCookie - -=for tags comments +=head2 UserSessionCookieName + +Returns the value of the C<UserSessionCookieName> configuration setting. +If the setting contains the C<%b> string, it will replaced with the blog ID +of the blog currently in context. + +B<Example:> + + <$mt:UserSessionCookieName$> + +=for tags comments, configuration =cut @@ -11119,4 +11555,10 @@ =head2 CommenterName +The name of the commenter for the comment currently in context. + +B<Example:> + + <$mt:CommenterName$> + =for tags comments @@ -11135,4 +11577,11 @@ =head2 CommenterEmail +The email address of the commenter. The spam_protect global filter may +be used. + +B<Example:> + + <$mt:CommenterEmail$> + =for tags comments @@ -11150,5 +11599,18 @@ =head2 CommenterAuthType -=for tags comments +Returns a string which identifies what authentication provider the commenter +in context used to authenticate him/herself. Commenter context is created by +either MTComments or MTCommentReplies template tag. For example, 'MT' will be +returned when the commenter in context is authenticated by Movable Type. When +the commenter in context is authenticated by Vox, 'Vox' will be returned. + +B<Example:> + + <mt:Comments> + <$mt:CommenterName$> (<$mt:CommenterAuthType$>) said: + <$mt:CommentBody$> + </mt:Comments> + +=for tags comments, authentication =cut @@ -11164,5 +11626,20 @@ =head2 CommenterAuthIconURL -=for tags comments +Returns URL to a small (16x16) image represents in what authentication +provider the commenter in context is authenticated. Commenter context +is created by either a L<Comments> or L<CommentReplies> block tag. For +commenters authenticated by Movable Type, it will be a small spanner +logo of Movable Type. Otherwise, icon image is provided by each of +authentication provider. Movable Type provides images for Vox, +LiveJournal and OpenID out of the box. + +B<Example:> + + <mt:Comments> + <$mt:CommenterName$><$mt:CommenterAuthIconURL$>: + <$mt:CommentBody$> + </mt:Comments> + +=for tags comments, authentication =cut @@ -11187,7 +11664,20 @@ ########################################################################### +=head2 CommenterIfTrusted + +Deprecated in favor of the L<IfCommenterTrusted> tag. + +=for tags deprecated + +=cut + +########################################################################### + =head2 IfCommenterTrusted -=for tags comments +A conditional tag that displays its contents if the commenter in context +has been marked as trusted. + +=for tags comments, authentication =cut @@ -11285,4 +11775,16 @@ =head2 CommenterUserpic +This template tag returns a complete HTML C<img> tag for the current +commenter's userpic. For example: + + <img src="http://yourblog.com/userpics/1.jpg" width="100" height="100" /> + +B<Example:> + + <h2>Recent Commenters</h2> + <mt:Entries recently_commented_on="10"> + <div class="userpic" style="float: left; padding: 5px;"><$mt:CommenterUserpic$></div> + </mt:Entries> + =for tags comments @@ -11301,4 +11803,11 @@ =head2 CommenterUserpicURL +This template tag returns the URL to the image of the current +commenter's userpic. + +B<Example:> + + <img src="<$mt:CommenterUserpicURL$>" /> + =for tags comments @@ -11315,5 +11824,17 @@ =head2 CommenterUserpicAsset -=for tags comments +This template tag is a container tag that puts the current commenter's +userpic asset in context. Because userpics are stored as assets within +Movable Type, this allows you to utilize all of the asset-related +template tags when displaying a user's userpic. + +B<Example:> + + <mt:CommenterUserpicAsset> + <img src="<$mt:AssetThumbnailURL width="20" height="20"$>" + width="20" height="20" /> + </mt:CommenterUserpicAsset> + +=for tags comments, assets =cut @@ -11357,6 +11878,35 @@ =head2 ArchivePrevious - -=cut +A container tag that creates a context to the "previous" archive +relative to the current archive context. + +This tag also works with the else tag to produce content if there is no +"previous" archive. + +B<Attributes:> + +=over 4 + +=item * type or archive_type (optional) + +Specifies the "previous" archive type the context is for. See +the L<ArchiveList> tag for supported values for this attribute. + +=back + +B<Example:> + + <mt:ArchivePrevious> + <a href="<$mt:ArchiveLink$>" + title="<$mt:ArchiveTitle escape="html"$>">Next</a> + <mt:Else> + <!-- output when no previous archive is available --> + </mt:ArchivePrevious> + +=for tags archiving + +=cut + +########################################################################### =head2 ArchiveNext @@ -11366,5 +11916,5 @@ This tag also works with the else tag to produce content if there is no -"previous" archive. +"next" archive. B<Attributes:> @@ -11372,5 +11922,5 @@ =over 4 -=item type or archive_type (optional) +=item * type or archive_type (optional) Specifies the "next" archive type the context is for. See the L<ArchiveList> @@ -11384,7 +11934,9 @@ <a href="<$mt:ArchiveLink$>" title="<$mt:ArchiveTitle escape="html"$>">Next</a> - <mt:else> - <!-- output when no previous archive is available --> + <mt:Else> + <!-- output when no next archive is available --> </mt:ArchiveNext> + +=for tags archiving =cut @@ -11504,5 +12056,5 @@ =over 4 -=item with_index (optional; default "0") +=item * with_index (optional; default "0") If enabled, will retain the "index.html" (or similar index filename) @@ -11551,5 +12103,5 @@ =over 4 -=item extension (optional; default "0") +=item * extension (optional; default "0") If specified, will append the blog's configured file extension. @@ -11583,5 +12135,5 @@ =over 4 -=item type or archive_type (optional) +=item * type or archive_type (optional) Specify a comma-delimited list of archive types to loop over. If you @@ -11637,5 +12189,5 @@ =over 4 -=item type or archive_type +=item * type or archive_type An optional attribute that specifies the type of archives to list. @@ -11648,10 +12200,10 @@ in the blog settings. -=item lastn (optional) +=item * lastn (optional) An optional attribute that can be used to limit the number of archives in the list. -=item sort_order (optional; default "descend") +=item * sort_order (optional; default "descend") An optional attribute that specifies the sort order of the archives @@ -11829,5 +12381,60 @@ ########################################################################### +=head2 ArchiveListHeader + +The contents of this container tag will be displayed when the first +entry listed by a L<ArchiveList> tag is reached. + +=for tags archiving + +=cut + +########################################################################### + +=head2 ArchiveListFooter + +The contents of this container tag will be displayed when the last +entry listed by a L<ArchiveList> tag is reached. + +=for tags archiving + +=cut + +########################################################################### + =head2 ArchiveTitle + +A descriptive title of the current archive. The value returned from this +tag will vary based on the archive type: + +=over 4 + +=item * Category + +The label of the category. + +=item * Daily + +The date in "Month, Day YYYY" form. + +=item * Weekly + +The range of dates in the week in "Month, Day YYYY - Month, Day YYYY" + +=item * Monthly + +The range of dates in the week in "Month YYYY" form. + +=item * Individual + +The title of the entry. + +=back + +B<Example:> + + <$mt:ArchiveTitle$> + +=for tags archives =cut @@ -11889,4 +12496,36 @@ attributes. +B<Attributes:> + +=over 4 + +=item * format (optional) + +A string that provides the format in which to publish the date. If +unspecified, the default that is appropriate for the language of the blog +is used (for English, this is "%B %e, %Y %l:%M %p"). See the L<Date> +tag for the supported formats. + +=item * language (optional; defaults to blog language) + +Forces the date to the format associated with the specified language. + +=item * utc (optional; default "0") + +Forces the date to UTC time zone. + +=item * relative (optional; default "0") + +Produces a relative date (relative to current date and time). Suitable for +dynamic publishing (for instance, from PHP or search result templates). If +a relative date cannot be produced (the archive date is sufficiently old), +the 'format' attribute will govern the output of the date. + +=back + +B<Example:> + + <$mt:ArchiveDateEnd$> + =for tags date @@ -11925,4 +12564,18 @@ =head2 ArchiveLabel +An alias for the L<ArchiveTypeLabel> tag. + +B<Notes:> + +Deprecated in favor of the more specific tag: L<ArchiveTypeLabel> + +=for tags deprecated + +=cut + +########################################################################### + +=head2 ArchiveTypeLabel + A descriptive label of the current archive type. @@ -11935,13 +12588,9 @@ B<Example:> - <$mt:ArchiveLabel$> + <$mt:ArchiveTypeLabel$> Related Tags: L<ArchiveType> -Notes: - -May be deprecated in exchange for the more specific tag: L<ArchiveTypeLabel> - -=for tags archive +=for tags archives =cut @@ -11949,5 +12598,5 @@ sub _hdlr_archive_label { my ($ctx, $args, $cond) = @_; - + my $at = $ctx->{current_archive_type} || $ctx->{archive_type}; $at = 'Category' if $ctx->{inside_mt_categories}; @@ -11958,5 +12607,5 @@ $al = $al->(); } - $al; + return $al; } @@ -11976,10 +12625,10 @@ =over 4 -=item extension +=item * extension set to '0' to exclude the file extension (ie, produce "politics" instead of "politics.html") -=item separator +=item * separator set to '-' to force any underscore characters in the filename to dashes @@ -12034,7 +12683,7 @@ =over 4 -=item type (optional) - -=item archive_type (optional) +=item * type (optional) + +=item * archive_type (optional) Identifies the specific archive type to generate a link for. If unspecified, @@ -12042,5 +12691,5 @@ template. -=item with_index (optional; default "0") +=item * with_index (optional; default "0") If specified, forces any index filename to be included in the link to @@ -12155,5 +12804,5 @@ <$mt:ArchiveCategory$> -=for tags deprecated, category, archive +=for tags deprecated =cut @@ -12208,4 +12857,40 @@ =head2 Calendar + +A container tag representing a calendar month that lists a single +calendar "cell" in the calendar display. + +B<Attributes:> + +=over 4 + +=item * month + +An optional attribute that specifies the calendar month and year the +tagset is to generate. The value must be in YYYYMM format. The month +attribute also recognizes two special values. Given a value of "last", +the calendar will be generated for the previous month from the current +date. Using a value of "this" will generate a calendar for the +current month. + +The default behavior is to generate a monthly calendar based on the +archive in context. When used in the context of an archive type +other then "Category," the calendar will be generated for the month +in which the archive falls. + +=item * category + +An optional attribute that specifies the name of a category from which +to return entries. + +=back + +B<Example:> + +To produce a calendar for January, 2002 of entries in the category "Foo": + + <mt:Calendar month="200201" category="Foo"> + ... + </mt:Calendar> =for tags calendar @@ -12329,5 +13014,117 @@ ########################################################################### +=head2 CalendarIfBlank + +A conditional tag that will display its contents if the current calendar +cell is for a day in another month. + +B<Example:> + + <mt:CalendarIfBlank> </mt:CalendarIfBlank> + +=for tags calendar + +=cut + +########################################################################### + +=head2 CalendarIfEntries + +A conditional tag that will display its contents if there are any +entries for this day in the blog. + +B<Example:> + + <mt:CalendarIfEntries> + <mt:Entries limit="1"> + <a href="<$mt:ArchiveLink type="Daily"$>"> + <$mt:CalendarDay$> + </a> + </mt:Entries> + </mt:CalendarIfEntries> + +=for tags calendar, entries + +=cut + +########################################################################### + +=head2 CalendarIfNoEntries + +A conditional tag that will display its contents if there are not entries +for this day in the blog. This tag predates the introduction of L<Else>, +a tag that could be used with L<CalendarIfEntries> to replace +C<CalendarIfNoEntries>. + +=for tags calendar, entries + +=cut + +########################################################################### + +=head2 CalendarDate + +The timestamp of the current day of the month. Date format tags may be +applied with the format attribute along with the language attribute. + +B<Example:> + + <$mt:CalendarDate$> + +=for tags calendar, date + +=cut + +########################################################################### + +=head2 CalendarIfToday + +A conditional tag that will display its contents if the current cell +is for the current day. + +=for tags calendar + +=cut + +########################################################################### + +=head2 CalendarWeekHeader + +A conditional tag that will display its contents before a calendar +week is started. + +B<Example:> + + <mt:CalendarWeekHeader><tr></mt:CalendarWeekHeader> + +=for tags calendar + +=cut + +########################################################################### + +=head2 CalendarWeekFooter + +A conditional tag that will display its contents before a calendar +week is ended. + +B<Example:> + + <mt:CalendarWeekFooter></tr></mt:CalendarWeekFooter> + +=for tags calendar + +=cut + +########################################################################### + =head2 CalendarDay + +The numeric day of the month for the cell of the calendar being published. +This tag may only be used inside a L<Calendar> tag. + +B<Example:> + + <$mt:CalendarDay$> =for tags calendar @@ -12347,4 +13144,12 @@ =head2 CalendarCellNumber + +The number of the "cell" in the calendar, beginning with 1. The count +begins with the first cell regardless of whether a day of the month +falls on it. This tag may only be used inside a L<Calendar> tag. + +B<Example:> + + <$mt:CalendarCellNumber$> =for tags calendar @@ -12454,4 +13259,12 @@ =head2 CategoryID +The numeric system ID of the category. + +B<Example:> + + <$mt:CategoryID$> + +=for tags categories + =cut @@ -12468,4 +13281,23 @@ =head2 CategoryLabel + +The label of the category in context. The current category in context can be +placed there by either the following contexts (in order of precedence): + +=over 4 + +=item * the current category you might be by looping through a list of categories + +=item * the current category archive template/mapping you are in + +=item * the primary category of the current entry in context + +=back + +B<Example:> + + <$mt:CategoryLabel$> + +=for tags categories =cut @@ -12489,4 +13321,26 @@ =head2 CategoryBasename + +Produces the dirified basename defined for the category in context. + +B<Attributes:> + +=over 4 + +=item * default + +A value to use in the event that no category is in context. + +=item * separator + +Valid values are "_" and "-", dash is the default value. Specifying an +underscore will convert any dashes to underscores. Specifying a dash will +convert any underscores to dashes. + +=back + +B<Example:> + + <$mt:CategoryBasename$> =cut @@ -12517,4 +13371,10 @@ =head2 CategoryDescription +The description for the category in context. + +B<Example:> + + <$mt:CategoryDescription$> + =cut @@ -12531,4 +13391,12 @@ =head2 CategoryCount + +The number of published entries for the category in context. + +B<Example:> + + Entries in this category: <$mt:CategoryCount$> + +=for tags categories, count =cut @@ -12557,4 +13425,14 @@ =head2 CategoryCommentCount + +This template tag returns the number of comments found within a category. + +B<Example:> + + <ul><mt:Categories> + <li><$mt:CategoryLabel$> (<$mt:CategoryCommentCount$>)</li> + </mt:Categories></ul> + +=for tags categories, comments =cut @@ -12585,4 +13463,10 @@ =head2 CategoryArchiveLink +A link to the archive page of the category. + +B<Example:> + + <$mt:CategoryArchiveLink$> + =cut @@ -12624,4 +13508,10 @@ =head2 CategoryTrackbackLink +The URL that TrackBack pings can be sent for the category in context. + +B<Example:> + + <$mt:CategoryTrackbackLink$> + =cut @@ -12648,4 +13538,9 @@ =head2 CategoryIfAllowPings +A conditional tag that displays its contents if pings are enabled for +the category in context. + +=for tags categories, pings + =cut @@ -12659,4 +13554,12 @@ =head2 CategoryTrackbackCount + +The number of published TrackBack pings for the category in context. + +B<Example:> + + <$mt:CategoryTrackbackCount$> + +=for tags categories, pings, count =cut @@ -12692,4 +13595,46 @@ =head2 CategoryPrevious +A container tag which creates a category context of the previous +category relative to the current entry category or archived category. + +If the current category has sub-categories, then CategoryPrevious +will generate a link to the previous sibling category. For example, +in the following category hierarchy: + + News + Gossip + Politics + Sports + Events + Oakland + Palo Alto + San Francisco + Sports + Local College + MBA + NFL + +If the current category is "Events" then CategoryPrevious will link to +"News". If the current category is "San Francisco" then CategoryPrevious +will link to "Palo Alto". + +B<Attributes:> + +=over 4 + +=item * show_empty + +Specifies whether categories with no entries assigned should be counted. + +=back + +B<Example:> + + <mt:CategoryPrevious> + <a href="<$mt:ArchiveLink archive_type="Category"$>"><$mt:CategoryLabel$></a> + </mt:CategoryPrevious> + +=for tags category, archiving + =cut @@ -12697,4 +13642,41 @@ =head2 CategoryNext + +A container tag which creates a category context of the next category +relative to the current entry category or archived category. + +If the current category has sub-categories, then CategoryNext will +generate a link to the next sibling category. For example, in the +following category hierarchy: + + News + Gossip + Politics + Sports + Events + Oakland + Palo Alto + San Francisco + Sports + Local College + MBA + NFL + +If the current category is "News" then CategoryNext will link to +"Events". If the current category is "Oakland" then CategoryNext will +link to "Palo Alto". + +B<Attributes:> + +=over 4 + +=item * show_empty + +Specifies whether categories with no entries assigned should be +counted and displayed. + +=back + +=for tags categories, archiving =cut @@ -12761,4 +13743,45 @@ =head2 IfCategory +A conditional tag used to test for category assignments for the entry +in context, or generically to test for which category is in context. + +B<Attributes:> + +=over 4 + +=item * name (or label; optional) + +The name of a category. If given, tests the category in context (or +categories of an entry in context) to see if it matches with the given +category name. + +=item * type (optional) + +Either the keyword "primary" or "secondary". Used to test whether the +specified category (specified by the name or label attribute) is a +primary or secondary category assignment for the entry in context. + +=back + +B<Examples:> + + <mt:IfCategory> + (current entry in context has a category assignment) + </mt:IfCategory> + + <mt:IfCategory type="secondary"> + (current entry in context has one or more secondary category) + </mt:IfCategory> + + <mt:IfCategory name="News"> + (current entry in context is assigned to the "News" category) + </mt:IfCategory> + + <mt:IfCategory name="News" type="primary"> + (current entry in context has a "News" category as its primary category) + </mt:IfCategory> + +=for tags entries, categories + =cut @@ -12766,4 +13789,8 @@ =head2 EntryIfCategory + +This tag has been deprecated in favor of L<IfCategory>. + +=for tags deprecated =cut @@ -12804,4 +13831,11 @@ =head2 EntryAdditionalCategories + +This block tag iterates over all secondary categories for the entry in +context. Must be used in an entry context (entry archive or L<Entries> loop). + +All categories can be listed using L<EntryCategories> loop tag. + +=for tags entries, categories =cut @@ -12832,5 +13866,31 @@ =head2 Pings -=for tags multiblog +A context-sensitive container tag that lists all of the pings sent +to a particular entry, category or blog. If used in an entry context +the tagset will list all pings for the entry. Likewise for a +TrackBack-enabled category in context. If not in an entry or category +context, a blog context is assumed and all associated pings are listed. + +B<Attributes:> + +=over 4 + +=item * category + +This attribute creates a specific category context regardless of +its placement. + +=item * lastn + +Display the last N pings in context. N is a positive integer. + +=item * sort_order + +Specifies the sort order. Recognized values are "ascend" (default) and +"descend." + +=back + +=for tags pings, multiblog =cut @@ -12896,5 +13956,41 @@ ########################################################################### +=head2 PingsHeader + +The contents of this container tag will be displayed when the first +ping listed by a L<Pings> tag is reached. + +=for tags pings + +=cut + +########################################################################### + +=head2 PingsFooter + +The contents of this container tag will be displayed when the last +ping listed by a L<Pings> tag is reached. + +=for tags pings + +=cut + +########################################################################### + =head2 PingsSent + +A container tag representing a list of TrackBack pings sent from an +entry. Use the L<PingsSentURL> tag to display the URL pinged. + +B<Example:> + + <h4>Ping'd</h4> + <ul> + <mt:PingsSent> + <li><$mt:PingsSentURL$></li> + </mt:PingsSent> + </ul> + +=for tags pings, entries =cut @@ -12921,4 +14017,13 @@ =head2 PingsSentURL +The URL of the TrackBack ping was sent to. This is the TrackBack Ping URL +and not a permalink. + +B<Example:> + + <$mt:PingsSentURL$> + +=for tags pings + =cut @@ -12932,5 +14037,40 @@ =head2 PingDate -=for tags date +The timestamp of when the ping was submitted. Date format tags may be +applied with the format attribute along with the language attribute. + +B<Attributes:> + +=over 4 + +=item * format (optional) + +A string that provides the format in which to publish the date. If +unspecified, the default that is appropriate for the language of the blog +is used (for English, this is "%B %e, %Y %l:%M %p"). See the L<Date> +tag for the supported formats. + +=item * language (optional; defaults to blog language) + +Forces the date to the format associated with the specified language. + +=item * utc (optional; default "0") + +Forces the date to UTC time zone. + +=item * relative (optional; default "0") + +Produces a relative date (relative to current date and time). Suitable for +dynamic publishing (for instance, from PHP or search result templates). If +a relative date cannot be produced (the archive date is sufficiently old), +the 'format' attribute will govern the output of the date. + +=back + +B<Example:> + + <$mt:PingDate$> + +=for tags pings, date =cut @@ -12948,4 +14088,12 @@ =head2 PingID +A numeric system ID of the TrackBack ping in context. + +B<Example:> + + <$mt:PingID$> + +=for tags pings + =cut @@ -12960,4 +14108,12 @@ =head2 PingTitle + +The title of the remote resource that the TrackBack ping sent. + +B<Example:> + + <$mt:PingTitle$> + +=for tags pings =cut @@ -12975,4 +14131,12 @@ =head2 PingURL +The URL of the remote resource that the TrackBack ping sent. + +B<Example:> + + <$mt:PingURL$> + +=for tags pings + =cut @@ -12989,4 +14153,12 @@ =head2 PingExcerpt +An excerpt describing the URL of the ping sent. + +B<Example:> + + <$mt:PingExcerpt$> + +=for tags pings + =cut @@ -13003,4 +14175,13 @@ =head2 PingIP +The IP (Internet Protocol) network address the TrackBack ping was sent +from. + +B<Example:> + + <$mt:PingIP$> + +=for tags pings + =cut @@ -13015,4 +14196,12 @@ =head2 PingBlogName + +The site name that sent the TrackBack ping. + +B<Example:> + + <$mt:BlogName$> + +=for tags pings =cut @@ -13029,4 +14218,19 @@ =head2 PingEntry + +Provides an entry context for the parent entry of the TrackBack ping +in context. + +B<Example:> + + Last TrackBack received was for the entry + titled: + <mt:Pings lastn="1"> + <mt:PingEntry> + <$mt:EntryTitle$> + </mt:PingEntry> + </mt:Pings> + +=for tags pings, entries =cut @@ -13051,4 +14255,9 @@ =head2 IfAllowCommentHTML +Conditional block that is true when the blog has been configured to +permit HTML in comments. + +=for tags comments + =cut @@ -13067,4 +14276,11 @@ =head2 IfCommentsAllowed + +Conditional block that is true when the blog is configured to accept +comments, and comments are accepted on a system-wide basis. This tag +does not take the current entry context into account; use the +L<IfCommentsAccepted> tag for this. + +=for tags comments, configuration =cut @@ -13087,4 +14303,9 @@ =head2 IfCommentsActive + +Conditional tag that displays its contents if comments are enabled or +comments exist for the entry in context. + +=for tags comments, entries =cut @@ -13114,4 +14335,16 @@ =head2 IfCommentsAccepted +Conditional tag that displays its contents if commenting is enabled for +the entry in context. + +B<Example:> + + <mt:IfCommentsAccepted> + <h3>What do you think?</h3> + (comment form) + </mt:IfCommentsAccepted> + +=for tags comments, entries, configuration + =cut @@ -13134,4 +14367,9 @@ =head2 IfPingsActive + +Conditional tag that displays its contents if TrackBack pings are +enabled or pings exist for the entry in context. + +=for tags entries, pings =cut @@ -13272,5 +14510,7 @@ =head2 EntryIfCommentsOpen -Conditional tag +Deprecated in favor of L<EntryIfCommentsActive>. + +=for tags deprecated =cut @@ -13293,4 +14533,8 @@ =head2 EntryIfAllowPings +Deprecated in favor of L<IfPingsAccepted>. + +=for tags deprecated + =cut @@ -13349,4 +14593,9 @@ =head2 SubCatIsFirst +The contents of this container tag will be displayed when the first +category listed by a L<SubCategories> tag is reached. + +=for tags categories + =cut @@ -13360,4 +14609,9 @@ =head2 SubCatIsLast +The contents of this container tag will be displayed when the last +category listed by a L<SubCategories> tag is reached. + +=for tags categories + =cut @@ -13370,4 +14624,46 @@ =head2 SubCatsRecurse + +Recursively call the L<SubCategories> or L<TopLevelCategories> container +with the subcategories of the category in context. This tag, when placed +at the end of loop controlled by one of the tags above will cause them +to recursively descend into any subcategories that exist during the loop. + +B<Attributes:> + +=over 4 + +=item * max_depth (optional) + +An optional attribute that specifies the maximum number of times the system +should recurse. The default is infinite depth. + +=back + +B<Examples:> + +The following code prints out a recursive list of categories/subcategories, linking those with entries assigned to their category archive pages. + + <mt:TopLevelCategories> + <mt:SubCatIsFirst><ul></mt:SubCatIsFirst> + <mt:If tag="CategoryCount"> + <li><a href="<$mt:CategoryArchiveLink$>" + title="<$mt:CategoryDescription$>"><mt:CategoryLabel></a> + <mt:Else> + <li><$mt:CategoryLabel$> + </mt:If> + <$mt:SubCatsRecurse$> + </li> + <mt:SubCatIsLast></ul></mt:SubCatIsLast> + </mt:TopLevelCategories> + +Or more simply: + + <mt:TopLevelCategories> + <$mt:CategoryLabel$> + <$mt:SubCatsRecurse$> + </mt:TopLevelCategories> + +=for tags categories =cut @@ -13452,4 +14748,10 @@ =head2 TopLevelCategories +A block tag listing the categories that do not have a parent and exist at +"the top" of the category hierarchy. Same as using +C<E<lt>mt:SubCategories top="1"E<gt>>. + +=for tags categories + =cut @@ -13470,4 +14772,42 @@ =head2 SubCategories + +A specialized version of the L<Categories> container tag that respects the +hierarchical structure of categories. + +B<Attributes:> + +=over 4 + +=item * include_current + +An optional boolean attribute that controls the inclusion of the +current category in the list. + +=item * sort_method + +An optional and advanced usage attribute. A fully qualified Perl method +name to be used to sort the categories. + +=item * sort_order + +Specifies the sort order of the category labels. Recognized values +are "ascend" and "descend." The default is "ascend." This attribute is +ignored if sort_method has been set. + +=item * top + +If set to 1, displays only top level categories. Same as using +L<TopLevelCategories>. + +=item * category + +Specifies a specific category by name for which to return subcategories. + +=item * glue + +=back + +=for tags categories =cut @@ -13575,4 +14915,14 @@ =head2 ParentCategory +A container tag that creates a context to the current category's parent. + +B<Example:> + + <mt:ParentCategory> + Up: <a href="<mt:ArchiveLink>"><mt:CategoryLabel></a> + </mt:ParentCategory> + +=for tags categories + =cut @@ -13602,4 +14952,25 @@ =head2 ParentCategories + +A block tag that lists all the ancestors of the current category. + +B<Attributes:> + +=over 4 + +=item * glue + +This optional attribute is a shortcut for connecting each category +label with its value. Single and double quotes are not permitted in +the string. + +=item * exclude_current + +This optional boolean attribute controls the exclusion of the +current category in the list. + +=back + +=for tags categories =cut @@ -13644,4 +15015,9 @@ =head2 TopLevelParent + +A container tag that creates a context to the top-level ancestor of +the current category. + +=for tags categories =cut @@ -13722,4 +15098,35 @@ =head2 EntriesWithSubCategories +A specialized version of L<Entries> that is aware of subcategories. The +difference between the two tags is the behavior of the category attribute. + +B<Attributes:> + +=over 4 + +=item * category + +The value of this attribute is a category label. This will include +any entries to that category and any of its subcategories. Since it +is possible for two categories to have the same label, you can specify +one particular category by including its ancestors, separated by +slashes. For instance if you have a category "Flies" and within it +a subcategory labeled "Fruit", you can ask for that category with +category="Flies/Fruit". This would distinguish it from a category +labeled "Fruit" within another called "Food Groups", for example, +which could be identified using category="Food Groups/Fruit". + +If any category in the ancestor chain has a slash in its label, the +label must be quoted using square brackets: +category="Beverages/[Coffee/Tea]" identifies a category labeled +Coffee/Tea within a category labeled Beverages. + +=back + +You can also use any of the other attributes available to L<Entries>; +and they should behave just as they do with the original tag. + +=for tags entries, categories + =cut @@ -13749,4 +15156,18 @@ =head2 SubCategoryPath + +The path to the category relative to L<BlogURL>. + +In other words, this tag returns a string that is a concatenation of the +current category and its ancestors. This tag is provided for convenience +and is the equivalent of the following template tags: + + <mt:ParentCategories glue="/"><mt:CategoryBasename /></mt:ParentCategories> + +B<Example:> + +The category "Bar" in a category "Foo" C<E<lt>$mt:SubCategoryPath$E<gt>> becomes C<foo/bar>. + +=for tags categories =cut @@ -13777,4 +15198,8 @@ =head2 HasSubCategories +Returns true if the current category has a sub-category. + +=for tags categories + =cut @@ -13796,4 +15221,8 @@ =head2 HasNoSubCategories +Returns true if the current category has no sub-categories. + +=for tags categories + =cut @@ -13805,4 +15234,9 @@ =head2 HasParentCategory + +Returns true if the current category has a parent category other than +the root. + +=for tags categories =cut @@ -13824,4 +15258,19 @@ =head2 HasNoParentCategory +Returns true if the current category does not have a parent category +other than the root. + +B<Example:> + + <mt:Categories> + <mt:HasNoParentCategory> + <mt:CategoryLabel> is but an orphan and has no parents. + <mt:else> + <mt:CategoryLabel> has a parent category! + </mt:HasNoParentCategory> + </mt:Categories> + +=for tags categories + =cut @@ -13833,4 +15282,26 @@ =head2 IfIsAncestor + +Conditional tag that is true when the category in context is an ancestor +category of the specified 'child' attribute. + +B<Attributes:> + +=over 4 + +=item * child (required) + +The label of a category in the current blog. + +=back + +B<Example:> + + <mt:IfIsAncestor child="Featured"> + (category in context is a parent category + to a subcategory named "Featured".) + </mt:IfIsDescendant> + +=for tags categories =cut @@ -13862,4 +15333,26 @@ =head2 IfIsDescendant +Conditional tag that is true when the category in context is a child +category of the specified 'parent' attribute. + +B<Attributes:> + +=over 4 + +=item * parent (required) + +The label of a category in the current blog. + +=back + +B<Example:> + + <mt:IfIsDescendant parent="Featured"> + (category in context is a child category + to the 'Featured' category.) + </mt:IfIsDescendant> + +=for tags categories + =cut @@ -13955,4 +15448,13 @@ =head2 EntryBlogID +The numeric system ID of the blog that is parent to the entry currently +in context. + +B<Example:> + + <$mt:EntryBlogID$> + +=for tags entries, blogs + =cut @@ -13967,4 +15469,13 @@ =head2 EntryBlogName + +Returns the blog name of the blog to which the entry in context belongs. +The blog name is set in the General Blog Settings. + +B<Example:> + + <$mt:EntryBlogName$> + +=for tags entries, blogs =cut @@ -13982,4 +15493,13 @@ =head2 EntryBlogDescription + +Returns the blog description of the blog to which the entry in context +belongs. The blog description is set in the General Blog Settings. + +B<Example:> + + <$mt:EntryBlogDescription$> + +=for tags blogs, entries =cut @@ -13999,4 +15519,12 @@ =head2 EntryBlogURL +Returns the blog URL for the blog to which the entry in context belongs. + +B<Example:> + + <$mt:EntryBlogURL$> + +=for tags blogs, entries + =cut @@ -14013,4 +15541,24 @@ =head2 EntryEditLink + +A link to edit the entry in context from the Movable Type CMS. This tag is +only recognized in system templates where an authenticated user is +logged-in. + +B<Attributes:> + +=over 4 + +=item * text (optional; default "Edit") + +A phrase to use for the edit link. + +=back + +B<Example:> + + <$mt:EntryEditLink$> + +=for tags search =cut @@ -14046,4 +15594,34 @@ =head2 HTTPContentType +When this tag is used in a dynamically published index template, the value +specified to the type attribute will be returned in the Content-Type HTTP +header sent to web browser. This content is never displayed directly to the +user but is instead used to signal to the browser the data type of the +response. + +When this tag is used in a system template, such as the search results +template, mt-search.cgi will use the value specified to "type" attribute and +returns it in Content-Type HTTP header to web browser. + +When this tag is used in statically published template, this template tag +outputs nothing. + +B<Attributes:> + +=over 4 + +=item * type + +A valid HTTP Content-Type value, for example 'application/xml'. Note that you +must not specify charset portion of Content-Type header value in this +attribute. MT will set the portion automatically by using PublishCharset +configuration directive. + +=back + +B<Example:> + + <$mt:HTTPContentType type="application/xml"$> + =cut @@ -14058,4 +15636,85 @@ =head2 Assets + +A container tag which iterates over a list of assets. + +B<Attributes:> + +=over 4 + +=item * type + +Specifies a particular type(s) of asset to select. This may be +one of image, audio, video (if unspecified, will select all asset +types). Supports a comma-delimited list. + +=item * file_ext + +Specifies a particular file extension to select. For instance, gif, mp3, +pdf, etc. Supports a comma-delimited list. + +=item * days + +Selects assets created in the last number of days specified. + +=item * author + +Selects assets uploaded by a particular author (where the author's +username is given). + +=item * lastn + +Limits the selection of assets to the specified number. + +=item * limit + +a positive integer to limit results. + +=item * offset + +Used in coordination with lastn, starts N assets from the start of the +list. N is a positive integer. + +=item * tag + +Selects assets with particular tags (supports expressions such as +"interesting AND featured"). + +=item * sort_by + +Supported values: file_name, created_by, created_on, score. + +=item * sort_order + +Supported values: ascend, descend. + +=item * namespace + +Used in conjunction with the sort_by attribute when sorting in +"score" order. The namespace identifies the method of scoring to use +in sorting assets. + +=item * assets_per_row + +When publishing a grid of thumbnails, this attribute sets how many +iterations the Assets tag publishes before setting the state that +enables the L<AssetIsLastInRow> tag. Supported values: numbers between 1 +and 100. Also supported is the keyword "auto" which selects the +most aesthetically pleasing number of items per row based on the +total number of assets. For example, if you had 18 total assets, three +rows of six would publish, but for 16 assets, four rows of four +would publish. + +=back + +B<Example:> + + <mt:Assets lastn="10" type="image" tag="favorite"> + <a href="<mt:AssetURL>"> + <img src="<mt:AssetThumbnailURL height="70">" + alt="<mt:AssetLabel escape="html">" + title="<mt:AssetLabel escape="html">" /> + </a> + </mt:Assets> =for tags multiblog, asset @@ -14427,7 +16086,125 @@ ########################################################################### +=head2 EntryAssets + +A container tag which iterates over a list of assets for the current +entry in context. Supports all the attributes provided by the L<Assets> +tag. + +=for tags entries, assets + +=cut + +########################################################################### + +=head2 PageAssets + +A container tag which iterates over a list of assets for the current +page in context. Supports all the attributes provided by the L<Assets> +tag. + +=for tags pages, assets + +=cut + +########################################################################### + +=head2 AssetsHeader + +The contents of this container tag will be displayed when the first +entry listed by a L<Assets> tag is reached. + +=for tags assets + +=cut + +########################################################################### + +=head2 AssetsFooter + +The contents of this container tag will be displayed when the last +entry listed by a L<Assets> tag is reached. + +=for tags assets + +=cut + +########################################################################### + +=head2 AssetIsFirstInRow + +A conditional tag that displays its contents if the asset in context is +the first item in the row in context when publishing a grid of +assets (e.g. thumbnails). Grid of assets can be created by specifying +assets_per_row attribute value to L<Assets> block tag. + +For example, the first, the fourth and the seventh asset are the +first assets in row when L<Assets> iterates eight assets and +assets_per_row is set to "3". + +B<Example:> + + <table> + <mt:Assets type="image" assets_per_row="4"> + <mt:AssetIsFirstInRow><tr></mt:AssetIsFirstInRow> + <td><$mt:AssetThumbnailLink$></td> + <mt:AssetIsLastInRow></tr></mt:AssetIsLastInRow> + </mt:Assets> + </table> + +=cut + +########################################################################### + +=head2 AssetIsLastInRow + +A conditional tag that displays its contents if the asset in context +is the last item in the row in context when publishing a grid of +assets (e.g. thumbnails). Grid of assets can be created by specifying +assets_per_row attribute value to L<Assets> block tag. + +For example, the third, the sixth and the eighth asset are the last +assets in row when L<Assets> iterates eight assets and assets_per_row is +set to "3". + +B<Example:> + + <table> + <mt:Assets type="image" assets_per_row="4"> + <mt:AssetIsFirstInRow><tr></mt:AssetIsFirstInRow> + <td><$mt:AssetThumbnailLink$></td> + <mt:AssetIsLastInRow></tr></mt:AssetIsLastInRow> + </mt:Assets> + </table> + +=for tags assets + +=cut + +########################################################################### + =head2 Asset -=for tags asset +Container tag that provides an asset context for a specific asset, +from which all asset variable tags can be used to retreive metadata +about that asset. + +B<Attributes:> + +=over 4 + +=item * id + +The unique numeric id of the asset. + +=back + +B<Example:> + + <mt:Asset id="10"> + <$mt:AssetLabel$> + </mt:Asset> + +=for tags assets =cut @@ -14460,5 +16237,38 @@ =head2 AssetTags -=for tags asset +A container tag used to output infomation about the asset tags assigned +to the asset in context. + +To avoid printing out the leading text when no asset tags are assigned you +can use the L<AssetIfTagged> conditional block to first test for asset tags +on the asset. You can also use the L<AssetIfTagged> conditional block with +the tag attribute to test for the assignment of a particular entry tag. + +B<Attributes:> + +=over 4 + +=item * glue + +A text string that is used to join each of the items together. For example: + + <mt:AssetTags glue=", "><$mt:TagName$></mt:AssetTags> + +would print out each tag name separated by a comma and a space. + +=back + +B<Example:> + +The following code can be used anywhere L<Assets> can be used. It prints +a list of all of the tags assigned to each asset returned by L<Assets> +glued together by a comma and a space. + + <mt:If tag="AssetTags"> + The asset "<$mt:AssetLabel$>" is tagged: + <mt:AssetTags glue=", "><$mt:TagName$></mt:AssetTags> + </mt:If> + +=for tags tags, assets =cut @@ -14505,5 +16315,11 @@ =head2 AssetID -=for tags asset +A numeric system ID of the Asset currently in context. + +B<Example:> + + <$mt:AssetID$> + +=for tags assets =cut @@ -14520,5 +16336,13 @@ =head2 AssetFileName -=for tags asset +The file name of the asset in context. For file-based assets only. Returns +the file name without the path (i.e. file.jpg, not +/home/user/public_html/images/file.jpg). + +B<Example:> + + <$mt:AssetFileName$> + +=for tags assets =cut @@ -14535,5 +16359,12 @@ =head2 AssetLabel -=for tags asset +Returns the label of the asset in context. Label can be specified upon +uploading a file. + +B<Example:> + + <$mt:AssetLabel$> + +=for tags assets =cut @@ -14550,5 +16381,11 @@ =head2 AssetDescription -=for tags asset +This tag returns the description text of the asset currently in context. + +B<Example:> + + <$mt:AssetDescription$> + +=for tags assets =cut @@ -14565,5 +16402,11 @@ =head2 AssetURL -=for tags asset +Produces a permalink for the uploaded asset. + +B<Example:> + + <$mt:AssetURL$> + +=for tags assets =cut @@ -14580,5 +16423,13 @@ =head2 AssetType -=for tags asset +Returns the localized name for the type of asset currently in context. +For instance, for an image asset, this will tag will output (for English +blogs), "image". + +B<Example:> + + <$mt:AssetType$> + +=for tags assets =cut @@ -14595,5 +16446,12 @@ =head2 AssetMimeType -=for tags asset +Returns MIME type of the asset in context. MIME type of a file is typically +provided by web browser upon uploading. + +B<Example:> + + <$mt:AssetMimeType$> + +=for tags assets =cut @@ -14610,5 +16468,13 @@ =head2 AssetFilePath -=for tags asset +Path information of the asset in context. For file-based assets only. +Returns the local file path with the name of the file (i.e. +/home/user/public_html/images/file.jpg). + +B<Example:> + + <$mt:AssetFilePath$> + +=for tags assets =cut @@ -14624,4 +16490,31 @@ =head2 AssetDateAdded + +The date the asset in context was added to Movable Type. + +B<Attributes:> + +=over 4 + +=item * format + +A string that provides the format in which to publish the date. If +unspecified, the default that is appropriate for the language of the blog +is used (for English, this is "%B %e, %Y %l:%M %p"). See the L<Date> +tag for the supported formats. + +=item * language + +Forces the date to the format associated with the specified language. + +=item * utc + +Forces the date to UTC format. + +=back + +B<Example:> + + <$mt:AssetDateAdded$> =for tags date, asset @@ -14641,5 +16534,12 @@ =head2 AssetAddedBy -=for tags asset +Display name (or username if display name isn't assigned) of the user +who added the asset to the system. + +B<Example:> + + <$mt:AssetAddedBy$> + +=for tags assets =cut @@ -14660,5 +16560,63 @@ =head2 AssetProperty -=for tags asset +Returns the additional metadata of the asset in context. Some of these +properties only make sense for certain file types. For example, image_width +and image_height apply only to images. + +B<Attributes:> + +=over 4 + +=item * property (required) + +Specifies what property to return from the tag. B<Supported attribute values:> + +=over 4 + +=item * file_size + +asset's file size + +=item * image_width + +asset's width (for image only; otherwise returns 0) + +=item * image_height + +asset's height (for image only; otherwise returns 0) + +=item * description + +asset's description + +=back + +=item * format + +Used in conjunction with file_size property. B<Supported attribute values:> + +=over 4 + +=item * 0 + +return raw size + +=item * 1 (default) + +auto format depending on the size + +=item * k + +size expressed in kilobytes + +=item * m + +size expressed in megabytes + +=back + +=back + +=for tags assets =cut @@ -14710,5 +16668,12 @@ =head2 AssetFileExt -=for tags asset +The file extension of the asset in context. For file-based assets only. +Returns the file extension without the leading period (ie: "jpg"). + +B<Example:> + + <$mt:AssetFileExt$> + +=for tags assets =cut @@ -14725,5 +16690,49 @@ =head2 AssetThumbnailURL -=for tags asset +Returns the URL for a thumbnail you wish to generate for the current +asset in context. + +B<Attributes:> + +=over 4 + +=item * height + +The height of the thumbnail to generate. If this is the only parameter +specified then the thumbnail's width will be scaled proportionally to +the height. + +=item * width + +The width of the thumbnail to generate. If this is the only parameter +specified then the thumbnail's height will be scaled proportionally +to the width. + +=item * scale + +The percentage by which to reduce or increase the size of the current +asset. + +=item * square + +If set to 1 (one) then the thumbnail generated will be square, where +the length of each side of the square will be equal to the shortest +side of the image. + +=back + +B<Example:> + +The following will output thumbnails for all of the assets embedded in all +of the entries on the system. Each thumbnail will be square and have a +max height/width of 100 pixels. + + <mt:Entries> + <mt:EntryAssets> + <$mt:AssetThumbnailURL width="100" square="1"$> + </mt:EntryAssets> + </mt:Entries> + +=for tags assets =cut @@ -14751,5 +16760,24 @@ =head2 AssetLink -=for tags asset +Returns HTML anchor tag for the asset in context. For example, if the URL +of the asset is C<http://example.com/image.jpg>, the tag returns +C<E<lt>a href="http://example.com/image.jpg"E<gt>image.jpgE<lt>/aE<gt>>. + +B<Attributes:> + +=over 4 + +=item * new_window (optional; default "0") + +Specifies if the tag generates 'target="_blank"' attribute to the anchor +tag. + +=back + +B<Example:> + + <$mt:AssetLink$> + +=for tags assets =cut @@ -14772,5 +16800,35 @@ =head2 AssetThumbnailLink -=for tags asset +Produces a thumbnail image, linked to the image asset currently in +context. + +B<Attributes:> + +=over 4 + +=item * height + +The height of the thumbnail to generate. If this is the only parameter +specified then the thumbnail's width will be scaled proportionally to +the height. + +=item * width + +The width of the thumbnail to generate. If this is the only parameter +specified then the thumbnail's height will be scaled proportionally +to the width. + +=item * scale + +The percentage by which to reduce or increase the size of the current +asset. + +=item * new_window (optional; default "0") + +If set to '1', causes the link to open a new window to the linked asset. + +=back + +=for tags assets =cut @@ -14806,5 +16864,22 @@ =head2 AssetCount -=for tags asset +Returns the number of assets associated with the active blog. + +B<Attributes:> + +=over 4 + +=item type + +Allows for filtering by file type. Built-in types supported are "image", +"audio", "video". These types can be extended by plugins. + +=back + +B<Example:> + + Images available: <$mt:AssetCount type="image"$> + +=for tags assets =cut @@ -14823,5 +16898,19 @@ =head2 AssetIfTagged -=for tags asset +A conditional tag whose contents will be displayed if the asset in +context has tags. + +B<Attributes:> + +=over 4 + +=item * tag or name + +If either 'name' or 'tag' are specified, tests the asset in context +for whether it has a tag association by that name. + +=back + +=for tags assets, tags =cut @@ -14845,4 +16934,14 @@ =head2 CaptchaFields + +Returns the HTML markup necessary to display the CAPTCHA on the published +blog. The value returned is escaped for assignment to a JavaScript string, +since the CAPTCHA field is displayed through the MT JavaScript code. + +B<Example:> + + var captcha = '<$mt:CaptchaFields$>'; + +=for tags comments =cut @@ -14865,4 +16964,28 @@ =head2 Pages + +A container tag which iterates over a list of pages--which pages depends +on the context the tag is being used in. Within each iteration, you can +use any of the page variable tags. + +Because pages are basically non-date-based entries, the the C<Pages> +tag is very similar to L<Entries>. + +B<Attributes unique to the Pages tag:> + +=over 4 + +=item * folder + +Use folder label, not basename. + +=item * include_subfolders + +Specify '1' to cause all pages that may exist within subfolders to the +folder in context to be included. + +=back + +=for tags pages, multiblog =cut @@ -14904,4 +17027,8 @@ =head2 PagePrevious +A container tag that create a context to the previous page. + +=for tags pages, archiving + =cut @@ -14909,5 +17036,5 @@ my($ctx, $args, $cond) = @_; - return $_ unless &_check_page(@_); + return undef unless &_check_page(@_); require MT::Page; $args->{class_type} = MT::Page->properties->{class_type}; @@ -14919,4 +17046,8 @@ =head2 PageNext +A container tag that create a context to the next page. + +=for tags pages, archiving + =cut @@ -14926,5 +17057,5 @@ require MT::Page; $args->{class_type} = MT::Page->properties->{class_type}; - return $_ unless &_check_page(@_); + return undef unless &_check_page(@_); &_hdlr_entry_next(@_); } @@ -14933,4 +17064,26 @@ =head2 PageTags + +A container tag which create a context about the assigned tags. Analogous +to L<EntryTags>. + +B<Attributes:> + +=over 4 + +=item * glue + +A string used to join the output of the separate iterations of +this tag. + +=back + +B<Example:> + +Listing out the page's tags, separated by commas: + + <mt:PageTags glue=", "><$mt:TagName$></mt:PageTags> + +=for tags pages, tags =cut @@ -14939,5 +17092,5 @@ my($ctx, $args, $cond) = @_; - return $_ unless &_check_page(@_); + return undef unless &_check_page(@_); require MT::Page; $args->{class_type} = MT::Page->properties->{class_type}; @@ -14950,4 +17103,27 @@ =head2 PageIfTagged +This template tag evaluates a block of code if a tag has been assigned +to the current entry in context. If the tag attribute is not assigned, +then the template tag will evaluate if any tag is present. + +B<Attributes:> + +=over 4 + +=item * tag + +If present, the template tag will evaluate if the specified tag is +assigned to the current page. + +=back + +B<Example:> + + <mt:PageIfTagged tag="Foo"> + <!-- do something --> + <mt:Else> + <!-- do something else --> + </mt:PageIfTagged> + =cut @@ -14955,5 +17131,5 @@ my($ctx, $args, $cond) = @_; - return $_ unless &_check_page(@_); + return undef unless &_check_page(@_); require MT::Page; $args->{class_type} = MT::Page->properties->{class_type}; @@ -14965,4 +17141,8 @@ =head2 PageFolder +A container tag which holds folder context relating to the page. + +=for tags pages, folders + =cut @@ -14970,5 +17150,5 @@ my($ctx, $args, $cond) = @_; - return $_ unless &_check_page(@_); + return undef unless &_check_page(@_); require MT::Page; $args->{class_type} = MT::Page->properties->{class_type}; @@ -14981,8 +17161,14 @@ =head2 PageID +A numeric system ID of the Page currently in context. + +B<Example:> + + <$mt:PageID$> + =cut sub _hdlr_page_id { - return $_ unless &_check_page(@_); + return undef unless &_check_page(@_); &_hdlr_entry_id(@_); } @@ -14992,8 +17178,16 @@ =head2 PageTitle +The title of the page in context. + +B<Example:> + + <$mt:PageTitle$> + +=for tags pages + =cut sub _hdlr_page_title { - return $_ unless &_check_page(@_); + return undef unless &_check_page(@_); &_hdlr_entry_title(@_); } @@ -15003,8 +17197,34 @@ =head2 PageBody +This tag outputs the contents of the page's Body field. + +If a text formatting filter has been specified, it will automatically applied. + +B<Attributes:> + +=over 4 + +=item * words + +Trims the number of words to display. By default all are displayed. + +=item * convert_breaks + +Controls the application of text formatting. By default convert_breaks is 0 +(false). This should only be used if text formatting is set to "none" in the +Entry/Page editor. + +=back + +B<Example:> + + <$mt:PageBody$> + +=for tags pages + =cut sub _hdlr_page_body { - return $_ unless &_check_page(@_); + return undef unless &_check_page(@_); &_hdlr_entry_body(@_); } @@ -15014,8 +17234,30 @@ =head2 PageMore +This tag outputs the contents of the page's Extended field. + +If a text formatting filter has been specified it will automatically applied. + +B<Attributes:> + +=over 4 + +=item * convert_breaks (optional) + +Controls the application of text formatting. By default convert_breaks is 0 +(false). This should only be used if text formatting is set to "none" in the +Entry/Page editor. + +=back + +B<Example:> + + <$mt:PageMore$> + +=for tags pages + =cut sub _hdlr_page_more { - return $_ unless &_check_page(@_); + return undef unless &_check_page(@_); &_hdlr_entry_more(@_); } @@ -15025,10 +17267,37 @@ =head2 PageDate -=for tags date +The authored on timestamp for the page. + +B<Attributes:> + +=over 4 + +=item * format + +A string that provides the format in which to publish the date. If +unspecified, the default that is appropriate for the language of the blog +is used (for English, this is "%B %e, %Y %l:%M %p"). See the L<Date> +tag for the supported formats. + +=item * language + +Forces the date to the format associated with the specified language. + +=item * utc + +Forces the date to UTC format. + +=back + +B<Example:> + + <$mt:PageDate$> + +=for tags pages, date =cut sub _hdlr_page_date { - return $_ unless &_check_page(@_); + return undef unless &_check_page(@_); &_hdlr_entry_date(@_); } @@ -15038,10 +17307,37 @@ =head2 PageModifiedDate -=for tags date +The last modified timestamp for the page. + +B<Attributes:> + +=over 4 + +=item * format + +A string that provides the format in which to publish the date. If +unspecified, the default that is appropriate for the language of the blog +is used (for English, this is "%B %e, %Y %l:%M %p"). See the L<Date> +tag for the supported formats. + +=item * language + +Forces the date to the format associated with the specified language. + +=item * utc + +Forces the date to UTC format. + +=back + +B<Example:> + + <$mt:PageModifiedDate$> + +=for tags pages, date =cut sub _hdlr_page_modified_date { - return $_ unless &_check_page(@_); + return undef unless &_check_page(@_); &_hdlr_entry_mod_date(@_); } @@ -15051,8 +17347,14 @@ =head2 PageKeywords +The specified keywords of the page in context. + +B<Example:> + + <$mt:PageKeywords$> + =cut sub _hdlr_page_keywords { - return $_ unless &_check_page(@_); + return undef unless &_check_page(@_); &_hdlr_entry_keywords(@_); } @@ -15062,8 +17364,42 @@ =head2 PageBasename +By default, the page basename is a constant and unique identifier for +an page which is used as part of the individual pages's archive filename. + +The basename is created by dirifiying the page title when the page is +first saved (regardless of the page status). From then on, barring direct +manipulation, the page basename stays constant even when you change the +page's title. In this way, Movable Type ensures that changes you make +to an page after saving it don't change the URL to the page, subsequently +breaking incoming links. + +The page basename can be modified by anyone who can edit the page. If it +is modified after it is created, it is up to the user to ensure uniqueness +and no incrementing will occur. This allows you to have complete and +total control over your URLs when you want to as well as effortless +simplicity when you don't care. + +B<Attributes:> + +=over 4 + +=item * separator (optional) + +Valid values are "_" and "-", dash is the default value. Specifying +an underscore will convert any dashes to underscores. Specifying a dash +will convert any underscores to dashes. + +=back + +B<Example:> + + <$mt:PageBasename$> + +=for tags pages + =cut sub _hdlr_page_basename { - return $_ unless &_check_page(@_); + return undef unless &_check_page(@_); &_hdlr_entry_basename(@_); } @@ -15073,8 +17409,18 @@ =head2 PagePermalink +An absolute URL pointing to the archive page containing this entry. An +anchor (#) is included if the permalink is not pointing to an +Individual Archive page. + +B<Example:> + + <$mt:PagePermalink$> + +=for tags pages, archives + =cut sub _hdlr_page_permalink { - return $_ unless &_check_page(@_); + return undef unless &_check_page(@_); &_hdlr_entry_permalink(@_); } @@ -15084,8 +17430,18 @@ =head2 PageAuthorEmail +The email address of the page's author. + +B<Note:> It is not recommended to publish email addresses. + +B<Example:> + + <$mt:PageAuthorEmail$> + +=for tags pages, authors + =cut sub _hdlr_page_author_email { - return $_ unless &_check_page(@_); + return undef unless &_check_page(@_); &_hdlr_entry_author_email(@_); } @@ -15095,8 +17451,40 @@ =head2 PageAuthorLink +A linked version of the author's user name, using the author URL if provided +in the author's profile. Otherwise, the author name is unlinked. This tag uses +the author URL if available and the author email otherwise. If neither are on +record the author name is unlinked. + +B<Attributes:> + +=over 4 + +=item * show_email + +Specifies if the author's email can be displayed. The default is false (0). + +=item * show_url + +Specifies if the author's URL can be displayed. The default is true (1). + +=item * new_window + +Specifies to open the link in a new window by adding "target=_blank" to the +anchor tag. See example below. The default is false (0). + +=back + +B<Examples:> + + <$mt:PageAuthorLink$> + + <$mt:PageAuthorLink new_window="1"$> + +=for tags pages, authors + =cut sub _hdlr_page_author_link { - return $_ unless &_check_page(@_); + return undef unless &_check_page(@_); &_hdlr_entry_author_link(@_); } @@ -15106,8 +17494,14 @@ =head2 PageAuthorURL +The URL of the page's author. + +B<Example:> + + <$mt:PageAuthorURL$> + =cut sub _hdlr_page_author_url { - return $_ unless &_check_page(@_); + return undef unless &_check_page(@_); &_hdlr_entry_author_url(@_); } @@ -15117,8 +17511,36 @@ =head2 PageExcerpt +This tag outputs the contents of the page Excerpt field if one is specified +or, if not, an auto-generated excerpt from the page Body field followed by an +ellipsis ("..."). + +The length of the auto-generated output of this tag can be set in the blog's +Entry Settings. + +B<Attributes:> + +=over 4 + +=item no_generate (optional; default "0") + +When set to 1, the system will not auto-generate an excerpt if the excerpt +field of the page is left blank. Instead it will output nothing. + +=item * convert_breaks (optional; default "0") + +When set to 1, the page's specified text formatting filter will be applied. By +default, the text formatting is not applied and the excerpt is published +either as input or auto-generated by the system. + +=back + +B<Example:> + + <$mt:PageExcerpt$> + =cut sub _hdlr_page_excerpt { - return $_ unless &_check_page(@_); + return undef unless &_check_page(@_); &_hdlr_entry_excerpt(@_); } @@ -15127,4 +17549,13 @@ =head2 BlogPageCount + +The number of published pages in the blog. This template tag supports the +multiblog template tags. + +B<Example:> + + <$mt:BlogPageCount$> + +=for tags blogs, pages, multiblog, count =cut @@ -15142,8 +17573,17 @@ =head2 PageAuthorDisplayName +The display name of the author of the page in context. If no display name is +specified, returns an empty string, and no name is displayed. + +B<Example:> + + <$mt:PageAuthorDisplayName$> + +=for tags authors + =cut sub _hdlr_page_author_display_name { - return $_ unless &_check_page(@_); + return undef unless &_check_page(@_); &_hdlr_entry_author_display_name(@_); } @@ -15152,4 +17592,20 @@ =head2 Folders + +A container tags which iterates over a list of all folders and subfolders. + +B<Attributes:> + +=over 4 + +=item * show_empty + +Setting this optional attribute to true (1) will include folders with no +pages assigned. The default is false (0), where only folders with pages +assigned. + +=back + +=for tags folders =cut @@ -15167,4 +17623,9 @@ =head2 FolderPrevious +A container tag which creates a folder context of the previous folder +relative to the current page folder or archived folder. + +=for tags folders, archiving + =cut @@ -15172,4 +17633,9 @@ =head2 FolderNext + +A container tag which creates a folder context of the next folder +relative to the current page folder or archived folder. + +=for tags folders, archiving =cut @@ -15187,4 +17653,36 @@ =head2 SubFolders +A specialized version of the L<Folders> container tag that respects +the hierarchical structure of folders. + +B<Attributes:> + +=over 4 + +=item * include_current + +An optional boolean attribute that controls the inclusion of the +current folder in the list. + +=item * sort_method + +An optional and advanced usage attribute. A fully qualified Perl method +name to be used to sort the folders. + +=item * sort_order + +Specifies the sort order of the folder labels. Recognized values +are "ascend" and "descend." The default is "ascend." This attribute +is ignored if C<sort_method> is unspecified. + +=item * top + +If set to 1, displays only top level folders. Same as using +L<TopLevelFolders>. + +=back + +=for tags folders + =cut @@ -15201,4 +17699,47 @@ =head2 SubFolderRecurse +Recursively call the L<SubFolders> or L<TopLevelFolders> container +with the subfolders of the folder in context. This tag, when placed at the +end of loop controlled by one of the tags above will cause them to +recursively descend into any subfolders that exist during the loop. + +B<Attributes:> + +=over 4 + +=item * max_depth (optional) + +Specifies the maximum number of times the system should recurse. The default +is infinite depth. + +=back + +B<Examples:> + +The following code prints out a recursive list of folders/subfolders, linking +those with entries assigned to their folder archive pages. + + <mt:TopLevelFolders> + <mt:SubFolderIsFirst><ul></mt:SubFolderIsFirst> + <mt:If tag="FolderCount"> + <li><a href="<$mt:FolderArchiveLink$>" + title="<$mt:FolderDescription$>"><$mt:FolderLabel$></a> + <mt:Else> + <li><$mt:FolderLabel$> + </mt:If> + <$mt:SubFolderRecurse$> + </li> + <mt:SubFolderIsLast></ul></mt:SubFolderIsLast> + </mt:TopLevelFolders> + +Or more simply: + + <mt:TopLevelFolders> + <$mt:FolderLabel$> + <$mt:SubFolderRecurse$> + </mt:TopLevelFolders> + +=for tags folders + =cut @@ -15215,4 +17756,24 @@ =head2 ParentFolders +A block tag that lists all the ancestors of the current folder. + +B<Attributes:> + +=over 4 + +=item * glue + +This optional attribute is a shortcut for connecting each folder label +with its value. Single and double quotes are not permitted in the string. + +=item * exclude_current + +This optional boolean attribute controls the exclusion of the current +folder in the list. + +=back + +=for tags folders + =cut @@ -15229,4 +17790,14 @@ =head2 ParentFolder +A container tag that creates a context to the current folder's parent. + +B<Example:> + + <mt:ParentFolder> + Up: <a href="<mt:ArchiveLink>"><mt:FolderLabel></a> + </mt:ParentFolder> + +=for tags folders + =cut @@ -15243,4 +17814,13 @@ =head2 TopLevelFolders +A block tag listing the folders that do not have a parent and exist at "the +top" of the folder hierarchy. Same as using C<E<lt>mt:SubFolders top="1"E<gt>>. + +B<Example:> + + <mt:TopLevelFolders> + <!-- do something --> + </mt:TopLevelFolders> + =cut @@ -15257,4 +17837,9 @@ =head2 TopLevelFolder +A container tag that creates a context to the top-level ancestor of +the current folder. + +=for tags folders + =cut @@ -15271,8 +17856,32 @@ =head2 FolderBasename +Produces the dirified basename defined for the folder in context. + +B<Attributes:> + +=over 4 + +=item * default + +A value to use in the event that no folder is in context. + +=item * separator + +Valid values are "_" and "-", dash is the default value. Specifying +an underscore will convert any dashes to underscores. Specifying a +dash will convert any underscores to dashes. + +=back + +B<Example:> + + <$mt:FolderBasename$> + +=for tags folders + =cut sub _hdlr_folder_basename { - return $_ unless &_check_folder(@_); + return undef unless &_check_folder(@_); return _hdlr_category_basename(@_); } @@ -15282,8 +17891,16 @@ =head2 FolderDescription +The description for the folder in context. + +B<Example:> + + <$mt:FolderDescription$> + +=for tags folders + =cut sub _hdlr_folder_description { - return $_ unless &_check_folder(@_); + return undef unless &_check_folder(@_); return _hdlr_category_desc(@_); } @@ -15293,8 +17910,16 @@ =head2 FolderID +The numeric system ID of the folder. + +B<Example:> + + <$mt:FolderID$> + +=for tags folders + =cut sub _hdlr_folder_id { - return $_ unless &_check_folder(@_); + return undef unless &_check_folder(@_); return _hdlr_category_id(@_); } @@ -15304,8 +17929,16 @@ =head2 FolderLabel +The label of the folder in context. + +B<Example:> + + <$mt:FolderLabel$> + +=for tags folders + =cut sub _hdlr_folder_label { - return $_ unless &_check_folder(@_); + return undef unless &_check_folder(@_); return _hdlr_category_label(@_); } @@ -15315,8 +17948,16 @@ =head2 FolderCount +The number published pages in the folder. + +B<Example:> + + <$mt:FolderCount$> + +=for tags folders, pages + =cut sub _hdlr_folder_count { - return $_ unless &_check_folder(@_); + return undef unless &_check_folder(@_); return _hdlr_category_count(@_); } @@ -15326,8 +17967,17 @@ =head2 FolderPath +The path to the folder, relative to the L<BlogURL>. + +B<Example:> + +For the folder "Bar" in a folder "Foo" C<E<lt>$mt:FolderPath$E<gt>> +becomes foo/bar. + +=for tags folders + =cut sub _hdlr_folder_path { - return $_ unless &_check_folder(@_); + return undef unless &_check_folder(@_); return _hdlr_sub_category_path(@_); } @@ -15337,8 +17987,31 @@ =head2 IfFolder +A conditional tag used to test for the folder assignment for the page +in context, or generically to test for which folder is in context. + +B<Attributes:> + +=over 4 + +=item * name (or label; optional) + +The name of a folder. If given, tests the folder in context (or +folder of an entry in context) to see if it matches with the given +folder name. + +=back + +B<Example:> + + <mt:IfFolder name="News"> + (current page in context is in the "News" folder) + </mt:IfFolder> + +=for tags pages, folders + =cut sub _hdlr_if_folder { - return $_ unless &_check_folder(@_); + return undef unless &_check_folder(@_); return _hdlr_if_category(@_); } @@ -15348,8 +18021,11 @@ =head2 FolderHeader +The contents of this container tag will be displayed when the first +folder listed by a L<Folders> tag is reached. + =cut sub _hdlr_folder_header { - return $_ unless &_check_folder(@_); + return undef unless &_check_folder(@_); my ($ctx) = @_; $ctx->stash('folder_header'); @@ -15360,8 +18036,13 @@ =head2 FolderFooter +The contents of this container tag will be displayed when the last +folder listed by a L<Folders> tag is reached. + +=for tags folders + =cut sub _hdlr_folder_footer { - return $_ unless &_check_folder(@_); + return undef unless &_check_folder(@_); my ($ctx) = @_; $ctx->stash('folder_footer'); @@ -15372,8 +18053,12 @@ =head2 HasSubFolders +Returns true if the current folder has a sub-folder. + +=for tags folders + =cut sub _hdlr_has_sub_folders { - return $_ unless &_check_folder(@_); + return undef unless &_check_folder(@_); &_hdlr_has_sub_categories(@_); } @@ -15383,8 +18068,13 @@ =head2 HasParentFolder +Returns true if the current folder has a parent folder other than the +root. + +=for tags folders + =cut sub _hdlr_has_parent_folder { - return $_ unless &_check_folder(@_); + return undef unless &_check_folder(@_); &_hdlr_has_parent_category(@_); } @@ -15395,7 +18085,7 @@ my $cat = ($ctx->stash('category')) || (($e = $ctx->stash('entry')) && $e->category) - or return MT->translate( + or return $ctx->error(MT->translate( "You used an [_1] tag outside of the proper context.", - 'MT' . $ctx->stash('tag') ); + 'MT' . $ctx->stash('tag') )); 1; } @@ -15405,5 +18095,5 @@ my $e = $ctx->stash('entry') or return $ctx->_no_page_error(); - return $ctx->_no_page_error('MT'.$ctx->stash('tag')) + return $ctx->_no_page_error() if ref $e ne 'MT::Page'; 1; @@ -15428,5 +18118,24 @@ =head2 EntryScore -=for tags entry, scoring +A function tag that provides total score of the entry in context. Scores +grouped by namespace of a plugin are summed to calculate total score of an +entry. + +B<Attributes:> + +=over 4 + +=item * namespace (required) + +Specify namespace for score to be calculated. Namespace is defined by each +plugin which leverages rating API. + +=back + +B<Example:> + + <$mt:EntryScore namespace="FiveStarRating"$> + +=for tags entries, scoring =cut @@ -15440,4 +18149,23 @@ =head2 CommentScore +A function tag that provides total score of the comment in context. Scores +grouped by namespace of a plugin are summed to calculate total score of a +comment. + +B<Attributes:> + +=over 4 + +=item * namespace (required) + +Specify namespace for score to be calculated. Namespace is defined by each +plugin which leverages rating API. + +=back + +B<Example:> + + <$mt:CommentScore namespace="FiveStarRating"$> + =for tags comments, scoring @@ -15452,4 +18180,23 @@ =head2 PingScore +A function tag that provides total score of the TrackBack ping in context. +Scores grouped by namespace of a plugin are summed to calculate total +score of a TrackBack ping. + +B<Attributes:> + +=over 4 + +=item * namespace (required) + +Specify namespace for the score to be sorted. Namespace is defined by each +plugin which leverages rating API. + +=back + +B<Example:> + + <$mt:PingScore namespace="FiveStarRating"$> + =for tags pings, scoring @@ -15464,4 +18211,23 @@ =head2 AssetScore +A function tag that provides total score of the asset in context. Scores +grouped by namespace of a plugin are summed to calculate total score of an +asset. + +B<Attributes:> + +=over 4 + +=item * namespace (required) + +Specify namespace for score to be calculated. Namespace is defined by each +plugin which leverages rating API. + +=back + +B<Example:> + + <$mt:AssetScore namespace="FiveStarRating"$> + =for tags assets, scoring @@ -15475,4 +18241,23 @@ =head2 AuthorScore + +A function tag that provides total score of the author in context. Scores +grouped by namespace of a plugin are summed to calculate total score of an +author. + +B<Attributes:> + +=over 4 + +=item * namespace (required) + +Specify namespace for score to be calculated. Namespace is defined by each +plugin which leverages rating API. + +=back + +B<Example:> + + <$mt:AuthorScore namespace="FiveStarRating"$> =for tags authors, scoring @@ -15497,4 +18282,23 @@ =head2 EntryScoreHigh +A function tag that provides the highest score of the entry in context. +Scorings grouped by namespace of a plugin are sorted to find the highest +score of an entry. + +B<Attributes:> + +=over 4 + +=item * namespace (required) + +Specify namespace for score to be calculated. Namespace is defined by each +plugin which leverages rating API. + +=back + +B<Example:> + + <$mt:EntryScoreHigh namespace="FiveStarRating"$> + =for tags entries, scoring @@ -15509,4 +18313,23 @@ =head2 CommentScoreHigh +A function tag that provides the highest score of the comment in context. +Scorings grouped by namespace of a plugin are sorted to find the +highest score of a comment. + +B<Attributes:> + +=over 4 + +=item * namespace (required) + +Specify namespace for the score to be sorted. Namespace is defined by each +plugin which leverages rating API. + +=back + +B<Example:> + + <$mt:CommentScoreHigh namespace="FiveStarRating"$> + =for tags comments, scoring @@ -15521,4 +18344,23 @@ =head2 PingScoreHigh +A function tag that provides the highest score of the TrackBack ping +in context. Scorings grouped by namespace of a plugin are sorted to +find the highest score of a TrackBack ping. + +B<Attributes:> + +=over 4 + +=item * namespace (required) + +Specify namespace for the score to be sorted. Namespace is defined by each +plugin which leverages rating API. + +=back + +B<Example:> + + <$mt:PingScoreHigh namespace="FiveStarRating"$> + =for tags pings, scoring @@ -15533,4 +18375,23 @@ =head2 AssetScoreHigh +A function tag that provides the highest score of the asset in context. +Scorings grouped by namespace of a plugin are sorted to find the +highest score of an asset. + +B<Attributes:> + +=over 4 + +=item * namespace (required) + +Specify namespace for the score to be sorted. Namespace is defined by each +plugin which leverages rating API. + +=back + +B<Example:> + + <$mt:AssetScoreHigh namespace="FiveStarRating"$> + =for tags assets, scoring @@ -15544,4 +18405,23 @@ =head2 AuthorScoreHigh + +A function tag that provides the highest score of the author in context. +Scorings grouped by namespace of a plugin are sorted to find the +highest score of an author. + +B<Attributes:> + +=over 4 + +=item * namespace (required) + +Specify namespace for the score to be sorted. Namespace is defined by each +plugin which leverages rating API. + +=back + +B<Example:> + + <$mt:AuthorScoreHigh namespace="FiveStarRating"$> =for tags authors, scoring @@ -15566,4 +18446,23 @@ =head2 EntryScoreLow +A function tag that provides the lowest score of the entry in context. +Scorings grouped by namespace of a plugin are sorted to find the +lowest score of an entry. + +B<Attributes:> + +=over 4 + +=item * namespace (required) + +Specify namespace for the score to be sorted. Namespace is defined by each +plugin which leverages rating API. + +=back + +B<Example:> + + <$mt:EntryScoreLow namespace="FiveStarRating"$> + =for tags entries, scoring @@ -15578,4 +18477,23 @@ =head2 CommentScoreLow +A function tag that provides the lowest score of the comment in context. +Scorings grouped by namespace of a plugin are sorted to find the lowest score +of a comment. + +B<Attributes:> + +=over 4 + +=item * namespace (required) + +Specify namespace for the score to be sorted. Namespace is defined by each +plugin which leverages rating API. + +=back + +B<Example:> + + <$mt:CommentScoreLow namespace="FiveStarRating"$> + =for tags comments, scoring @@ -15590,4 +18508,21 @@ =head2 PingScoreLow +A function tag that provides the lowest score of the TrackBack ping in context. Scorings grouped by namespace of a plugin are sorted to find the lowest score of a TrackBack ping. + +B<Attributes:> + +=over 4 + +=item * namespace (required) + +Specify namespace for the score to be sorted. Namespace is defined by each +plugin which leverages rating API. + +=back + +B<Example:> + + <$mt:PingScoreLow namespace="FiveStarRating"$> + =for tags pings, scoring @@ -15602,4 +18537,23 @@ =head2 AssetScoreLow +A function tag that provides the lowest score of the asset in context. +Scorings grouped by namespace of a plugin are sorted to find the lowest +score of an asset. + +B<Attributes:> + +=over 4 + +=item * namespace (required) + +Specify namespace for the score to be sorted. Namespace is defined by each +plugin which leverages rating API. + +=back + +B<Example:> + + <$mt:AssetScoreLow namespace="FiveStarRating"$> + =for tags assets, scoring @@ -15613,4 +18567,23 @@ =head2 AuthorScoreLow + +A function tag that provides the lowest score of the author in context. +Scorings grouped by namespace of a plugin are sorted to find the lowest +score of an author. + +B<Attributes:> + +=over 4 + +=item * namespace (required) + +Specify namespace for the score to be sorted. Namespace is defined by each +plugin which leverages rating API. + +=back + +B<Example:> + + <$mt:AuthorScoreLow namespace="FiveStarRating"$> =for tags authors, scoring @@ -15637,4 +18610,24 @@ =head2 EntryScoreAvg +A function tag that provides the avarage score of the entry in context. Scores +grouped by namespace of a plugin are summed to calculate total score of an +entry, and average is calculated by dividing the total score by the number of +scorings or 'votes'. + +B<Attributes:> + +=over 4 + +=item * namespace (required) + +Specify namespace for avarage score to be calculated. Namespace is defined by +each plugin which leverages rating API. + +=back + +B<Example:> + + <$mt:EntryScoreAvg namespace="FiveStarRating"$> + =for tags entries, scoring @@ -15649,4 +18642,24 @@ =head2 CommentScoreAvg +A function tag that provides the avarage score of the comment in context. +Scores grouped by namespace of a plugin are summed to calculate total +score of a comment, and average is calculated by dividing the total +score by the number of scorings or 'votes'. + +B<Attributes:> + +=over 4 + +=item * namespace (required) + +Specify namespace for avarage score to be calculated. Namespace is defined by +each plugin which leverages rating API. + +=back + +B<Example:> + + <$mt:CommentScoreAvg namespace="FiveStarRating"$> + =for tags comments, scoring @@ -15661,4 +18674,24 @@ =head2 PingScoreAvg +A function tag that provides the avarage score of the TrackBack ping in +context. Scores grouped by namespace of a plugin are summed to calculate +total score of a TrackBack ping, and average is calculated by dividing the +total score by the number of scorings or 'votes'. + +B<Attributes:> + +=over 4 + +=item * namespace (required) + +Specify namespace for avarage score to be calculated. Namespace is defined by +each plugin which leverages rating API. + +=back + +B<Example:> + + <$mt:PingScoreAvg namespace="FiveStarRating"$> + =for tags pings, scoring @@ -15673,4 +18706,24 @@ =head2 AssetScoreAvg +A function tag that provides the avarage score of the asset in context. +Scores grouped by namespace of a plugin are summed to calculate total +score of an asset, and average is calculated by dividing the total +score by the number of scorings or 'votes'. + +B<Attributes:> + +=over 4 + +=item * namespace (required) + +Specify namespace for avarage score to be calculated. Namespace is defined by +each plugin which leverages rating API. + +=back + +B<Example:> + + <$mt:AssetScoreAvg namespace="FiveStarRating"$> + =for tags assets, scoring @@ -15684,4 +18737,24 @@ =head2 AuthorScoreAvg + +A function tag that provides the avarage score of the author in context. +Scores grouped by namespace of a plugin are summed to calculate total score of +an author, and average is calculated by dividing the total score by the number +of scorings or 'votes'. + +B<Attributes:> + +=over 4 + +=item * namespace (required) + +Specify namespace for avarage score to be calculated. Namespace is defined by +each plugin which leverages rating API. + +=back + +B<Example:> + + <$mt:AuthorScoreAvg namespace="FiveStarRating"$> =for tags authors, scoring @@ -15708,5 +18781,23 @@ =head2 EntryScoreCount -=for tags entry, scoring +A function tag that provides the number of scorings or 'votes' made to the +entry in context. Scorings grouped by namespace of a plugin are summed. + +B<Attributes:> + +=over 4 + +=item * namespace (required) + +Specify namespace for the number of scorings to be calculated. Namespace is +defined by each plugin which leverages rating API. + +=back + +B<Example:> + + <$mt:EntryScoreCount namespace="FiveStarRating"$> + +=for tags entries, scoring =cut @@ -15720,4 +18811,23 @@ =head2 CommentScoreCount +A function tag that provides the number of scorings or 'votes' made to +the comment in context. Scorings grouped by namespace of a plugin are +summed. + +B<Attributes:> + +=over 4 + +=item * namespace (required) + +Specify namespace for the number of scorings to be calculated. Namespace is +defined by each plugin which leverages rating API. + +=back + +B<Example:> + + <$mt:CommentScoreCount namespace="FiveStarRating"$> + =for tags comments, scoring @@ -15732,4 +18842,23 @@ =head2 PingScoreCount +A function tag that provides the number of scorings or 'votes' made to the +TrackBack ping in context. Scorings grouped by namespace of a plugin are +summed. + +B<Attributes:> + +=over 4 + +=item * namespace (required) + +Specify namespace for the number of scorings to be calculated. Namespace is +defined by each plugin which leverages rating API. + +=back + +B<Example:> + + <$mt:PingScoreCount namespace="FiveStarRating"$> + =for tags pings, scoring @@ -15744,5 +18873,23 @@ =head2 AssetScoreCount -pings assets, scoring +A function tag that provides the number of scorings or 'votes' made to the +asset in context. Scorings grouped by namespace of a plugin are summed. + +B<Attributes:> + +=over 4 + +=item * namespace (required) + +Specify namespace for the number of scorings to be calculated. Namespace is +defined by each plugin which leverages rating API. + +=back + +B<Example:> + + <$mt:AssetScoreCount namespace="FiveStarRating"$> + +=for tags assets, scoring =cut @@ -15755,4 +18902,22 @@ =head2 AuthorScoreCount + +A function tag that provides the number of scorings or 'votes' made to the +author in context. Scorings grouped by namespace of a plugin are summed. + +B<Attributes:> + +=over 4 + +=item * namespace (required) + +Specify namespace for the number of scorings to be calculated. Namespace is +defined by each plugin which leverages rating API. + +=back + +B<Example:> + + <$mt:AuthorScoreCount namespace="FiveStarRating"$> =for tags authors, scoring @@ -15776,4 +18941,26 @@ =head2 EntryRank + +A function tag which returns a number from 1 to 6 (by default) which +represents the rating of the entry in context in terms of total +score where '1' is used for the highest score, '6' for the lowest score. + +B<Attributes:> + +=over 4 + +=item * namespace (required) + +Specify namespace for rank to be calculated. Namespace is defined by each plugin which leverages rating API. + +=item * max (optional; default "6") + +Allows a user to specify the upper bound of the scale. + +=back + +B<Example:> + + <$mt:EntryRank namespace="FiveStarRating"$> =for tags entries, scoring @@ -15801,4 +18988,26 @@ =head2 CommentRank +A function tag which returns a number from 1 to 6 (by default) which +represents the rating of the comment in context in terms of total score +where '1' is used for the highest score, '6' for the lowest score. + +B<Attributes:> + +=over 4 + +=item * namespace (required) + +Specify namespace for rank to be calculated. Namespace is defined by each plugin which leverages rating API. + +=item * max (optional; default "6") + +Allows a user to specify the upper bound of the scale. + +=back + +B<Example:> + + <$mt:CommentRank namespace="FiveStarRating"$> + =for tags comments, scoring @@ -15821,4 +19030,26 @@ =head2 PingRank +A function tag which returns a number from 1 to 6 (by default) which +represents the rating of the TrackBack ping in context in terms of total score +where '1' is used for the highest score, '6' for the lowest score. + +B<Attributes:> + +=over 4 + +=item * namespace (required) + +Specify namespace for rank to be calculated. Namespace is defined by each plugin which leverages rating API. + +=item * max (optional; default "6") + +Allows a user to specify the upper bound of the scale. + +=back + +B<Example:> + + <$mt:PingRank namespace="FiveStarRating"$> + =for tags pings, scoring @@ -15841,4 +19072,26 @@ =head2 AssetRank +A function tag which returns a number from 1 to 6 (by default) which +represents the rating of the asset in context in terms of total score where +'1' is used for the highest score, '6' for the lowest score. + +B<Attributes:> + +=over 4 + +=item * namespace (required) + +Specify namespace for rank to be calculated. Namespace is defined by each plugin which leverages rating API. + +=item * max (optional; default "6") + +Allows a user to specify the upper bound of the scale. + +=back + +B<Example:> + + <$mt:AssetRank namespace="FiveStarRating"$> + =for tags assets, scoring @@ -15853,4 +19106,26 @@ =head2 AuthorRank +A function tag which returns a number from 1 to 6 (by default) which +represents the rating of the author in context in terms of total score where +'1' is used for the highest score, '6' for the lowest score. + +B<Attributes:> + +=over 4 + +=item * namespace (required) + +Specify namespace for rank to be calculated. Namespace is defined by each plugin which leverages rating API. + +=item * max (optional; default "6") + +Allows a user to specify the upper bound of the scale. + +=back + +B<Example:> + + <$mt:AuthorRank namespace="FiveStarRating"$> + =for tags authors, scoring @@ -15865,5 +19140,15 @@ =head2 AuthorNext -=for tags authors +A container tag which creates a author context of the next author. The +order of authors is determined by author's login name. Authors who have +at least a published entry will be considered in finding the next author. + +B<Example:> + + <mt:AuthorNext> + <a href="<$mt:ArchiveLink archive_type="Author"$>"><$mt:AuthorDisplayName$></a> + </mt:AuthorNext> + +=for tags authors, archiving =cut @@ -15873,5 +19158,15 @@ =head2 AuthorPrevious -=for tags authors +A container tag which creates a author context of the previous author. The +order of authors is determined by author's login name. Authors who have +at least a published entry will be considered in finding the previous author. + +B<Example:> + + <mt:AuthorPrevious> + <a href="<$mt:ArchiveLink archive_type="Author"$>"><$mt:AuthorDisplayName$></a> + </mt:AuthorPrevious> + +=for tags authors, archiving =cut @@ -15923,5 +19218,55 @@ =head2 Section -=for tags utility +A utility block tag that is used to wrap content that can be cached, +or merely manipulated by any of Movable Type's tag modifiers. + +B<Attributes:> + +=over 4 + +=item * cache_prefix (optional) + +When specified, causes the contents of the section tag to be cached +for some period of time. The 'period' attribute can specify the +cache duration (in seconds), or will use the C<DashboardCachePeriod> +configuration setting as a default (this feature was initially added +to support cacheable portions of the Movable Type Dashboard). + +=item * period (optional) + +A number in seconds defining the duration to cache the content produced +by the tag. Use in combination with the 'cache_prefix' attribute. + +=item * by_blog (optional) + +When using the 'cache_prefix' attribute, specifying '1' for this +attribute will cause the content to be cached on a per-blog basis +(otherwise, the default is system-wide). + +=item * by_user (optional) + +When using the 'cache_prefix' attribute, specifying '1' for this +attribute will cause the content to be cached on a per-user basis +(otherwise, the default is system-wide). + +=item * html_tag (optional) + +If specified, causes the content of the tag to be enclosed in a +the HTML tag identified. Example: + + <mt:Section html_tag="p">Lorem ipsum...</mt:Section> + +Which would output: + + <p>Lorem ipsum...</p> + +=item * id (optional) + +If specified in combination with the 'html_tag' attribute, this 'id' +is added to the wrapping HTML tag. + +=back + +=for tags utility, templating =cut @@ -16285,4 +19630,8 @@ =head2 WidgetManager +An alias for the L<WidgetSet> tag, and considered deprecated. + +=for tags deprecated + =cut @@ -16290,4 +19639,28 @@ =head2 WidgetSet + +Publishes the widget set identified by the C<name> attribute. + +B<Attributes:> + +=over 4 + +=item * name (required) + +The name of the widget set to publish. + +=item * blog_id (optional) + +The target blog to use as a context for loading the widget set. This only +affects the loading of the widget set: it does not set the blog context +for the widgets that are published. By default, the blog in context is +used. You may specify a value of "0" for blog_id to target a global +widget set. + +=back + +B<Example:> + + <$mt:WidgetSet name="Sidebar"$> =for tags widgets Index: /branches/release-41/lib/MT/Template/Context/Search.pm =================================================================== --- /branches/release-41/lib/MT/Template/Context/Search.pm (revision 2420) +++ /branches/release-41/lib/MT/Template/Context/Search.pm (revision 2742) @@ -39,4 +39,52 @@ ########################################################################### +=head2 IfStraightSearch + +A conditional block which outputs its contents if the search in progress +is a regular (or "straight") search. + +=for tags search + +=cut + +########################################################################### + +=head2 IfTagSearch + +A conditional block which outputs its contents if the search in progress +is a search of entries by tag. + +=for tags search + +=cut + +########################################################################### + +=head2 NoSearch + +A container tag whose contents are displayed only if there is no search +performed. + +This tag is only recognized in search templates. + +=for tags search + +=cut + +########################################################################### + +=head2 NoSearchResults + +A container tag whose contents are displayed if a search is performed +but no results are found. + +This tag is only recognized in search templates. + +=for tags search + +=cut + +########################################################################### + =head2 SearchResultsHeader @@ -48,4 +96,10 @@ This tag is only recognized in SearchResults block. +B<Example:> + + <mt:SearchResultsHeader> + <h3>Look what we found!</h3> + </mt:SearchResultsHeader> + =for tags search @@ -61,4 +115,11 @@ This tag is only recognized in SearchResults block. + +B<Example:> + + <mt:SearchResultsFooter> + <p>If you didn't find what you were looking for, you can also peruse + the <a href="<mt:Link identifier="archive_index">">site archives</a>.</p> + </mt:SearchResultsFooter> =for tags search @@ -110,4 +171,6 @@ This tag is only recognized in search templates. +=for tags search + =cut @@ -124,8 +187,68 @@ =cut +########################################################################### + +=head2 SearchIncludeBlogs + +Used in the search result template to pass the IncludeBlogs parameters +through from the search form keeping the context of any followup search +the same as the initial search. + +B<Example:> + + <input type="hidden" name="IncludeBlogs" value="<$mt:SearchIncludeBlogs$>" /> + +=cut + sub _hdlr_include_blogs { $_[0]->stash('include_blogs') || '' } + +########################################################################### + +=head2 SearchString + +An HTML-encoded search query. This tag is only recognized in search templates. + +B<Example:> + + <$mt:SearchString$> + +=for tags search + +=cut + sub _hdlr_search_string { $_[0]->stash('search_string') || '' } + +########################################################################### + +=head2 SearchTemplateID + +Returns the identifier of the search template (ie, "feed" or +"nomorepizzaplease"). + +B<Example:> + + <$mt:SearchTemplateID$> + +=for tags search + +=cut + sub _hdlr_template_id { $_[0]->stash('template_id') || '' } sub _hdlr_max_results { $_[0]->stash('maxresults') || '' } + +########################################################################### + +=head2 SearchResultCount + +The number of results found across all of the blogs searched. This tag +is only recognized in search templates. + +B<Example:> + + <$mt:SearchResultCount$> + +=for tags search, count + +=cut sub _hdlr_result_count { @@ -133,4 +256,18 @@ $results ? $results : 0; } + +########################################################################### + +=head2 SearchResults + +A container tag that creates a list of search results. This tag +creates an entry and blog context that all Entry* and Blog* tags +can be used. + +This tag is only recognized in search templates. + +=for tags search + +=cut sub _hdlr_results { Index: /branches/release-41/t/91-tagcoverage.t =================================================================== --- /branches/release-41/t/91-tagcoverage.t (revision 2742) +++ /branches/release-41/t/91-tagcoverage.t (revision 2742) @@ -0,0 +1,69 @@ +#!/usr/bin/perl + +use strict; +use lib 't/extlib', 't/lib', 'extlib', 'lib'; +use Test::More; +use MT::Test; +use Data::Dumper; + +my @core_docs = qw( + lib/MT/Template/ContextHandlers.pm + lib/MT/Template/Context/Search.pm +); + +my $mt = MT->instance; +my $tags = $mt->component('core')->registry('tags'); + +my $tag_count = (scalar keys(%{ $tags->{function} }) + + scalar keys(%{ $tags->{modifier} }) + + scalar keys(%{ $tags->{block} })) + - 3; # the registry gives us an extra 'plugin' key for each element +plan tests => $tag_count; + +my $core_docs = ''; +{ + local $/ = undef; + foreach my $file ( @core_docs ) { + # core tag docs are embedded as POD + open DOC, "< $file"; + $core_docs .= <DOC>; + close DOC; + } +} + +# Determine if the core tags have adequate documentation or not. +my $doc_names = {}; +while ($core_docs =~ m/\n=head2[ ]+([\w:]+)[ ]*\n(.*?)?\n=cut[ ]*\n/gs) { + my $tag = $1; + my $docs = defined $2 ? $2 : ''; + $docs =~ s/\r//g; # for windows newlines + # ignore comment lines + $docs =~ s/^#.*//gm; + # ignore empty lines + $docs =~ s/^\s*$//gm; + # strip any '=for ...', etc. directive. docs should be above this + $docs =~ s/(^|\n)=\w+.*//s; + # strip trailing/leading newlines + $docs =~ s/^\n+//s; + $docs =~ s/\n+$//s; + # if documentation block doesn't have anything left, the tag is undocumented + next if $docs eq ''; + $doc_names->{lc $tag} = 1; +} + +foreach my $tag ( keys %{ $tags->{function} } ) { + next if $tag eq 'plugin'; + ok(exists $doc_names->{lc $tag}, "function tag $tag"); +} + +foreach my $tag ( keys %{ $tags->{block} } ) { + next if $tag eq 'plugin'; + $tag =~ s/\?$//; + ok(exists $doc_names->{lc $tag}, "block tag $tag"); +} + +foreach my $tag ( keys %{ $tags->{modifier} } ) { + next if $tag eq 'plugin'; + ok(exists $doc_names->{lc $tag}, "modifier $tag"); +} +