Changeset 2742

Timestamp:

07/09/08 20:16:36 (5 months ago)

Author:

bchoate

Message:

Updated POD for template tags; added test for template tag doc coverage.

Files:

• branches/release-41/lib/MT/Template/Context/Search.pm (modified) (6 diffs)
• branches/release-41/lib/MT/Template/ContextHandlers.pm (modified) (343 diffs)
• branches/release-41/t/91-tagcoverage.t (added)

branches/release-41/lib/MT/Template/Context/Search.pm

@@ -39 +39 @@
-###########################################################################
-
+=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 +96 @@
-This tag is only recognized in SearchResults block.
-
+B<Example:>
+
+    <mt:SearchResultsHeader>
+    <h3>Look what we found!</h3>
+    </mt:SearchResultsHeader>
+
-=for tags search
-
@@ -61 +115 @@
-
-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 +171 @@
-This tag is only recognized in search templates.
-
+=for tags search
+
-=cut
-
@@ -124 +187 @@
-=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 +256 @@
-    $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 {

branches/release-41/lib/MT/Template/ContextHandlers.pm

@@ -1075 +1075 @@
-###########################################################################
-
+=head2 string_format
+
+An alias for the 'sprintf' modifier.
+
+=cut
+
+###########################################################################
+
-=head2 sprintf
-
@@ -1228 +1236 @@
-=over 4
-
-
+* 
-
-Similar to the 'encode_html' modifier. Escapes special characters as
-HTML entities.
-
-
+* 
-
-Similar to the 'encode_url' modifier. Escapes special characters using
-a URL-encoded format (ie, " " becomes "%20").
-
-
+* 
-
-Similar to the 'encode_js' modifier. Escapes special characters such
@@ -1244 +1252 @@
-in a JavaScript string.
-
-
+* 
-
-A very simple email obfuscation technique.
@@ -1455 +1463 @@
-###########################################################################
-
+=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<Example:>
+
+    <$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<Example:>
+
+    <mt:Ignore>
+        The API key for the following tag is D3ADB33F.
+    </mt:Ignore>
+
+=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 +1589 @@
-=over 4
-
-
+* 
-
-The C<MT::Object> object type the listing is processing. If unset,
-will use the contents of the C<object_type> variable.
-
-
+* 
-
-The source of data to process. This is an array of hashes, similar
@@ -1537 +1600 @@
-variable is used instead.
-
-
+* 
-
-Used when there are no rows to output for the listing. If not set,
@@ -1544 +1607 @@
-found.
-
-
+* 
-
-Used to construct the DOM id for the listing. The outer C<div> tag
@@ -1551 +1614 @@
-attribute).
-
-
+* 
-
-Provides a custom class name that can be applied to the main
@@ -1557 +1620 @@
-that is always applied).
-
-
+* 
-
-Supplies the 'action' attribute of the C<form> tag produced.
-
-
+* 
-
-Controls whether the pagination controls are shown or not.
-If unspecified, pagination is shown.
-
-
+* 
-
-Controls whether the actions associated with the object type
@@ -1677 +1740 @@
-=over 4
-
-
+* 
-
-Maps to a '__mode' argument.
-
-
+* 
-
-Maps to a '_type' argument.
@@ -1741 +1804 @@
-=over 4
-
-
+* 
-
-Assigns a CSS class name indicating whether the control is above or
-below the listing or edit form it is associated with.
-
-
+* 
-
-Assign either 1 or 0 to control whether the pagination controls are
-displayed or not.
-
-
+* 
-
-Associates the pagition controls and item action widget with the
@@ -1793 +1856 @@
-=over 4
-
-
+* 
-
-If specified, will be used as the 'id' attribute for the outermost C<div>
@@ -1799 +1862 @@
-variable instead.
-
-
+* 
-
-The label to display above the widget.
-
-
+* 
-
-If specified, this link will wrap the label for the widget.
-
-
+* 
-
-If specified, this JavaScript code will be assigned to the 'onclick'
-attribute of a link tag wrapping the widget label.
-
-
+* 
-
-If unspecified, will use the id of the widget. This class is included in the
-'class' attribute of the outermost C<div> tag for the widget.
-
-
-
-
+* 
+
+* 
-
-Identifies whether widget may be closed or not.
-
-
+* 
-
-If specified, the widget will be assigned an attribute that gives it
@@ -1932 +1995 @@
-=over 4
-
-
-
-
-
-
+* 
+
+* 
+
+* 
-
-Accepted values: "all", "index".
-
-
+* 
-
-=back
@@ -2063 +2126 @@
-=over 4
-
-
+* 
-
-Identifies the URL to submit the form to. If not given, will use
-the current application URI.
-
-
+* 
-
-Supplies the C<form> method. "GET" or "POST" are the typical values
-for this, but will accept any HTTP-compatible method (ie: "PUT", "DELETE").
-
-
+* 
-
-Populates a hidden 'id' field in the form. If not given, will also use any
-'id' template variable defined.
-
-
+* 
-
-Populates a hidden 'blog_id' field in the form. If not given, will also use
-any 'blog_id' template variable defined.
-
-
+* 
-
-Populates a hidden '_type' field in the form. If not given, will also use
-any 'type' template variable defined.
-
-
+* 
-
-Used to form the 'id' element of the HTML C<form> tag. If not specified,
@@ -2094 +2157 @@
-determined object_type.
-
-
+* 
-
-Supplies the C<form> name attribute. If unspecified, will use the C<id>
-attribute, if available.
-
-
+* 
-
-If assigned, sets an 'enctype' attribute on the C<form> tag using the value
@@ -2175 +2238 @@
-=over 4
-
-
+* 
-
-A unique identifier for this group of settings.
-
-
+* 
-
-If specified, applies this CSS class to the C<fieldset> tag produced.
-
-
+* 
-
-Controls whether the C<fieldset> is initially shown or not. If hidden,
@@ -2230 +2293 @@
-=over 4
-
-
+* 
-
-Each application setting tag requires a unique 'id' attribute. This id
-should not be re-used within the template.
-
-
+* 
-
-Controls whether the field is displayed with visual cues that the
-field is a required field or not.
-
-
+* 
-
-Supplies the label phrase for the setting.
-
-
+* 
-
-Controls whether the label portion of the setting is shown or not.
-
-
+* 
-
-Controls whether the setting is visible or not. If specified, adds
@@ -2254 +2317 @@
-setting.
-
-
+* 
-
-Allows an additional CSS class to be applied to the label of the
-setting.
-
-
+* 
-
-Allows an addtional CSS class to be applied to the contents of the
-setting.
-
-
+* 
-
-Supplies a "hint" phrase that provides inline instruction to the user.
@@ -2270 +2333 @@
-forces it to display.
-
-
+* 
-
-Controls whether the inline help 'hint' label is shown or not.
-
-
+* 
-
-Supplies a warning message to the user regarding the use of this setting.
-
-
+* 
-
-Controls whether the warning message is shown or not.
-
-
+* 
-
-Identifies a specific page of the MT help documentation for this setting.
-
-
+* 
-
-Identifies a section name of the MT help documentation for this setting.
@@ -2408 +2471 @@
-=over 4
-
-
+* 
-
-If assigned, the current 'index' of the loop is assigned to this template
-variable.
-
-
-
-
+* 
+
+* 
-
-Identifies the starting number for the loop.
-
-
-
-
+* 
+
+* 
-
-Identifies the ending number for the loop. Either 'to' or 'end' must
-be specified.
-
-
-
-
+* 
+
+* 
-
-Provides the amount to increment the loop counter.
-
-
+* 
-
-If specified, this string is added inbetween each block of the loop.
@@ -2442 +2505 @@
-=over 4
-
-
+* 
-
-Assigned 1 when the loop is in the first iteration.
-
-
+* 
-
-Assigned 1 when the loop is in the last iteration.
-
-
+* 
-
-Assigned 1 when the loop index is odd, 0 when it is even.
-
-
+* 
-
-Assigned 1 when the loop index is even, 0 when it is odd.
-
-
+* 
-
-Holds the current loop index value, even if the 'var' attribute has
-been given.
-
-
+* 
-
-Tracks the number of times the loop has run (starts at 1).
@@ -2597 +2660 @@
-=over 4
-
-
-
-
+* 
+
+* 
-
-Declares a variable to test. When none of the comparison attributes are
@@ -2605 +2668 @@
-a "true" value, meaning if it is assigned a non-empty, non-zero value.
-
-
+* 
-
-Declares a MT tag to execute; the value of which is used for testing.
@@ -2613 +2676 @@
-If tag passes through the logical result of that conditional tag.
-
-
+* 
-
-If specified, applies the specified mathematical operator to the value
@@ -2621 +2684 @@
-=over 4
-
-
+* 
-
-Addition.
-
-
+* 
-
-Subtraction.
-
-
+* 
-
-Adds 1 to the given value.
-
-
+* 
-
-Subtracts 1 from the given value.
-
-
+* 
-
-Multiplication.
-
-
+* 
-
-Division.
-
-
+* 
-
-Issues a modulus operator.
@@ -2651 +2714 @@
-=back
-
-
+* 
-
-Used in conjunction with the 'op' attribute.
-
-
+* 
-
-Tests whether the given value is equal to the value of the 'eq' attribute.
-
-
+* 
-
-Tests whether the given value is not equal to the value of the 'ne' attribute.
-
-
+* 
-
-Tests whether the given value is greater than the value of the 'gt' attribute.
-
-
+* 
-
-Tests whether the given value is less than the value of the 'lt' attribute.
-
-
+* 
-
-Tests whether the given value is greater than or equal to the value of the
-'ge' attribute.
-
-
+* 
-
-Tests whether the given value is less than or equal to the value of the
-'le' attribute.
-
-
+* 
-
-Tests whether the given value matches the regex pattern in the 'like'
-attribute.
-
-
+* 
-
-Uses a Perl (or PHP under Dynamic Publishing) expression. For Perl, this
@@ -2969 +3032 @@
-###########################################################################
-
+=head2 Unless
+
+A conditional tag that is the logical opposite of the L<If> tag. All
+attributes supported by the L<If> tag are also supported for this tag.
+
+=for tags templating
+
+=cut
+
+###########################################################################
+
-=head2 Loop
-
@@ -2981 +3055 @@
-=over 4
-
-
-
-
+* 
+
+* 
-
-The template variable that contains the array of hashref data to
-process.
-
-
+* 
-
-Causes the data in the given array to be resorted in the manner
@@ -3000 +3074 @@
-    sort_by="key reverse"; sort_by="value numeric"
-
-
+* 
-
-If specified, this string will be placed inbetween each "row"
@@ -3012 +3086 @@
-=over 4
-
-
+* 
-
-Assigned when the loop is in the first iteration.
-
-
+* 
-
-Assigned when the loop is in the last iteration.
-
-
+* 
-
-Assigned 1 when the loop is on odd numbered rows, 0 when even.
-
-
+* 
-
-Assigned 1 when the loop is on even numbered rows, 0 when odd.
-
-
+* 
-
-When looping over a hashref template variable, this variable is
-assigned the key currently in context.
-
-
+* 
-
-This variable holds the value of the array or hashref element
@@ -3138 +3212 @@
-An alias for the 'Var' tag, and considered deprecated in favor of 'Var'.
-
+=for tags deprecated
+
-=cut
-
@@ -3150 +3226 @@
-=over 4
-
-
+* 
-
-Identifies the template variable. The 'name' attribute supports a variety
@@ -3175 +3251 @@
-    <mt:Var name="count(foo)">
-
-
+* 
-
-Along with the 'value' attribute, this allows the application of
@@ -3181 +3257 @@
-are supported).
-
-
+* 
-
-If provided with the 'op' attribute, provides the operand for the
@@ -3190 +3266 @@
-is useful for setting variables as well.
-
-
+* 
-
-For array template variables, this attribute supports:
@@ -3196 +3272 @@
-=over 4
-
-
+* 
-
-Takes an element from the end of the array (last element).
-
-
+* 
-
-Takes an element from the front of the array (index 0).
-
-
+* 
-
-Returns the number of elements in the array template variable.
@@ -3214 +3290 @@
-=over 4
-
-
+* 
-
-Only valid when used with the 'key' attribute, or if a key is present
-in the variable name.
-
-
+* 
-
-Returns the number of keys present in the hash template variable.
@@ -3225 +3301 @@
-=back
-
-
+* 
-
-Identifies an element of an array template variable.
-
-
+* 
-
-Identifies a key of a hash template variable.
-
-
+* 
-
-If the variable is undefined or empty, this value will be output instead.
-
-
+* 
-
-Formats the variable in JSON notation.
-
-
+* 
-
-For array template variables, this attribute is used in joining the
@@ -3437 +3513 @@
-=over 4
-
-
+* 
-
-If either 'name' or 'tag' are specified, tests the entry in context
@@ -3553 +3629 @@
-=over 4
-
-
+* 
-
-A text string that is used to join each of the items together. For example
@@ -3561 +3637 @@
-would print out each tag name separated by a comma and a space.
-
-
+* 
-
-The kind of object for which to show tags. By default the entry tags are shown.
-
-
+* 
-
-The tag object column on which to order the tags. Common values are name and
-rank. By default tags are sorted by name.
-
-
+* 
-
-The direction in which to sort tags by the sort_by field. Possible values
@@ -3576 +3652 @@
-when sorted by name and descending order when sorted by other columns.
-
-
+* 
-
-A number of tags to show. If given, only the first tags as ordered by
-sort_by and sort_order are shown.
-
-
+* 
-
-A number of tags to show. If given, only the given number of tags with
@@ -3817 +3893 @@
-=over 4
-
-
+* 
-
-Allows a user to specify the upper bound of the scale.
@@ -3931 +4007 @@
-
-To avoid printing out the leading text when no entry tags are assigned you
-EntryIfTagged
-EntryIfTagged
+L<EntryIfTagged>
+L<EntryIfTagged>
-the tag attribute to test for the assignment of a particular entry tag.
-
@@ -3939 +4015 @@
-=over 4
-
-
+* 
-
-A text string that is used to join each of the items together. For example:
-
-MT
+mt:
-
-would print out each tag name separated by a comma and a space.
@@ -3951 +4027 @@
-B<Example:>
-
-MTEntries
+L<Entries>
-a list of all of the tags assigned to each entry returned by L<Entries>
-glued together by a comma and a space.
@@ -3995 +4071 @@
-###########################################################################
-
+=head2 TagLabel
+
+An alias for the 'TagName' tag.
+
+=cut
+
+###########################################################################
+
-=head2 TagName
-
@@ -4003 +4087 @@
-=over 4
-
-
+* 
-
-If specified, outputs the "normalized" form of the tag. A normalized
@@ -4011 +4095 @@
-=over 4
-
-
+* 
-
-If specified, causes any tag with spaces in it to be wrapped in quote
@@ -4229 +4313 @@
-=over 4
-
-
-
-
+* 
+
+* 
-
-The archive type to test for, case-insensitively. See L<ArchiveType> for
@@ -4276 +4360 @@
-=over 4
-
-
+* 
-
-Specifies the name of the archive type you wish to check to see if it is enabled.
@@ -4354 +4438 @@
-=over 4
-
-
+* 
-
-Supplies a variable name to use for assigning the contents of the
@@ -4387 +4471 @@
-=over 4
-
-
+* 
-
-The name of a template module in the current blog.
-
-
+* 
-
-The name of the widget in the current blog to include.
-
-
+* 
-
-The path to an external file on the system. The path can be absolute or
@@ -4402 +4486 @@
-includes like that found in PHP.
-
-
+* 
-
-For selecting Index templates by their unique identifier.
@@ -4411 +4495 @@
-filename to load.
-
-
+* 
-
-Used to include a template from another blog in the system. Use in
-conjunction with the module, widget or identifier attributes.
-
-
+* 
-
-Forces an Include of a globally defined template even if the
@@ -4422 +4506 @@
-(For module, widget and identifier includes.)
-
-
+* 
-
-If specified, causes the include to be handled as a server-side
@@ -4443 +4527 @@
-Suitable for module, widget or identifier includes.
-
-
+* 
-
-Enables caching of the contents of the include. Suitable for module,
-widget or identifier includes.
-
-
+* 
-
-Used to cache the template module. Used in conjunction with the 'cache'
-attribute. Suitable for module, widget or identifier includes.
-
-
+* 
-
-Specifies the lifetime in seconds of a cached template module. Suitable
@@ -4791 +4875 @@
-=over 4
-
-
+* 
-
-A required attribute that defines the template with a string of specifiers.
@@ -4801 +4885 @@
-=over 4
-
-
+* 
-
-The entry's author's display name passed through the dirify global filter. Example: melody_nelson
-
-
+* 
-
-The same as above except using dashes. Example: melody-nelson
-
-
+* 
-
-For individual archive mappings, this returns the basename of the entry. By
@@ -4816 +4900 @@
-entry screen. Example: my_summer_vacation
-
-
+* 
-
-Same as above but using dashes. Example: my-summer-vacation
-
-
+* 
-
-The entry's primary category/subcategory path, built using the category
-basename field. Example: arts_and_entertainment/tv_and_movies
-
-
+* 
-
-Same as above but using dashes. Example: arts-and-entertainment/tv-and-movies
-
-
+* 
-
-The entry's primary category label passed through the dirify global filter. Example: arts_and_entertainment
-
-
+* 
-
-Same as above but using dashes. Example: arts-and-entertainment
-
-
+* 
-
-2-digit day of the month. Example: 09
-
-
+* 
-
-3-letter language-dependent abbreviation of the week day. Example: Tue
-
-
+* 
-
-A numeric entry ID padded with leading zeroes to six digits. Example: 000040
-
-
+* 
-
-The entry's numeric ID. Example: 40
-
-