Sunday, November 1st, 2009 (updated 16 Oct ’14)

Documentation for Tied Entries v2.1.5

 
  • Version
    2.1.5
  • Type
    Plugins
  • More info
  • Elsewhere
    "EE Forums thread":http://expressionengine.com/forums/viewthread/134112 "Devot-ee page":http://devot-ee.com/add-ons/plugins/tied-entries/
  • Download
The Tied Entries plugin works similarly to the exp:channel:entries tag's related_entries and reverse_related_entries tags. The difference is that you can tie entries to those in other channels not just one relationship away but via all the relationships and reverse relationships that connect them. There is no limit to the length of this tie, ie, to the number of relationship steps. h2. Known Issues * When using MSM and displaying a channel from another site, the search:field_name parameter doesn't work. * When using Playa, entries cannot be sorted using the Playa order. h2. Installation Place the */tied_entries* directory from the download package into your site's */[system_folder]/expressionengine/third_party* directory. h2. Required Parameters h4. site Required when using the Multiple Site Manager. h4. this_channel If you are using the this_url_title parameter instead of the this_entry_id parameter to set the initial entry, then the channel name must also be specified, as entries from different channels can share the same url_title. h4. this_entry_id This required parameter sets the initial entry. If the plugin is within another tag, such as the channel:entries tag, then the value of this parameter can be set dynamically, eg, with the {entry_id} variable. h4. this_url_title If the entry_id is not available then the entry can be set by the url_title, such as from a segment variable. h4. tie This is where the magic happens. Build the tie with relationship fields and channel names. Prefix each relationship field with ">" to signify a relationship (or "child" in Playa) and each channel name with "<" to signify a reverse relationship (or "parent" in Playa). These two different prefixes address the ambiguity where a field and a channel can share the same name. In reverse relationships you can limit the results to a specific relationship field. Do this with a colon separating the channel name from the field, eg, tie="<my_channel:my_field_name<another_channel". You can also limit results to a number of specific relationship fields using a pipe, eg, tie="<my_channel:my_field_name|my_second_field_name<another_channel". h2. Optional parameters h4. allow_php Set to "Y", "y", "Yes" or "yes" to allow PHP within the tag. Default is not. h4. backspace h4. category h4. channel h4. day h4. debug Set to yes and instead of results the main SQL statement and error messages are displayed, if any, regarding the value of "tie". Messages are displayed within a div of CSS class "tied-entries-message" if you want to style that. h4. delimiter When using the "entry_ids" mode, this parameter lets you present the list of entry_ids using a parameter other than the default commas. h4. entry_id h4. limit h4. month h4. orderby h4. mode Current values are "full" (default), "entry_ids" and "economy". The "economy" mode does not parse custom field names. The "entry_ids" mode limits the output to a list of entry_ids only separated by commas. You can change the delimiter with the "delimiter"¶meter. In "entry_ids" mode, the following parameters will not work: category, day, limit, month, orderby, show_expired, show_future_entries, sort, start_on, status, sticky, stop_before, year. Also, there is no need for a closing tag. h4. parse Setting parse="inward" allows another tag to be placed within Tied Entries. This is a universal parameter for all plugins. h4. search:[custom field] h4. show_expired h4. show_future_entries h4. sort h4. start_on h4. status h4. sticky h4. stop_before h4. url_title h4. year h2. Variables h4. {tied:[single_standard_variable]} All the "channel entries single standard variables":http://expressionengine.com/user_guide/modules/channel/channel_entries.html#single-variables are available (though they haven't all been tested -- please add a comment if you find any that don't work). h4. {tied:[custom_field]} Text input and text area custom fields can be displayed. Relationship fields cannot be displayed. Date variables cannot be displayed the regular way, ie, {tied:entry_date format="%D/%M/%Y"}. Instead, use PHP (set the plugin's allow_php parameter to "yes" and the template's 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. Using Playa Playa 4+ is supported only. If you have Playa installed, you can still use both Playa and regular relationship fields in the tie parameter, but only if they are in separate steps within the tie. In the tie, if you have a reverse/channel step lacking a filter field, ie my_channel, then if Playa is installed the plugin will _only_ find Playa fields. You can override this behavior by setting the reverse_method to "rel" but then you can only find regular relationship fields in that step of the tie, not Playa fields. If you filter for particular fields in your reverse/channel step, ie, my_channel:one_field|another_field then they must all be Playa fields, or regular relationship fields if you use reverse_method="rel". You can mix and match Playa and regular relationship fields in separate steps of the tie, so that, eg, first_channel:rel_field_1|rel_field_2<second_channel:playa_field_1|playa_field_2 is fine. h2. Examples We have a portfolio site of songs, albums and bands. Songs have an Albums relationship field songs_album while Albums have a Band relationship field albums_band. We're listing songs and we'd like to have the band name next to each one. This is what we'd like to do:
<ul>
	{exp:channel:entries channel="songs"}
	<li>
		{title}
		{related_entries id="songs_album"}
			{related_entries id="albums_band"}
				(<a href="{path=bands}{tied:url_title}">{tied:title}</a>)
			{/related_entries}
		{/related_entries}
	</li>
	{/exp:channel:entries}
</ul>
In reverse, we have a list of bands and want to show 10 their songs alphabetically:
<ul>
	{exp:channel:entries channel="bands"}
	<li>
		{title}
		<ul>
			{reverse_related_entries channel="albums"}
				{reverse_related_entries channel="songs"}
				{if "{count}"=="1"}<ul>{/if}
					<li>
						<a href="{path=songs}{url_title}">{title}</a>
						{if "{songs_review}"}: {songs_review}{/if}
					</li>
				{if "{total_results}"=="{count}"}</ul>{/if}
				{/reverse_related_entries}
			{/reverse_related_entries}
		</ul>
	</li>
	{/exp:channel:entries}
</ul>
But the related_entries and reverse_related_entries tags can't be nested. So here's how the above is done with tied entries:
<ul>
	{exp:channel:entries channel="songs"}
	<li>
		{title}
		{exp:tied_entries this_entry_id="{entry_id}" tie=">songs_album>albums_band"}
		(<a href="{path=bands}{tied:url_title}">{tied:title}</a>)
		{/exp:tied_entries}
	</li>
	{/exp:channel:entries}
</ul>
And:
<ul>
	{exp:channel:entries channel="bands"}
	<li>
		{title}
		<ul>
			{exp:tied_entries this_entry_id="{entry_id}" tie="<albums<songs" limit="10" orderby="title" sort="asc"}
			{if "{tied:count}"=="1"}<ul>{/if}
				<li>
					<a href="{path=songs}{tied:url_title}">{tied:title}</a>
					{if "{tied:songs_review}"}: {tied:songs_review}{/if}
				</li>
			{if "{tied:total_results}"=="{tied:count}"}</ul>{/if}
			{/exp:tied_entries}
		</ul>
	</li>
	{/exp:channel:entries}
</ul>
Note that each reverse relationship can result in many entries, while each relationship can result in only one. h2. Thanks Thanks to Yvonne Martinsson of fellow EE Pro Network member "Studio.Freewheelin":http://freewheelin.nu for initial testing./a¶ mode, this parameter lets you present the list of entry_ids using a parameter other than the default commas. h4. entry_id h4. limit h4. month h4. orderby h4. mode Current values are

Changelog

