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