RelationshipsExtended 11.0.9

Relationships Extended for Kentico CMS Documentation

Full Documentation at http://devtrev.com/Resources/Relationships-Extended

Helper Methods

The RelationshipsExtended module comes with a RelHelper class which provides helper methods for leveraging various features of the RelationshipsExtended.

Where Condition Generators

In some cases (such as categorization) often the bound relationships are meant as a means of tagging and filtering objects. For example, you may have Regions on a Banner and want to show only Banners in the current user's region or regions. In SQL the where condition or join can be tedious. You can leverage the following methods to generate the Where Conditions for you.

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 File's DemoInitializationModule.cs to see how each of them work and how to leverage them.

• HandleNodeBindingInsertUpdateDeleteEvent (Handles triggering the Document Update with some magic to ensure only about 1 document update is ran even if you bind a large quantity of objects)
• UpdateTaskDataWithNodeBinding (handles attaching the Bound objects to the Document Update's Task data so it can be processed)
• NewBoundObjectIDs (Used in the Staging Task Processing to convert the old object IDs into the new ones on the new environment, returning all the IDs that the node should be bound to)
• NewOrderedBoundObjectIDs (For Ordered Node Bindings, used in the Staging Task Processing to convert the old object IDs into the new ones on the new environment, returning all the IDs in order)

If you decide to not Bind the Node-Binding objects to the Node itself, there is the SetBetterBindingTaskTitle that can help convert the less-than-readable normal StagingTask into a normal one. This is used on the StagingTask.LogTask.Before hook.

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.