Sunday, January 17th, 2010 (updated 4 Aug ’16)

Documentation for Nearby Entries v1.6.2

 
  • Version
    1.6.2
  • Type
    Plugins
  • More info
  • Elsewhere
    "EE Forums thread":http://expressionengine.com/forums/viewthread/141842/ "Devot-ee page":http://devot-ee.com/add-ons/plugins/nearby-entries/ "Kick Awesome Show #1 by fortyseven media":http://fortysevenmedia.com/blog/archives/tkas_episode_1/
  • Download
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

Post a comment

Name:

Email:

Location:

URL:

Your comment:

Remember my personal information
Notify me of follow-up comments?

Please enter the word you see in the image below: