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
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 {
// 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.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");
//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());
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.
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.
//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();
//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.
