Overview

The basic element in NCommet is the item. Items are essentially the nodes that form trees and graphs.

In NCommet, you can have any number of trees you require. A tree is defined by its root item, i.e. the item that does not have a parent item. An important characteristic of these trees is that they are ordered. That means that the order of an item among its sibling items is important.

The following drawing shows two trees of items. The numbers inside each item is the order they have among their siblings.
ordered-trees.png

Graphs

You can also form directed graphs with your items. In NCommet that is supported through related items. A relation involves two items: the subject item (also called owner item) and the object item (also called related item). Also, the relation is described by a name, the relation type. This way you can assign a logical meaning to the relations, form named directed graphs, etc.

The following drawing shows two trees of items where some items are connected forming a graph. Note that graphs may be formed among items that belong to different trees.
directed-graphs.png

A closer look on items

As we previously saw, items are the basic element in NCommet. Items form trees and graphs. Now we'll see what information we can store in an item.

Every item has the following attributes:
  • name, which is a user defined string that has meaning only to the application creating the items (in other words, NCommet doesn't use the name of the item)
  • itemType, which is a user defined string intended to describe the type of the item and perform operations on the trees and graphs based on that item type. This is a very important mandatory attribute that cannot be changed once it is set.
  • tags, which is a user defined string array. An example usage could be to assign keywords to items. Just like the item's name, this attribute is not used by NCommet.

The most interesting attribute is the itemType. You'll find out more about its usefulness later on. For now, you may think of it as an item classifier that can be used to filter children or even enforce validation rules on the trees. The following drawing shows an example of an item with its attributes.
item-attributes.png

Content Objects

Setting a name on an item is far from enough when you want to build a more real-life application. You should be able to store every information you want on an item. However, NCommet is just a library and cannot know in advance what that information might be. That's where content objects come in. Each item may hold one content object that holds all the extra information you need.

A content object is a regular .NET object from your application. However, there are some limitations:
  1. the content class must derive from ContentBase, a core NCommet class.
  2. the content class must be XML Serializable. If you want to know why, you can read about it here.

Items combined with content objects unleash the potential of NCommet and convert it from a graph library to a full content management system framework. All you need to do is to provide the content classes: the content hierarchy is managed by NCommet.

The following drawing shows some items with their content.
items-with-content.png

Item Types and Content Types

You may be thinking that the content object has its .NET type so, what do we need that itemType attribute? Well, first of all, a content object is not mandatory: an item doesn't need to hold a content object. Secondly, placing the itemType attribute directly on the item makes it easier to implement all the useful features related to the itemType, without having to worry about the content.

In your application you will be typically having one itemType for each content type. But that's not necessary: an item type may be used with several content types and vice versa. The case where several item types "share" the same content type is very interesting: had a one-to-one restriction been enforced, you would have to create many identical content classes that would contain the same information.

Core classes

Before using NCommet, you should at least know about the core classes of NCommet. These are the classes that correspond to items, content objects, relations, etc. Read this page to find out more.

More item operations

The obvious operations are supported: create an item, add it under a parent item and remove it, add related items, etc. You can also:
  • Move an item and its subtree under another parent item.
  • Detach an item and its subtree, effectively creating a new tree.
  • Clone an item and its content with or without its subtree (shallow and deep clone)
  • Filter items based on their item type
  • Filter related items based on the relation type and the itemType of the related item.
  • Reorder an item among its siblings.

More operations are available if you're using NCommet's agents. You'll read more about NCommet's agents later on, but the first agent you'll probably be using is the persister, which is responsible for storing items and everything about them to a persistent storage, typically a database.

Last edited Apr 11, 2008 at 10:19 AM by NikolaosGeorgiou, version 12

Comments

No comments yet.