The Entity-Manipulation API
To enable programmers to create / edit / delete entities using their own C# code, we provide a simplified API for just these actions. So you have 3 commands, as follows:
- Create
- Update
- Delete
How can you quickly learn this?
Install these tutorial apps, discover!
Where can you use this?
Basically there are 2 typical places for this
- In your C# Razor template (see related posts below)
- In your C# WebAPI Controller (see related posts below)
The Syntax
These commands are attached to a DataController - who is in charge of data-management. So the most common way to use it is
- App.Data.Create(Content-Type-Name, DictionaryOfValuesToAdd)
- or App.Data.Create(Content-Type-Name, DictionaryOfValuesToAdd, UserNameToLog)
- App.Data.Update(Id-As-Int, DictionaryOfValuesToChange)
- or App.Data.Update(Id-As-Int, DictionaryOfValuesToChange, UserNameToLog)
- App.Data.Delete(Id-As-Int)
- or App.Data.Delete(Id-As-Int, UserNameToLog)
Catching Errors
All these commands will either succeed or throw an error, so you will usually do something like
try
{
App.Data.Create("Comment", values);
message = App.Resources.SaveSucceeded;
}
catch
{
message = App.Resources.SaveFailed;
}
The Values-Dictionary
This is a simple Dictionary<string, object>. Note that if you use invalid types, the save will fail. Here's an example
var Values = new Dictionary<string, object>;
Values.Add("Title", Request.Form["Title"]);
Values.Add("Message", Request.Form["Message"]);
Values.Add("Rating", Convert.ToInt(Request.Form["Rating"]);
DataController().Add("Comment", Values);
Setting Published State
In 2sxc each save-operation can be published or unpublished. If it's unpublished, then users with read-access will see the previous state (so either without a just-added-entity, or in the previously published version). By default, the simple API will have the following effect on data:
- When you Create new entities, these are published by default
- When you Update existing entities, these will NOT change the published state by default. So updating an entity which has a draft will only affect the draft (by default)
- Delete is always a full delete, removing both a draft and/or the published entity
You can specifically say what you want as follows:
Values.Add("IsPublished", true); // would make it published
Values.Add("IsPublished", false); // keep it unpublished
Just so you don't get things wrong: an Update with "IsPublished"=false will not hide the existing entity, but will hide the change you just made. You can discover more in the related posts.
Some Performance Notes
2sxc is fully cached - at the App-Level. So any changes will reload the cache for this App. This will usually not affect your work, but could have 1-2 side effects
- if your App had many thousand entities, you may feel that the read after a write may have a delay
- If you have entities in some object before saving, these entities may become invalid after saving - so they might still contain the deleted entity as it was cached before the change.
Read more about the cache in the related posts below.
Relationships to other Entities
Relationships are established through EntityIds (or GUIDs?) todo. Note that the sort-order is preserved (todo: check). To add them, use code as follows:
Values.Add("Format", new List<int>() { formatId }); // add one
var tags = new List<int>();
tags.Add(17);
tags.Add(32);
Values.Add("Tags", tags);
Notes on Multiple Languages
The simple API assumes standard language needs - so it will always only create entities in the main language, update attributes in the main language and of course delete the entire entity in all languages. For language-specific data handling (which can be very complex) there is currently no official API.
Some Security Notes
For security reasons, the simple API does the following
- Only allow changes in the current portal and App
Deleting Entities
This will fail if the entity is in use. Common In-Use-Cases are:
- when the entity has incoming relationships (so a person-entity, who is referred to in a books author-field)
- when the entity is in use on a specific module (in use means that it was assigned manually in "content-mode")
- when the entity is used as a demo-entity in a view/template
The error message should help you get it right.