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.

• 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.

• DateTime {Name}Utc - You should always postfix your date fields with Utc, to make it obvious what the fields intended timezone is.

• 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;

• 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;

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.