Learning Umbraco in a week - Day VI

 

This is my sixth post of the "Learning Umbraco in a week" series. The main agenda of this post is listed below.

• Introduction to Umbraco API
• Working with the Umbraco Document API
• Working with the Umbraco Node Factory
• Introduction to Umbraco Events
• Working with Umbraco Member API
• Working with Umbraco User API
• Working with Umbraco Relationship API

Introduction to Umbraco API 

The Umbraco API give you programmatic access to everything in the Umbraco CMS. There are many ways to interact with the Umbraco API. From creating user-generated content from your web front-end via the Document API. To manage complex content relationships via the Relationship API. You can even represent the API as REST-Full Web Service Endpoints for use by your custom HTML Forms or web services. 

Working with the Umbraco Document API 
The Umbraco Document API provides programmatic access to Umbraco CMS Documents. The API provides the Document data which is stored inside the database.

1. Using the Umbraco Document API 
For using the Umbraco Document API, add the cms.dll, businesslogic.dll and umbraco.dll to your project.

Then add references to the following namespaces at the top of your .cs file.

  using umbraco.BusinessLogic;
  using umbraco.cms.businesslogic.web;

2. Creating an Umbraco Document 
The following Code Snippet creates an Umbraco Document and publish it.

  //First of all, we need to get the appropriate Document Type

  DocumentType docType = DocumentType.GetByAlias("Home");

  // Here we will get the appropriate creator of the Document.
  User author = User.GetUser(0);

  //For creating a Document we also need to mention the parent node
  //As this is the root document, we will use  -1
  Document doc = Document.MakeNew("Hello World", docType , author, -1);

  //The Document has been created
  // We will now publish the Document
  doc.Publish(author);

  //We will ask Umbraco to update the Document Cache
  umbraco.library.UpdateDocumentCache(doc.Id);

3. Modifying Document Properties 
The following Code Snippet get an Umbraco Document, modifies its properties and publish it.

  //First of all, we will get the appropriate Document
  Document doc = new Document(786);

  //Get the appropriate properties and modify the values
  doc.getProperty("bodyText").Value = "<p>Hello World!</p>";

  //The Document has been modified
  // We will now publish the Document
  User author = User.GetUser(0);
  doc.Publish(author);

  //We will ask Umbraco to update the Document Cache
  umbraco.library.UpdateDocumentCache(doc.Id);

4. Enumerating Documents Children 
The following Code Snippet get an Umbraco Document and enumerates its children.

  //First of all, we will get the appropriate Document
  Document doc = new Document(786);

  //We will check the Document's HasChildren property
  //before enumerating through the Children array
  if (doc.HasChildren) {
    //Now we will enumerate through the Children array
    Document[] children = doc.Children;
    foreach (Document childDoc in children) {
      Response.Write(childDoc.Text);
    }
  }

5. Attaching Document Event Handlers 
The following Code Snippet attach to the Document beforePublish event.

  protected void Page_Load(object sender, EventArgs e) {
     Document.BeforePublish +=
        new Document.PublishEventHandler( Document_BeforePublish );
  }

  void Document_BeforePublish(
    Document sender, umbraco.cms.businesslogic.PublishEventArgs e ) {
    Response.Write(sender.Text + " is being published");

    //We will set the EventArgs.Cancel = true, i.e. for cancelling the event
    e.Cancel = true;
  }

6. Moving a Document 
The following Code Snippet moves an Umbraco Document beforePublish event.

  //First of all, we will get the appropriate Document
  Document doc = new Document(786);

  //Move the document the new Parent Node
  int newParentNode = 1234;    doc.Move(newParentNode);

  //We will ask Umbraco to update the Document Cache
  umbraco.library.RefreshContent(); 

