Altering items
When altering items through the API you need to consider, which database you want to alter the item in. If you change an item retrieved from the web database, it will write the changes to the web database as well.
This means the changes will be overwritten as soon as you publish. Therefore you should make your changes to items retrieved from the master database. If you need the changes to appear right away, you need to publish the item programmatically. As another publish may be in progress, it still might take some time for the item to appear.
When altering an item in Sitecore, you need to set the item in an editing state. This is done by calling the Item.Editing.BeginEdit() and EndEdit() methods. As you are operating with a state you should always end the editing state, even though an exception occurs. Unfortunally the Sitecore API doesn’t provide a roll back, but the state should be closed anyway.
One more thing you want to pay attention to is security. The end user is normally logged in as the Extranet/Anonymous user, which by default isn’t allowed to change items. You can either setup proper security and make the user login or use the Sitecore.SecurityModel.SecurityDisabler, which disables security in a certain code block.
So when you want to alter an item, you should do something like this:
public void AlterItem()
{
//Use a security disabler to allow changes
using (new Sitecore.SecurityModel.SecurityDisabler())
{
//You want to alter the item in the master database, so get the item from there
Database db = Sitecore.Configuration.Factory.GetDatabase("master");
Item item = db.Items["/sitecore/content/home"];
//Begin editing
item.Editing.BeginEdit();
try
{
//perform the editing
item.Fields["Title"].Value = "This value will be stored";
}
finally
{
//Close the editing state
item.Editing.EndEdit();
}
}
}
Now the item is altered in the master database. If you want to publish the item programmatically, you need to setup some publish options and run the publish pipeline, as it is specified in the web.config. This can be done like this:
//We need the target database
Database webDb = Sitecore.Configuration.Factory.GetDatabase("web");
//We need to know the language to publish. Here we use the context language
Language language = Sitecore.Context.Language;
//We set the publish date to now
DateTime publishTime = DateTime.Now;
//Now we can create the publish options
Sitecore.Publishing.PublishOptions options = new PublishOptions(masterDb, webDb, PublishMode.SingleItem, language, publishTime);
//Activate the publishpipeline
Sitecore.Publishing.Pipelines.PublishItem.PublishItemPipeline.Run(item.ID, options);
Note that publishing automatically isn’t the best solution. For instance there may be some caching issues. Every time you publish the frontend cache is cleared, which in this case would mean, that the web cache can be cleared by an end user.
Creating items
Programmatically creating items in Sitecore is rather easy. You need to retrieve the root item, where the new item is to created under and then create the item with the Item.Add method, where it is also possible to specify either a template or a branch:
public void CreateItem()
{
//Again we need to handle security
//In this example we just disable it
using (new SecurityDisabler())
{
//First get the parent item from the master database
Database masterDb = Sitecore.Configuration.Factory.GetDatabase("master");
Item parentItem = masterDb.Items["/sitecore/content/home"];
//Now we need to get the template from which the item is created
TemplateItem template = masterDb.GetTemplate("sample/sample item");
//Now we can add the new item as a child to the parent
parentItem.Add("NewItemName", template);
//We can now manipulate the fields and publish as in the previous example
}
}
The add method also allows you to specify a branch, should you need that.
You should now have a fundamental idea on how you use the basic Item API, allowing you to read, alter and create items in Sitecore. Congratulations!