RelationshipsExtended 13.0.2

Must use on Kentico 13.0.0 and above. This package is for the Admin project, not for the MVC Site. Please use RelationshipsExtended.MVC for the MVC Site

Installation

• Open your Kentico Solution and right click on the CMS Project, and select "Manage NuGet Packages..."
• Search for RelationshipsExtended and select the major version that matches your Kentico version (ex 10.0.0 = Kentico 10, 11.0.0 = Kentico 11, etc)
• After your NuGet package finishes installing, run your Keintico site. Ignore the Event Log Error for the RelationshipsExtended ErrorSettingForeignKeys as that always happens on the first start up.
• Go to System → Restart Application
• Also go to System → Macros → Signatures and resign your macros.

Query Extensions

The following Extension methods have been added to all ObjectQuery and DocumentQuery, see the project's readme for more info on usage. Except for InRelationWithOrder which is available in all versions, these are only in 13+

• BindingCategoryCondition: Filter items based on a Binding table that leverages CMS_Categories
• DocumentCategoryCondition: Filter items based on Document Categories
• TreeCategoryCondition: Filter items based on Tree Categories
• BindingCondition: Filter items based on a Binding table
• InCustomRelationshipWithOrder: Show objects related through a custom binding table with ordering support
• InRelationWithOrder: Show related Pages with order support (Available in Kentico 10-13)

Where Condition Generators

RelHelper contains some Where Condition generators which are available in the RelHelper macro namespace for admin purposes. For Code, we recommend using the Document/ObjectQuery extension methods.

Each of these Where Condition methods features a couple options:

1. Automatic Conversion of Code Name, GUID, or IDs passed to it into ID lookups to optimize performance in queries.
2. Multiple Condition Types: (Matching Any of the items, All of the items, or none of the items passed)
3. Automatic "1=1" if no filter objects are passed to it or some misconfiguration occurs, so it will not break your where condition.
4. Each of these also comes with a Macro version through the RelHelper macro namespace.

These methods are:

• GetDocumentCategoryWhere (For Document Categories)
• GetNodeCategoryWhere (For Node Categories used with the CMS.TreeNode class that comes with this module)
• GetBindingCategoryWhere (For Object to Category bindings)
• GetBindingWhere (For any Object to Object binding)

Node-Binding Staging Task Handlers

Unlike normal Object to Object Binding classes, where you can simply set the SynchronizationSetting to TouchParent, Node to Object binding is trickier and requires a lot of manual processing if you wish to have a Node's update task contain all its related items.

But default Related Pages are already handled by Kentico, and Node Categories using the CMS.TreeNode that comes with the relationships extended also automatically are handled by my code. Any additional or custom classes need to be manually handled.

I have reduced all that complex logic into a couple lines of code thanks to some helper methods that I have created. I would refer to the Demo Project Files to see how each of them work and how to leverage them.

CMS.TreeCategory and Node Categories

Another feature is a new class, CMS.TreeNode. This is not a Kentico created class, although I am sharing the CMS namespace as if Kentico ever did create a Tree Category, this wouldn't be needed anymore. This class operates the same as CMS.DocumentCategory, except it's attached to the Node instead of the Document, allowing you to use Categories without fear of things becoming out of sync with different localized versions of the Documents.

There is also a new UI when you edit a Page. In Properties on the page, you'll see Node Categories next to Categories, this allows you to assign any Node-category just as you would a Document category.

Advanced Category Selector (RE) and Advanced Many to Many Selector (RE)

The Advanced Category Selector (RE) form control and Advanced Many to Many selector (RE) form controls are both included with this module. The Advanced Category Selector also has a "Node Category" Save mode added which automatically integrates with the CMS.TreeCategory of the RelationshipsExtended. The Advanced Many to Many selector can mimic the functionality of the Edit Bindings (Tree+Order Support) only in that it can handle Object to Object bindings and Node to Object bindings, however it does not support ordering through the control, you will need to leverage the Edit Bindings (Tree+Order Support) for that.

Related Pages (RE)

The Related Pages (RE) form control is also included with this module. This allows you to mimic the edit relationships functionality on a page form and provides most of the same functionality (ability to select an Adhoc or Normal Relationship Name, Bind on Primary Nodes, Restrain what pages can be selected through Page Type and Left Side/Right Side Macros). This form control does have some limitations however when compared to the Edit Relationships UI template in that it uses Kentico's default page selection instead of the Uni Selector/Tree Selector.

Relationship Names Extended

This new User Interface (under Configuration) simply allows for the creation of AdHoc (sortable) relationship names, as by default you cannot. This is used then in conjunction with the Edit Relationship Template discussed in the next section.

User Interfaces Templates

A large part of the functionality given in the RelationshipsExtended is a handful of User interfaces which allow you to control the various binding scenarios. We'll go over them and explain some of what they do and how to use them. Remember, I won't cover every property, most are well explained when you hover over them.

Edit Relationship

This user interface allows you to manage Page Relationships (including Adhoc ones) with much greater control. The default Kentico related pages gives no control over what Page Types you can relate (you could related a Folder page for the Relationship "Banners" for example), it was clunky in its usage (you had to add pages one at a time) and it didn't allow Adhoc relationships (orderable ones), so you couldn't have order to the objects without making it part of a Page Type (which can get messy if multiple page types may need the same relationship, such as Banners or Quick Links).

The Edit Relationship also automatically gives a "read only" view to the "Right Side" only page types. For example, if a Banner is a Right-side only on the Relationship "Banners" then if you view the Banners UI on a Banner page, it will show you all the pages that use that banner.

Edit Categories

Those of you who have used the Advanced Category Selector already pretty much know what this is all about. The Edit Categories is the IU version of that tool. With it you can leverage Kentico categories in any way you wish, with much more control than you get with the standard Kentico category selector (which shows the entire category tree)

Edit Bindings (Tree+Order Support)

The normal Edit bindings UI page template is great for Object to Object, non-ordered bindings. However, it lacked two features: The ability to support Node binding (it couldn't figure out that the NodeID was the ParentObjectID), and it didn't support Orderable Bindings. This of course, corrects that.