Working with the Umbraco Node Factory 
The Umbraco Node Factory is a strongly type presentation of the in Memory XML Cache optimized for reading (it's read-only). Which means it's very fast and only includes published content. The API provides the Node data which is published (and stored inside the Umbraco.config).

1. Using the Umbraco Node Factory 
For using the Umbraco Node Factory, add the interfaces.dll, cms.dll, businesslogic.dll and umbraco.dll to your project.

Then add references to the following namespaces at the top of your .cs file.

  using using umbraco.NodeFactory

2. Retrieving an Umbraco Node 
The following Code Snippet retrieves an Umbraco Node.

  Node node= new Node(786);
  //Use Node.GetCurrent() method to get the Current Node
  string bodyText= node.GetProperty("bodyText").Value;
  string nodeName = node.Name;
  DateTime nodeCreationDate = node.CreateDate;
  string nodeUrl = node.NiceUrl; 

Introduction to Umbraco Events 
For registering events in Umbraco, ApplicationBase class is used, as it is called automatically when Umbraco loads.

1. Using the Umbraco Events 
For using the Umbraco Events, add the cms.dll, businesslogic.dll and umbraco.dll to your project.

Then add references to the following namespaces at the top of your .cs file.

  using umbraco.BusinessLogic; 
  using umbraco.cms.businesslogic;
  using umbraco.cms.businesslogic.web;

2. Registering Events in Umbraco 
The following Code Snippet extends the ApplicationBase class and registers the event in the default constructor.

  public class AppBase : umbraco.BusinessLogic.ApplicationBase {

    public AppBase() {
      Document.BeforePublish += 
        new Document.PublishEventHandler(Document_BeforePublish);
    }

    void Document_BeforePublish(Document sender, PublishEventArgs e) {
      //TODO
    }
  }

3. Overview of All Events 
Events can be attached with the following Umbraco objects.

• Document
• Access
• DocumentType
• Domain
• StyleSheet
• StyleSheetProperty
• Member
• MemberGroup
• MemberType
• CMSNode
• Dictionary
• Media
• MediaType
• DataTypeDefinition
• Language
• Macro
• CreatedPackage
• InstalledPackage
• Template
• ContentControl
• BaseTree
• User
• Content 

Working with the Umbraco Member API 
A Member in Umbraco is an external person, who has a profile on the website. Members are distinct from Umbraco Users, meaning that a Member do not have access to the Umbraco back-end. The Member API provides access to the Members data which is stored inside the database. 

1. Using the Umbraco Member API 
For using the Umbraco Member API, add the umbraco.dll to your project. 

Then add references to the following namespaces at the top of your .cs file. 

  using umbraco.cms.businesslogic.member; 

2. Creating a Member 

The following Code Snippet creates an Umbraco Member and sets a property.

  //First of all we will have to select the appropriate Member Type
  MemberType memberType = MemberType.GetByAlias("standard");

  //Create a member

  Member member = 

    Member.MakeNew("Awan", memberType, new umbraco.BusinessLogic.User(0));

  //Set a property value on the member

  member.getProperty("city").Value = "London";

  //We will ask Umbraco to update the Member Cache

  member.XmlGenerate(new System.Xml.XmlDocument());

  //Save the Member

  member.Save();

3. Adding Member to a Group 

The following Code Snippet add an Umbraco Member to a Group and then removes it.

  //First of all we will have to select the appropriate Member

   Member member = Member.GetMemberFromEmail("muneeb@email.com");

  //Get the appropriate Member Group

  MemberGroup memberGroup = MemberGroup.GetByName("admin");

  //Add Member to the Group

  member.AddGroup(memberGroup.Id);

  //Remove Member from the Group

  member.RemoveGroup(memberGroup.Id); 

Working with the Umbraco User API 

Umbraco provides access of Umbraco Back-End via Umbraco User API for writers, translators, editors and administrators. 

1. Using the Umbraco User API 

For using the Umbraco User API, add the umbraco.dll to your project. 

Then add references to the following namespaces at the top of your .cs file. 

  using umbraco.BusinessLogic;

2. Creating a User and allow Access to Umbraco Section

The following Code Snippet creates an Umbraco User and sets a property. 

  //First of all we will get the appropriate User Type
  UserType userType = UserType.GetUserType(123); 

  //Create a new User
  User.MakeNew("Awan", "awan", "secrectPass", userType);

  //Get the User via Login
  User user = new User("awan");

  //Add User Email
  user.Email = "muneeb@email.com";

  //Allow access to Umbraco Section
  user.addApplication("settings");

  //Save the User 
  user.Save();

Working with the Umbraco Relationship API 

The Umbraco Relationship API enables associations or links between Typed NodeIds be defined. For example, you may wish to make a connection between Members and Email (Document) etc.

1. Using the Umbraco Relationship API 

For using the Umbraco Relationship API, add the umbraco.dll to your project. Then we need to defien an Umbraco Relation Type

• A row first needs to be added into the UmbracoRelationType Table in the Database (Detail available below).
• The Relation Types Package can used to define a type of link.

It's then possible to progmatically add / remove and quickly select relationships between typed Ids. We can now add references to the following namespaces at the top of your .cs file. 

  using cms.businesslogic.relations

2. Object GUIDs for Creating Relation Types 

To setup a RelationType in Umbraco, we will need the exact GUID of the appropriate Types, e.g, Document to Member, Member to Media, Media to Media.

A list of all the built Object Types and their GUIDs is below.

ObjectType	Description
C66BA18E-EAF3-4CFF-8A22-41B16D66A972	Document
B796F64C-1F99-4FFB-B886-4BF4BC011A9C	Media
6FBDE604-4178-42CE-A10B-8A2600A2F07D	Template
39EB0F98-B348-42A1-8662-E7EB18487560	Member
A2CB7800-F571-4787-9638-BC48539A0EFB	DocumentType
366E63B9-880F-4E13-A61C-98069B029728	MemberGroup

For a complete his list of Object Types please visit, Hendy Rachers Blog.

That's all for this post, in the next post (Learning Umbraco in a week - Day VII) we will have a look at LINQ to Umbraco.