Core documentation and reference

Intro

The framwork basics

Managed elements

Field
Content type
List instance
View
Feature

How-tos

Fields
Content type
List instance
View
Feature


The framwork basics

The framework consists of a set of base classes and attributes that can be used to create Managed elements. That means elements that are managed through the Genesis framework and can be used anywhere in code by simply referencing the type. You can access element properties and invoke functions to perform common tasks. The managed elements can be on of these:
  • Fields (list fields or site columns)
  • List instances
  • Content types
  • Views
  • Features

The managed elements are declared with the managed elements declarative syntax. It consists of a class declarations which inherits from one of the base classes depending on which element type, and a class attribute also depending on which element type to use. For example, we have the field element which is declared using th base class SPGENField and the class attribute SPGENFieldAttribute.

The syntax for the field element looks like this:

    [SPGENField(
        ID = "{EC23CA6E-BA90-443F-9F3A-6D54889298F4}", 
        DisplayName = "My field 1", 
        Type = SPFieldType.Text, 
        Group = "SPGenesis demo")]
    public class MyField1 : SPGENField<MyField1, SPFieldText, string>
    {
    }


The idea is to create a class that represents our field and declare its attributes with .NET attributes as in the example above. This definition will be compiled into our assembly and now we can reference this class in our assemblies. This means, I could read its properties, provision it to a list or site, getting an instance to the field etc. Here is an example on how to access its definition and read what field type it is:

    Guid myField1Id = MyField1.ID;

    SPFieldType myField1Type = MyField1.Definition.Type;

    //and so on....


If we add a SPGENFeatureAssociationAttribute to our class we instruct the framework that the field definition is deployed with a feature installed in the farm. It will read all properties from the XML-definition instead if we use it like the example above. Here is an example of the declaration:

    [SPGENFeatureAssociation(ID = "{6CB9E7B7-1126-42D3-B23C-0B225A0C8BBF}")]
    [SPGENField(ID = "{EC23CA6E-BA90-443F-9F3A-6D54889298F4}")]
    public class MyField1 : SPGENField<MyField1, SPFieldText, string>
    {
    }


How does it work?

The syntax is easy to understand because it uses the name of common used properties and attributes of the target elements, as for the field for example. All declarations must start with a class declaration and then inherit from a base class provided from the Genesis framework. For fields, this base class is SPGENField<TField, TFieldType, TListItemValue>. And to that, we must add a class attribute to declare the required properties for our field. That is the field ID for field elements. Other attributes for the field element is Title, field type etc. Although it is possible to specify these properties in another way (we'll talk about it later on in the field element section), this is the preferable way of declaring our field. To specify these properties we use the SPGENFieldAttribute provided by the framework. Here is a breakdown of the syntax:

    [SPGENField(
        ID = "{Field ID}", 
        DisplayName = "[Field display name]", 
        Type = [Field type], 
        Group = "[Group name]")]
    public class [ClassName] : SPGENField<[ClassName], [SPField], [ListItemValue type]>
    {
    }    


First of all, we declare our main properties for our field that is the field ID, display name, type and group name (for site fields only).
The second part is the class declaration. The name of the class is not important for now other than it should probably be something you can refer to, as in our previous example it was "MyField1". It will also be used unless nothing else is specified, as the fields internal and static name when provisioning the field. More of that can be read in the field element in this documentation.

The inherited base type which is the SPGENField class provided by the Genesis framework. As you can see it has three generic type arguments. The first must be the same type which is being declared. The second is which SPField type it should be casted to when using certain function as for example GetField etc. The third and last is the type to cast its item value to when using the GetItemValue method (see ###) for example.

Summary

As you can see, you can declare your fields in your code completely by code and have a single point of access to its definition. No more constants and hard coded access to its field which could be difficult to maintain during time in a large project. Another feature is that you can mix both this declarative syntax and xml definition to support both of the techniques. The genesis framework will identify the field for example by using the field ID and an attribute to match the feature ID the field is contained in. You can read more about different techniques and scenarios in the documentation for each element.

Last edited Mar 28, 2011 at 10:03 PM by tore7506, version 6

Comments

No comments yet.