With the Nearby Entries plugin, you can display not only one but any number of next and previous entries. You can order next/previous links not only by entry date but by edit or expiration date or by title alphabetically.
You can also display custom fields from next/previous entries. And you can filter next/previous entries using standard channel:entries parameters such as status, category, author and custom fields.
Getting slightly more complex, you can also select next/previous entries using one sort, then display them using a different sort, such as displaying the chronologically next 10 entries alphabetically by title.
h2. Compatibility
Works with both EE v1.x and v2.x.
h2. Installation
h3. EE v1.x
From the supplied *EE1* directory, place the
pi.nearby_entries.php file in the */system/plugins* folder.
h3. EE v2.x
From the supplied *EE2* directory, Place the *nearby_entries* folder in the */system/expressionengine/third_party* folder.
h2. Tags
The plugin has two tags, both used the same way:
exp:nearby_entries:next and
exp:nearby_entries:prev.
h2. Parameters
h3. Required parameters
h4. this_channel [EE2]
Helps determine the entry from which the previous and next entries are determined. Required if determining the entry using the
this_urltitle parameter.
h4. this_entryid OR this_entry_id
This is the entry from which the previous and next entries are determined. Required unless both the
this_urltitle and
this_weblog [EE1]
this_channel [EE2] parameters are entered instead.
h4. this_urltitle OR this_url_title
This is the entry from which the previous and next entries are determined. Requires completing the
this_weblog [EE1]
this_channel [EE2] parameter as well.
h4. this_weblog [EE1]
Helps determine the entry from which the previous and next entries are determined. Required if determining the entry using the
this_urltitle parameter.
h4. site
Required if using the Multiple Site Manager.
h3. Optional parameters
h4. allow_php
Defaults to "no". If set to "y", "Y", "Yes" or "yes", then EE's native security measure of the values, xss_cleaning, is switched off, allowing PHP code within the plugin.
h4. author_id
Works as in the channel:entries (EE1) or channel:entries (EE2) tag.
h4. category
Works as in the channel:entries tag.
h4. category_group
Works as in the channel:entries tag.
h4. channel
Works as in the channel:entries (EE2) tag.
h4. day
Works as in the channel:entries (EE1) or channel:entries (EE2) tag.
h4. debug
Allowed values are Yes, yes, y or No, no, n. If set to yes, then no results are displayed; instead, a series of notes about the deployment of the plugin appear within a div of class "nearby-entries-message". These notes should help debug usage of the plugin if the results aren't as expected.
h4. entry_id
Specify which entries should be included in the results. If excluding, see the
entry_id_not parameter.
h4. entry_id_not
Specify which entries should be excluded from the results.
h4. fixed_order
Works as in the weblog:entries (EE1) or channel:entries (EE2) tag.
h4. group_id
Works as in the weblog:entries (EE1) or channel:entries (EE2) tag.
h4. limit
Works as in the weblog:entries (EE1) or channel:entries (EE2) tag.
h4. month
Works as in the weblog:entries (EE1) or channel:entries (EE2) tag.
h4. offset
Works as in the weblog:entries (EE1) or channel:entries (EE2) tag.
h4. orderby
Sets the sort order of the results, whereas the
this_orderby parameter helps determine the content of the results. The only allowed values are all the columns in the exp_channel_titles table, among them entry_date (default), edit_date, expiration_date, recent_comment_date and title.
h4. parse
Setting parse="inward" allows another plugin to be placed within External Entries. (This is a universal parameter that works in all plugins.)
h4. show_expired
Works as in the weblog:entries (EE1) or channel:entries (EE2) tag.
h4. show_future_entries
Works as in the weblog:entries (EE1) or channel:entries (EE2) tag.
h4. sort
Sets the sort order of the results, whereas the
this_sort parameter helps determine the content of the results.
h4. status
Works as in the weblog:entries (EE1) or channel:entries (EE2) tag.
h4. sticky
Works as in the weblog:entries (EE1) or channel:entries (EE2) tag.
h4. start_on
Works as in the weblog:entries (EE1) or channel:entries (EE2) tag.
h4. stop_before
Works as in the weblog:entries (EE1) or channel:entries (EE2) tag.
h4. this_orderby
With
this_orderby you can set the entry order from which your set of next and previous entries will be selected. For example, you may want to display the previous 10 entries from the current one, but display them alphabetically by title rather than chronologically. In this scenario you'd set
this_orderby as "entry_date" (in this case its default value) then
orderby as "title".
h4. this_sort
The
this_sort parameter complements the
this_orderby one. The default value is "desc".
h4. weblog
Works as in the weblog:entries (EE1) tag.
h4. year
Works as in the weblog:entries (EE1) or channel:entries (EE2) tag.
h2. Variables
h4. {nearby:count}
Works as in the weblog:entries (EE1) or channel:entries (EE2) tag.
h4. {nearby:no_results}
Handles situations where no results are find. Eg,
{if nearby:no_results}No results{/if}.
h4. {nearby:total_results}
Works as in the weblog:entries (EE1) or channel:entries (EE2) tag.
h4. {nearby:[field_name]}
Text input and text area custom fields can be displayed.
Relationship fields cannot be displayed (though try the "Tied Entries":http://www.engaging.net/products/tied-entries plugin for that!).
Date variables cannot be displayed the regular way, ie, {tied:entry_date format="%D/%M/%Y"}. Instead, use PHP (set the PHP parsing stage to "output"):
<?php echo date("D/F/Y", "{tied:entry_date}"); ?>
Note that PHP's date format codes are slightly different to EE's own. They're posted at "PHP's date function manual page":http://www.php.net/manual/en/function.date.php.
h2. Examples
For a site using the blog-standard /year/month/date/url_title format for URLs, for which ExpressionEngine is not designed, the standard next/previous tags simply don't work. So we need to use the Nearby Entries plugin instead:
<div class="nextprev nextprev-single">
<div class="nav-previous">
<span class="nextprev-arrow">‹</span>
{exp:nearby_entries:prev this_urltitle="{segment_4}" this_channel="blog" debug="n" limit="1"}
<a href="{path=/}<?php echo date("Y/m/d", "{nearby:entry_date}"); ?>/{nearby:url_title}">
<span class="nextprev-post">Previous Post</span>
<span class="nextprev-single-link-title">{nearby:title}</span>
</a>
{/exp:nearby_entries:prev}
</div><!-- /.nav-previous -->
<div class="nav-next">
{exp:nearby_entries:next this_urltitle="{segment_4}" this_channel="blog" debug="n" limit="1"}
<a href="{path=/}<?php echo date("Y/m/d", "{nearby:entry_date}"); ?>/{nearby:url_title}">
<span class="nextprev-post">Next Post</span>
<span class="nextprev-single-link-title">{nearby:title}</span>
</a>
{/exp:nearby_entries:next}
<span class="nextprev-arrow">›</span>
</div><!-- /.nav-next -->
</div><!-- /.nextprev -->
Note that date fields cannot be output in the usual way, but instead need some assistance from PHP (be sure to switch on PHP for the template).inward
Changelog
h4. v.1.6.2 (2012 July 5)
* Moved "not" functionality in entry_id parameter to its own parameter entry_id_not
* Added if nearby:no_results functionality
* (thanks again to more input from Philip Prinz)
h4. v.1.6.1 (2012 June 21)
* Added "not" functionality to entry_id parameter (thanks again to Philip Prinz)
h4. v.1.6 (2012 May 31)
* reinstated channel:entries method of limiting entries range then reversing to prevent Next method from selecting first entry (thanks to Philip Prinz of puttyandpaint.com for feedback and patience)
h4. v.1.5.7 (2012 May 30)
* fixed issue when using author_id parameter
h4. v.1.5.6 (2012 May 19)
* fixed template-blanking bug when limit set to 1
h4. v.1.5.5 (2012 May 18)
* added offset parameter
* disabled _limit_results() function
h4. v.1.5.1 (2012 May 7)
* made error-trapping more robust
* added channel parameter
h4. v.1.4.5 (2011 Mar 13)
* fixed bug where MSM not handled properly in EE2
h4. v.1.4.4 (2010 Nov 6)
* placed support for EE2's file field type within conditional, otherwise was producing many PHP notices if no file fields were set
h4. v.1.4.3 (2010 Aug 3)
* added support for EE2's file field type
h4. v.1.4.2 (2010 June 11)
* fixed issue raised by Kyle Batson where using the author_id parameter caused PHP notices in some situations
h4. v.1.4 (2010 May 7)
* changed syntax, now using EE's db library, adapting to changes in EEv2.0.2
h4. v.1.3.1 (2010 Apr 12)
* added
allow_php parameter to override variable cleaning and allow PHP (thanks to Michael G Rose)
h4. v.1.3 (2010 Apr 9)
* added security measures: SQL Injection Prevention for parameters, Variable Cleaning for values
h4. v.1.2.4 (2010 Apr 6)
* fixed bug introduced in v1.2.3 where next and prev were reversed
h4. v.1.2.3 (2010 Apr 5)
* fixed bug where sorting produced unpredictable results
* added
this_orderby and
this_sort parameters
h4. v.1.1.3 (2010 Mar 1)
* fixed bug where variables weren't resetting for checking version when plugin called more than once on a template
h4. v.1.1.2 (2010 Mar 1)
* fixed bug where using parameters
this_weblog and
this_urltitle instead of
this_entryid wasn't working in EEv2.x
h4. v.1.1.1 (2010 Feb 23)
* fixed bug where using parameters
this_weblog and
this_urltitle instead of
this_entryid wasn't working in EEv1.x
h4. v.1.1 (2010 Feb 13)
* now works for both EE v1 and v2
h4. v.1.0.4 (2010 Jan 29)
* declared the $output variable so that no PHP messages are sent if it never gets defined
h4. v.1.0.3 (2010 Jan 18)
* added
author_id parameter
h4. v.1.0.2 (2010 Jan 17)
* added
offset,
group_id,
sticky,
fixed_order parameters
h4. v.1.0.1 (2010 Jan 17)
* added category and category_group parameters
Roadmap
* add search:[custom_field] parameter
* add support for popular 3rd-party field types
* fix category parameter in EE2
* add support for field names in this_orderby and orderby parameters