MTPaginate 1.28

January 12, 2003 - updated March 3, 2007 (Download)

This plugin is free for personal use. For commercial use a $20 license is required.

Important: The MTPaginate tags generate PHP code. In order to use these tags, your blogs must reside on a server that supports PHP and your blog files must have an appropriate PHP extension (usually .php). See this page for more information.

Purpose

Some web pages generated by MovableType may grow quite large. For example, a category archive with hundreds of entries or an individual entry archive with dozens of comments may become unmanagebly large.

The MTPaginate plugin makes it possible for the single web page that MovableType generates to be displayed as multiple pages, with easy navigation between them.

Pagination of a list of entries

Following is an example of a simple Index template. This template generates links and excerpts for the last 20 entries and breaks it on section (<$MTPaginateSectionBreak$>) boundaries into pages of less than 1000 bytes, each. Each page will contain one or more entries. If there is more than one page, the <MTPaginateNavigator> tag will create a popup menu 1 2 3 4 that jumps to the individual pages.

<MTPaginate>
   <h1><$MTBlogName$></h1>
   <MTPaginateIfMultiplePages>
      <div><$MTPaginateNavigator style="popup"$></div>
   </MTPaginateIfMultiplePages>
   <MTPaginateContent max_bytes="1000">
     <MTEntries lastn="20">
      <p>
         <MTPaginateSectionID><$MTEntryID><MTPaginateSectionID/>
         <b><a href="<$MTEntryPermalink$>"><$MTEntryTitle$></a></b>
         <$MTEntryExcerpt$>
      </p>
      <MTPaginateStaticBlock section="3,8,13">
            [ Section for displaying ads ]
      </MTPaginateStaticBlock>
      <$MTPaginateSectionBreak$>
      </MTEntries>
   </MTPaginateContent>
</MTPaginate>

Pagination of an individual entry

Following is an example of a simple Individual Entry Archive template using the MTPaginate tags. This template takes the entry text and breaks it on paragraph (<p>) boundaries into pages of less than 800 words, each. Each page will contain one or more paragraphs (if the first paragraph is more than 800 words, the page will only contain that one paragraph). If there is more than one page, the <MTPaginateNavigator> tag will create a list of links to the individual pages (1 | 2 | 3 | 4).

<MTPaginate>
   <h1><$MTEntryTitle$></h1>
   <MTPaginateIfMultiplePages>
      <div><$MTPaginateNavigator$></div>
   </MTPaginateIfMultiplePages>
   <MTPaginateContent max_words="800" section_start_tag="p">
      <$MTEntryBody$>
   </MTPaginateContent>
   <a href="<$MTBlogURL$>">Index</a>
</MTPaginate>

Example: The Long Articles Blog uses the MTPaginate tags to break a listing of articles into several pages, and to break individual entry archives into multiple pages.

The MTPaginate tags automatically break up specified (long) content in a single document into multiple pages. You can let the user navigate between the pages using Previous and Next links, a list of page numbers (1 | 2 | 3 | 4) or a selection menu 1 2 3 4 . You configure pagination by specifying section breaks within your document and the maximum size that multiple sections are allowed to be before a new page is created.

Tags

• Paginate
• Page Navigation
• Page and Section Numbers
• Page Conditions
• Paginated Content

Paginate

