Getting started with Items API

This is an introductory article that will help you get started with Items API in Dynamicweb. Here we will cover the basics: the API structure, the way item types are instantiated and the rules you should follow in order to implement your first item type using C#.

API structure

All item-related types are defined in "Dynamicweb" assembly (Dynamicweb.dll) under "Dynamicweb.Content.Items" namespace. This namespace, in turn, contains several sub-namespaces:

  • Dynamicweb.Content.Items.Activation
    This namespace contains types that are used for activating items. The term "activation" usually means generating nessesary metadata files as well as database tables for a given item type. Also, the term "activation" can refer to creation of item instances. Note: there are three ways of activating items (model-first, database-first and code-first) but in this series of articles we assume that the code-first approach is used (since we define our items by using C# code).
     
  • Dynamicweb.Content.Items.Annotations
    This namespace contains various custom attributes used for tweaking the behavior of the item types. For example, you can put item fields into different group by using GroupAttribute or apply a custom editor to a given item field by using EditorAttribute. We will discuss types from this namespace in more detail later in this series.
     
  • Dynamicweb.Content.Items.Editors
    This namespace contains concrete implementations of field editors. A field editor is an object that is responsible for presenting a user with the UI for editing field value (for example, a text box for editing text fields, a date picker for editing dates, etc.). Editors will be covered in more detail in the next articles of this series.
     
  • Dynamicweb.Content.Items.Metadata
    This namespace contains a strongly-typed representation of an item type metadata file. Every item type when created is given an .xml-file which contains various information about the item type (what fields does the item type contain, how these fields should be organized and manipulated, etc.). The metadata is also used wnen synchronizing item type changes (for example, when you're adding an additional field to already existing item type, the system must reflect this change on the database layout and the metadata is used to determine the current "state" of an item type).
     
  • Dynamicweb.Content.Items.Queries
    This namespace contains types that are used for interacting with item storage (database). The central part of this namespace is a repository - an object that is used for querying items from the database as well as saving, updating and deleting items from the database.
     
  • Dynamicweb.Content.Items.Rendering
    This namespace contains types that are used for presenting items on the frontend (list, details and edit views). The Item Publisher module as well as some of the core components of Dynamicweb use types from this namespace to render items and related information (for example, metadata).

Item vs ItemEntry

There're two main types in the items API that represent an item instance: Item and ItemEntry. The difference is that Item is used in cases when you don't have a CLR type backing your item type. For example, when you created a new item type through Dynamicweb backend, there's no CLR type that corresponds to the newly created item type and so the system needs so general way of treating all item instances. Item is basically a dictionary whose keys correspond to system names of the item type fields and values - to item field values. Normally you don't need to use Item when you're defining item type from code. On the other hand, ItemEntry encapsulates a minimum required properties of any item (for example, every item is required to have an Id, being able to serialize and deserialize, etc.). You must use ItemEntry for defining your items types from code and in fact Item also uses ItemEntry (it's directly inherited from ItemEntry). Both Item and ItemEntry are defined under Dynamicweb.Content.Items namespace.

ItemManager

The ItemManager is defined under Dynamicweb.Content.Items namespace and represents an entry point to items API. The majority of the item-related tasks can be accomplished by using the ItemManager (for example, activating and querying items, querying metadata, etc.) and so it's basically a set of shortcuts to various parts of the API.

Defining your first item type

Let's now define your first item type using C# and Visual Studio 2012. First of all, create a new project of type "Class library" as shown below (make sure you target .NET Framework 4.0):

The very next thing is to add a reference to "Dynamicweb" assembly:

Now we're ready to start with defining the item item. Add a new class called "BlogPost" and paste the following into the file that Visual Studio has created for you:

using Dynamicweb.Content.Items;

namespace ItemsCodeFirst
{
	public class BlogPost : ItemEntry
	{
		public string Heading { get; set; }
	}	
}

Congratiulations! You've just defined a new item type with one field of type "string". There's a couple of things we should point on here:

  • The class must be public (have a "public" access modifier) otherwise Dynamicweb won't be able to find it while activating items.
     
  • The class must be inherited from ItemEntry (defined in Dynamicweb.Content.Items namespace) so Dynamicweb will know that this is an item.
     
  • The class must contain a public parameterless constructor (in the example above we don't define any constructors and so the compiler will emit the default constructor for us automatically).
     
  • Every public property of a class that can be read from and written to becomes an item field.

Now compile the project and copy the resulting assembly file (ItemsCodeFirst.dll in our case) to the "bin" folder of your Dynamicweb installation. Next, open your browser and navigate to Dynamicweb backend (it can take a while for Dynamicweb application to restart), go to Management Center -> Item types. You should see your newly created item type in the list (the activation process happened on the application start but you can trigger it manually by hitting the "Refresh" button on the toolbar on the item type list page).

Conclusion

This was a quick "Getting started" guide to items API. In the next article of the series we're going to see how to customize the appearance and behavior of your item types by using custom attributes and overriding base class members.