Entities

An entity is an object which stores fields of information, usually in your database but can also be in memory only. Virtually everything in a SocialStack API is an entity of some form - roles, pages, menu items and so on.

The quickest way to create an entity is to generate a template of one like so:

socialstack generate Api/TodoItems

Use a plural name here, otherwise you'll be asked if you wanted to make a simple service instead. This is to avoid class naming collisions, i.e. the above ultimately creates an entity class called Api.TodoItems.TodoItem.

Fields

Edit your entity .cs file and you'll see some sample fields. Simply adding a field will allow it to be stored in the database and it will also be editable via the admin panel and appear in your API requests including Loop. Use a C# property instead if you don't want it to be stored in the database but did want it to appear everywhere else.

Field names

Some field names are treated specially for convenience. This is the list of all current patterns checked for by AutoFormService.

• string {Name}Ref - A string field ending with Ref indicates a file. You'll get a file selector in the admin panel for these. They should be given to the getRef function at UI/Functions/GetRef to either obtain a url or display it directly.

Whilst it's always recommended to end a field with ref so it's clear what data people are working with, you can get the same file selector on a field that doesn't end in ref by setting the type to image or file:

[Data("type", "file")]
public string MyFileSelector;

• DateTime {Name}, DateTime? {Name} - You should always postfix your date fields with Utc to make it obvious what the fields intended timezone is, however, any DateTime or DateTime? field will display a date selector. This is the same as setting the type to datetime:

[Data("type", "datetime")]
public DateTime MyDateSelector;

• bool {Name}, bool? {Name} - Displays a checkbox on any bool field. This is the same as setting the type to checkbox:

[Data("type", "checkbox")]
public int ZeroOrOne;

• string {Name}Json - A string field ending with Json indicates canvas JSON by default. You'll get a wysiwig editor. If you want a regular Json editor instead, use a data attribute, like this:

[Data("contentType", "application/json")]
public string ConfigurationJson;

To get a canvas editor on a field that does not end in Json, set the type to canvas:

[Data("type", "canvas")]
public string Configuration;

• string {Name}Color, string {Name}Colour - Displays a colour picker. To get a colour picker on any other field, set the type to color:

[Data("type", "color")]
public string Background;

• uint {Name}UserId - Displays a user selector. To display the same user selector on some other field, set the module like so:

[Module("Admin/User/Select")]
public uint ModeratedBy;

• uint {EntityName}Id - a uint field ending with Id will be checked to see if you have an entity with the same name. If one exists, a selector for that entity will be used on the admin panel. For example:

public uint PageId;

Will display a selector for a page. Override this behaviour by telling it to render with a regular UI/Input:

[Module("UI/Input")]
public uint PageId;

If you would like the same content selector on a field which does not match this pattern, set the module and contentType like so:

[Module("Admin/ContentSelect")]
[Data("contentType", "page")]
public uint ParentPageId;

As with all Data attributes, contentType here is just a prop of the Admin/ContentSelect component. I.e. we're telling the form system to use a specific component to render this field and giving it some additional props to use as well.

Field Attributes

SocialStack conveniences above are often all that is necessary, however, there are certainly times where it is useful to have a field display with a custom editor component, or not display at all. You can add attributes to your fields to customise the field behaviour in a variety of ways:

• [Module("Admin/ModuleName")] - This attribute tells the admin panel to render your field with the given module. The module will receive everything that UI/Input would have, so that's props like label, name and value.

• [Data("propName", "propValue")] - This attribute passes additional props to the admin panel rendering of your component. Works best with custom modules, but can also be used to override certain default behaviours.

• [Localized] - Often used on names and descriptions, this attribute indicates that the field varies by locale. Works with any field type meaning it can also be used to make, for example, a price vary by locale too. When you use localized fields and there are more than one locale on your site, you'll get a dropdown on the admin panel to switch between editing different locales.