• MTPaginate
  Container tag that must enclose all other pagination tags. You can provide one of the following optional attributes:
  • page_selector=”name”
    Specifies which URL parameter name is used for page selection. The default page_selector is "page". You would need to change the default page_selector only if your page uses the page parameter for some other purpose.
  • page_section_selector=”name”
    Specifies which URL parameter name is used for page section selection. The default page_section_selector is "page_section". You would need to change the default page_section_selector only if your page uses the page_section parameter for some other purpose.
  • default_page="1" or "first" or "last" or "all"
    Specifies the page number that is displayed by default. Besides specifying a number, you can also use "first" or "last", for first or last page, respectively, or "all" to display all pages at once. By default, the first page is displayed.
  • base_address=”_relative” or "_absolute" or "URL"
    This parameter can be used to specify that type of links built by the page navigation tags. You can specify a concrete URL or use "_relative" (i.e. document.php?page=3) or "_absolute" (i.e. http://www.yoursite.com/blog/page.php?page=3). By default, page navigation uses relative links.
  • debug=”1”
    This parameter can be used during the development of your template to displays entire contents of the document as a list of sections. By default, debug is disabled.
  • mode="php" or "cgi"
    Specifies whether the generated page will be processed by PHP or displayed by a CGI, such as the mt-search.cgi. The default mode is "php".
• MTPaginateIfSinglePage
  Conditional tag that is true if all content fits into a single page.
• MTPaginateIfMultiplePages
  Conditional tag that is true if the content has been split into two or more pages. To only show the navigation links when there are multiple pages, use the following code:

  <MTPaginateIfMultiplePages>
     <$MTPaginateNavigator$>
  </MTPaginateIfMultiplePages>

• MTPaginateVersion
  Returns the current version of the MTPaginate plugin.

Page Navigation

Addressing by page:You can use the page parameter to specify which page should be displayed. The parameter can have a numeric value (1 for first page, 2 for second page, …) or you can use the logical value first for the first page and last for the last page.

For example, the following URLs would address the first, third and last page, respectively.

http://www.example.com/blog/entry.php?page=first
http://www.example.com/blog/entry.php?page=3
http://www.example.com/blog/entry.php?page=last

Addressing by page section:When you generate a paginated list of items, you can identify each section using the MTPaginateSectionID container tag. You can then use the page_section parameter to target the page containing the specified section id.

For example, if you have a paginated listing of comments, you might want to use the comment ID as your MTPaginateSectionID:

...
    <MTPaginateSectionID><$MTCommentID$></MTPaginateSectionID>
...

The following URLs would address the pages, containing the entry comments 1000 and 1012, respectively.

http://www.example.com/blog/entry.php?page_section=1000
http://www.example.com/blog/entry.php?page_section=1012

If both a page and page_section parameter is specified, the page identified by the page_section parameter is selected.

• MTPaginatePreviousPageLink
  Link to the previous page of a multi page document. If currently the first page is being displayed, then MTPaginatePreviousPageLink is empty.
To show a link to the previous page - if there is one, use the following code:

<MTPaginateIfPreviousPage_>
   <a href="<$MTPaginatePreviousPageLink$>">Previous Page</a>
</MTPaginateIfPreviousPage_>

• MTPaginateNextPageLink
  Link to the next page of a multi page document. If currently the first page is being displayed, then MTPaginateNextPageLink is empty. To show a link to the next page - if there is one, use the following code:

  <MTPaginateIfNextPage_>
     <a href="<$MTPaginateNextPageLink$>">Next Page</a>
  </MTPaginateIfNextPage_>

• MTPaginateAllPagesLink
  Link to display all pages of a multi page document at once. To show a link to all the pages - if there there are more than one pages, use the following code:

  <MTPaginateIfMultiplePages>
     <a href="<$MTPaginateAllPagesLink$>">All Pages</a>
  </MTPaginateIfMultiplePages>

• MTPaginateNavigator
  Links to some or all of the pages in a multi-page document. See the navigator sampler pages for examples of this tag. You can use the following attributes to modify this tag:
  • anchor="#anchor"
    If specified, the linke generated by MTPaginator include this anchor.
  • style="navigator style"
    Specifies the display style of the navigation. The can be one of the following values - the default is "links":
    • links:  1 | 2 | 3 | 4
    • popup:    1 2 3 4
  • format="%d"
    Specified the format of the text used in the list of links or popup menu. The default value is "%d". Example, to display "Page 1 | Page 2 | Page 3 | Page 4", use the following code:

    <$MTPaginateNavigator format="Page %d">

  • format_title="%d"
    Specified the format of the text used for the link title in the list of links; it is only used in the "links" display style. Some browsers display the link title when the user hovers with the mouse over the link. The default value is "" or empty title. For example, to specify "Page <page number>" as the title, use the following code:

    <$MTPaginateNavigator format_title="Page %d">

  • format_current="%d"
    Specifies the format of the text used for the current page in the list of links or popup menu. The default value is the same as that of the format attribute. For example, to make the current page number bigger "1 | 2 | 3 | 4", use the following code (the format "<font size=+1>%d</font>" must be converted into HTML entities when it’s placed into the attribute):

    <$MTPaginateNavigator format_current="&lt;font size=+1&gt;%d&lt;/font&gt;">

  • format_all="text"
    When this attribute is specified, the navigators adds a link that displays all pages at once. Be default, format_all is empty. Specified the format of the text used in the list of links or popup menu. For example, to display "All 4 Pages | Page 1 | Page 2 | Page 3 | Page 4", use the following code:

    <$MTPaginateNavigator format_all="All %d Pages">

  • format_all_title="text"
    Specified the format of the text used for the link title in on the link used to display all pages at once; it is only used in the "links" display style in conjunction with the format_all attribute. Some browsers display the link title when the user hovers with the mouse over the link. The default value is "" or empty title. For example, to specify "Display all pages at once" as the title, use the following code:

    <$MTPaginateNavigator format_all="All Pages" format_all_title="display all pages at once">

  • format_all_current="text"
    Specifies the format of the text in the list of links or popup menu used when all pages are currently selected. The default value is the same as that of the format_all attribute. For example, to display "[ All Pages ] | Page 1 | Page 2 | Page 3 | Page 4", use the following code:

    <$MTPaginateNavigator format_all="All Pages" format_all_current="[ All Pages ]">

  • place_all="before" or "after"
    Specifies whether to to put the link to display all pages before (All Pages | 1 | 2 | 3 | 4) or after (1 | 2 | 3 | 4 | All Pages) the links to individual pages. The default is to put the linkbefore the individual pages. For example, if you only want to put the link to all pages after the links to individual pages, use the following code:

    <$MTPaginateNavigator format_all="All Pages" placement_all="after">

  • list_pages="before" or "after" or "all"
    Specifies whether to list all (1 | 2 | 3 | 4) pages or only pages before (1) or after (3 | 4) the current page. The default is to list all pages. For example, if you only want to list pages before the current page, use the following code:

    <$MTPaginateNavigator list_pages="before">

  • separator=" , "
    Specifies the separator between the links in the list; it is only used in the "links" display style. The default value is " | ". For example, to display "1, 2, 3, 4", use he following code:

    <$MTPaginateNavigator separator=", ">

  • target="name"
    Specifies the target attribute of links; it is only used in the "links" display style. By default no target is specified. For example, to always make the page open in the same window, use the following code:

    <$MTPaginateNavigator target="_self">

Page Number

• MTPaginateNumPages
  Number of pages into which content was paginated.
• MTPaginateCurrentPage
  Page number of current page.
• MTPaginatePreviousPage
  Page number of previous page, if any.
• MTPaginateNextPage
  Page number of next page, if any.
• MTPaginateNumSections
  Number of section into which content was divided.
• MTPaginateTopSection
  Section number of the first section on current page.
• MTPaginateCurrentSection
  Section number of the current section.
• MTPaginateBottomSection
  Section number of the last section on current page.

Page Conditions

The page condition tags allow you to display text based on which page is displayed. The page condition tags which end with an underscore (_) are different from standard MovableType condition tags because they generate PHP code. This means that you must use the single <MTPaginateElse_> tag instead of the <MTElse> container tags.

The following truth table shows when each of the conditional tags evaluate to a true value:

Tag	Single Page	First Page	Subsequent Pages	Last Page	All Pages	First Section	Last Section
MTPaginateIfFirstPage_	true	true			true
MTPaginateIfMiddlePage_			true
MTPaginateIfLastPage_	true			true	true
MTPaginateIfPreviousPage_			true	true
MTPaginateIfNextPage_		true	true
MTPaginateIfAllPages_					true
MTPaginateIfPageHeader_						true
MTPaginateIfPageFooter_							true

• MTPaginateIfFirstPage_
  Enclosed text is displayed if the current page is the first page of a multi-page document, or if there is only one page.
• MTPaginateIfLastPage_
  Enclosed text is displayed if the current page is the last page of a multi-page document, or if there is only one page.
• MTPaginateIfMiddlePage_
  Enclosed text is displayed if there are multiple pages and the current page is not the first or last page.
• MTPaginateIfPreviousPage_
  Enclosed text is displayed if there are multiple pages and the current page is not the first page.
• MTPaginateIfNextPage_
  Enclosed text is displayed if there are multiple pages and the current page is not the last page.
• MTPaginateIfAllPages_
  Enclosed text is displayed if there are multiple pages and all pages have been selected.
• MTPaginateIfPageHeader_
  Enclosed text is displayed if the current section is the first section on the current page.
• MTPaginateIfPageFooter_
  Enclosed text is displayed if the current section is the last section on the current page.
• MTPaginateElse_
  This tag can only be used inside one of the MTPaginateIf…_ conditional tags. The text that follows is displayed if the condition of the tag evaluates as false.

The following example displays a large header on the first page and a smaller header with navigation links on subsequent pages of a multi-page document:

<MTPaginateIfFirstPage_>
   <h1><$MTEntryTitle$></h1>
<MTPaginateElse_>
   <h2><$MTEntryTitle$>: <$MTPaginateNavigator$></h2>
</MTPaginateIfFirstPage_>

Paginated Content

The page condition tags allow you to display text based on which page id displayed. The page condition tags which end with an underscore (_) are different from standard MovableType condition tags because they generate PHP code which means that you must use the single <MTPaginateElse_> tag instead of the <MTElse> container tags.

• MTPaginateContent
  This container tag encloses text that is to be paginated. You can modify its behavior using the following attributes:
  • max_words="n"
    Specifies the maximum number of words in a page of content. The default value is 400 words.
  • max_bytes="n"
    Specifies the maximum number of bytes in a page of content. If specified, the max_words attribute is ignored.
  • max_sections="n"
    Specifies the number of sections in a page of content. If specified, the max_words and max_bytes attributes are ignored.
  • section_start_tag="p"
    Specifies the tag that indicates the beginning of a new section. When the content is paginated, a page break will be inserted in front of the specified tag, if necessary. By default, no section_start_tag is specified.
    
    To break up content before paragraph <p> tags, use the following code:

    <MTPaginateContent section_start_tag="p">
    ....
    </MTPaginateContent>

  • section_start="section start"
    Specifies any text which indicates the beginning of a new section. When the content is paginated, a page break will be inserted in front of the specified text, if necessity. The section_start attribute overrides the section_start_tag attribute. By default, no section_start_tag is specified.
    
    To break up content before <div class="section"> tags, use the following code (note that the value must be converted into HTML entities when it’s placed into the attribute):

    <MTPaginateContent section_start="&lt;div class=&quot;section&quot;&gt;">
    ....
    </MTPaginateContent>

  • section_break="text"
    Specifies the text that indicates separation between two sections. When the content is paginated, a page break will be inserted at the location of the specified text, if necessary. The section_break text is removed from the document during pagination. By default, the section_break is “__MTPAGINATE_SECTION_BREAK__”.
    
    To specify the text <p>——</p> as a section separator, use the following code:

    <MTPaginateContent section_break="&lt;p&gt;----&lt;/p&gt;">
       ...
    </MTPaginateContent>

  • page_break="text"
    Specifies the text that indicates separation between two pages. When the content is paginated, a page break will always be inserted at the location of the specified text. The section_break text is removed from the document during pagination. By default, the page_break is “__MTPAGINATE_PAGE_BREAK__”.
    
    To specify the text <p>====</p> as a section separator, use the following code:

    <MTPaginateContent page_break="&lt;p&gt;====&lt;/p&gt;">
       ...
    </MTPaginateContent>

• MTPaginateSectionBreak
  Indicates a section break. When the content is paginated, a page break will be inserted at the location of the MTPaginateSectionBreak tag, if necessary.
• MTPaginateSectionID
  Container tag whose contents specify the ID of the current section. This ID can be used as the value of the page_section URL parameter to specify the page that contains this section.
  

      <MTPaginateSectionID><$MTCommentID$></MTPaginateSectionID>
  

• MTPaginatePageBreak
  Indicates a page break. When the content is paginated, a page break will always be inserted at the location of the MTPaginateSectionBreak tag.
• MTPaginateStaticBlock
  This container tag encloses a static block that is included in the generated output at specific intervals. This tag is useful to include advertisements in the generated listing. You may have multiple MTPaginateStaticBlock tags in the paginated content, for example one to use on the first page and another one to use on subsequent pages.
  • section="3, 8, 10"
    Required attribute that specifies in which section on each page the static block should appear.
    For example, if you want to display an ad after the second entry in your listing, you would specify section=”2”. If you want the same block to also appear after the 7th entry, you would specify section=”2, 7”
  • page="1" or "2, *".
    Optional attribute that specifies on which page the static block should appear.
    For example, if you want to display an ad only on the first page, you would specify page=”1”. If you want a block to appear on all but the first page, you would specify page=”2, *” (the * means “all following pages”).

• 1.28 March 3 2007
  Enabled for Plugin Manager.
  New tags:
  
  • MTPaginateStaticBlock
  New tag attributes:
  
  • MTPaginateNavigator
    anchor
• 1.27 February 22 2007
  Fixed generated PHP to always use long PHP tags.
  Optimized plugin s.t. majority of the code is only loaded when needed.
  New tags:
  
  • MTPaginateSectionID
• 1.26 Septembet 28 2005
  Fixed problems with MTPaginateElse_ tag inside of MTPaginateIfPageHeader/Footer_ tags.
• 1.25 Septembet 23 2005
  Fixed errors reported by certain PHP configurations.
  Implemented MTPaginateIfPageFooter_ for PHP mode.
• 1.24 April 5 2004
  Escaped reserved chars in PHP URL parameters so that pages validate.
• 1.23 April 4 2004
  Fixed problem where additional parameters in URL were getting messed up.
• 1.2.2 April 1 2003
  Fixed problems with empty leading section.
• 1.2.1 March 31 2003
  Fixed MTPaginateNavigator target attribute in PHP mode.
• 1.2 February 20 2003
  New tags:
  
  • MTPaginateNumSections
  • MTPaginateTopSection
  • MTPaginateCurrentSection
  • MTPaginateBottomSection
  • MTPaginateIfPageHeader_
  • MTPaginateIfPageFooter_
  New tag attributes:
  
  • MTPaginate
    mode
• 1.1 January 18 2003
  New tags:
  
  • MTPaginateVersion
  • MTPaginateAllPagesLink
  • MTPaginateIfAllPages_
  New tag attributes:
  
  • MTPaginate
    default_page, base_address
  • MTPaginateNavigator
    format_title�, format_all�, format_all_title�, format_all_current�, place_all�, target
• 1.0.1 January 13 2003
  Fixed error:
  

  Undefined subroutine &MT::remove_html called at /htdocs/www/plugins/MTPaginate.pl line 165

• 1.0 January 12 2003
  Initial Release.