h4. 2.1.5 (2013 Mar 17) * Fixed bug where not discerning between identically named fields across multiple MSM sites h4. 2.1.4 (2012 May 19) * Fixed conditional where template was blanking out if no results h4. 2.1.3 (2012 May 18) * Fixed typo in directory name --- gah! h4. 2.1.2 (2012 May 3) * Scaled back what's processed when in debug mode to avoid fatal template crashes h4. 2.1.1 (2012 March 31) * Fixed bug introduced recently where custom fields were not being displayed h4. 2.1 (2012 March 3) * Removed EE1.x support -- farewell h4. 2.0.3 (2012 Jan 17) * Restored the dynamic="off" parameter; without it the plugin couldn't output on single-entry pages * Improved error-trapping by extending debug into the output process h4. 2.0.2 (2012 Jan 8) * Improved error-trapping and debug notification of changes made in v2.0.1 h4. 2.0.1 (2012 Jan 8) * Restructured handling of Playa child relationships together with regular reverse relationships h4. 2.0 (2011 December 26) * Rebuilt code to be easier to maintain * Changed required parameters from entry_id to this_entry_id and url_title to this_url_title and channel to this_channel. * Improved details in debug mode * Improved robustness and graceful degradation in case of errors h4. 1.5.4 (2011 December 23) * Fixed known issue of page blanking out if filter parameters (eg, category) result in no entries h4. 1.5.3 (2011 December 23) * Fixed silly bug introduced with backspace parameter h4. 1.5.2 (2011 December 22) * Added backspace parameter * If Playa is installed, then when called in reverse, the plugin now assumes a Playa field should be used h4. 1.5.1 (2011 December 15) * improved so that more combinations of Playa and EE relationship fields work together in a tie (thanks, Werner of Octave2.ch!) * EE1 version not updated from v1.4.3 h4. 1.5 (2011 December 14) * fixed bugs that generate bad SQL resulting internal server errors * EE1 version not updated from v1.4.3 h4. 1.4.7 (2011 June 28) * added stash: option for entry_id parameter in EE2 version * added economy mode * EE1 version not updated from v1.4.3 h4. 1.4.5 (2011 June 28) * fixed EE2 version to work when an entry has more than one Playa field * EE1 version not updated from v1.4.3 h4. 1.4.3 (2011 May 29) * made EE2 version fully compatible with Playa 4 * added optional "mode" parameter with "entry_ids" value; added optional "delimiter" parameter for mode="entry_ids" h4. 1.3.5 (2011 Mar 8) * fixed a reference to a renamed table exp_fieldtypes h4. 1.3.3 (2010 Oct 13) * split the plugin back into two separate versions for EE1 and EE2 due to problems calling the plugin repeatedly on a template in EE2 h4. 1.3.3 (2010 Oct 13) * added a conditional to stop a fatal error appearing in EE2x when there's no relevant content for the plugin to parse h4. 1.3.2 (2010 Aug 29) * added conditionals to stop notices appearing when residual Playa fields exist h4. 1.3.1 (2010 Aug 3) * added support for EE2's file field type h4. 1.3 (2010 Jun 17) * consolidated EE v1.x and v2.x versions into one release * enabled limiting of reverse related components of the tie to specific fields h4. 1.2.1 (2010 May 13) * Added allow_php parameter to override security h4. 1.2 (2010 May 7) * Changed syntax to adapt to changes in EE2.x as of EEv2.0.2 h4. 1.1.1 (2010 Apr 21) * Added conditional to stop problems with one particular type of tie parameter malformation h4. 1.1 (2010 Apr 9) * Added security measures: SQL Injection Prevention for parameters, Variable Cleaning for values h4. 1.0.9 (2009 Dec 14) * Rearranged structure to provide more detail in debug mode * Introduced partial support for Playa * Added date-related parameters h4. 1.0.8 (2009 Dec 14) * Added support for the search:[custom field] parameter h4. 1.0.7 (2009 Nov 19) * Added Multiple Site Manager support so that entries can be displayed from another MSM site h4. 1.0.6 (2009 Nov 19) * Streamlined code somewhat so that more is handled by the EE-native build_sql_query() function * Added show_expired, show_future_entries parameters h4. 1.0.5 (2009 Nov 18) * Fixed status parameter not working properly h4. 1.0.4 (2009 Nov 18) * Fixed bug where closed entries were causing PHP warnings h4. 1.0.3 (2009 Nov 17) * Released for ExpressionEngine v2.x * Removed undocumented categories functionality that was causing SQL errors in some circumstances h4. 1.0.2 (2009 Nov 16) * Fixed orderby, sort parameters * Added status, sticky parameters * Added explanation in docs for how to display dates * Removed documentation from plugin, providing instead a link to online docs

Roadmap

* add support for popular 3rd-party field types * switch over to relying on $channel->entries() for output (need first to understand how to not have the enveloping channel:entries tag "parse our precious bodily variables") * add awareness of Structure so that Structure URL can be used instead of url_title as a parameter * add Playa examples to documentation

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: