The CartellaRelations object is a special self-contained object that maintains the relations between two types of object. Relations may be directly manipulated and the result reflected in the database directly, without going through any Managers or Objects.

When a CartellaRelations object is created, a set of delegates are assigned to it to allow direct communication with the database.

A relation may be created directly and delegates assigned to it. Most of the relations are the properties of specific objects, for example the Categories property on a BlogPost object.

CartellaRelations is a one-to-many relationship holder. There is one Owner Object and multiple target objects. CartellaRelations may also be empty; it may have an Owner object but no target objects.

Enumerating CartellaRelations entries, Retrieving item values

CartellaRelations is structured as a dictionary. It also can be enumerated as a dictionary and items retrieved by an Indexer.

In CartellaRelations, the key value to the Indexer is always the target's ID. If the key does not exist, a Null value will be returned (instead of throwing an exception as normal Dictionary would do).

Note
CartellaRelations and its sub-classes also support Linq statements.
CopyC#
////////////////////////////////////////////////////////////////////////////////
// Retrieving values from a CartellaRelation
////////////////////////////////////////////////////////////////////////////////    
IBlogPost blog = blogManager.SelectSingleBlog(blogId);
ICartellaRelations<IEntity, ICategory> categories = blog.Categories;

//enumerating CartellaRelation
foreach (KeyValuePair<IEntity, ICategory> entry in categories)
{
    ICategory category = entry.Value;
}

//retrieving item with Indexer
string categoryId = "434545";
ICategory category2 = categories[categoryId];

//using Linq statements on CartellaRelation
var query = from entry in categories
            let category = entry.Value
            where category.Name.StartsWith("Cartella")
            select new
            {
                CategoryName = category.Name,
                CategoryDescription = category.Description
            };

Manipulating CartellaRelations

A CartellaRelations object is self-contained. It can directly communicate to the database without going through other objects. CartellaRelations may be manipulated directly.

Note that manipulation of CartellaRelations only affect the relation itself. It will neither remove any objects nor update properties that are un-related to the relation itself.

CopyC#
]
    IBlogPost blog = blogManager.SelectSingleBlog(blogId);
    ICartellaRelations<IEntity, ICategory> categories = blog.Categories;

    ICategory newCategoryToAssociate = siteManager.CategoryManager.SelectSingleCategory(categoryId);

    //Add and new target to relation.
    //Use try catch block since Exception will be thrown
    //if target is null or key already exists
    try
    {
        categories.AddRelation(newCategoryToAssociate);
    }
    catch (Exception e)
    {
        //do something about the exception
    }

    //Remove a target from relations
    //Use try catch block since Exception will be thrown
    //if target is null or key doesn't exists
    try
    {
        categories.RemoveRelation(newCategoryToAssociate);
    }
    catch (Exception e)
    {
        //do something about the exception
    }

    //Clear all targets in relations
    //Use it with caution
    try
    {
        categories.ClearRelations();
    }
    catch (Exception e)
    {
        //do something about the exception
    }

CartellaRelations Sub-types

Two sub-types exist for CartellaRelations: CartellaPagedRelations and CartellaPositionedRelations.

CartellaPagedRelations is an object that relies on deferred execution. When the object is created, it consists only of a set of delegates. The content is added page by page.

CartellaPositionedRelations is a CartellaRelations object with position information for each item.

CopyC#
//FolioModule's "GetChildEntityPagedRelations" method returns a paged relations object
ICartellaPagedRelations<IFolioModule, IFolioItem> blogPosts = folioModule.GetChildEntityPagedRelations<BlogPost>(category);

//get first page of relations, return a readonly dictionary, with target ID as strings
IReadonlyDictionary<string, IFolioItem> page1ItemsDictionary = blogPosts.GetPage<BlogPost>(1);

//Gallery's "Images" property returns a positioned relations object. 
//Each item has a position and  can be manipulated
ICartellaPositionedRelations<IGallery, IImage> imagesRelations = gallery.Images;

//Add a new image after the reference image
imagesRelations.AddRelation(newImage, referenceImage, false);

//Move a image before the reference image
imagesRelations.MoveRelation(image1, referen<codeEntityReference qualifyHint="false">P:System.CodeDom.CodeMemberProperty.HasSet</codeEntityReference>ceImage, true);

See Also