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.

Refs

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;

If you don't want this behaviour on a field that fits this pattern, override it by setting the type to something else (default: text).

Dates

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;

If you don't want this behaviour on a field that fits this pattern, override it by setting the type to something else (default: text).

Booleans

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;

If you don't want this behaviour on a field that fits this pattern, override it by setting the type to something else (default: text).

Canvas editors

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;

If you don't want this behaviour on a field that fits this pattern, override it by setting the type to something else (default: text).

Colour pickers

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;

If you don't want this behaviour on a field that fits this pattern, override it by setting the type to something else (default: text).

User selectors

uint {Name}UserId, int {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;

If you don't want this behaviour on a field that fits this pattern, override it by telling it to render with a regular UI/Input:

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

Entity selectors

uint {EntityName}Id - a uint field ending with Id will be checked to see if you have an entity, i.e. any content type on your site, with the same name. If one exists, a selector for that entity will be used on the admin panel.

public uint PageId; // Will display a dropdown of Page entries.

If you don't want this behaviour on a field that fits this pattern, override it 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.

Search mode for large sets

Because this is a generic content selector component, it makes some best guesses about what field to use as the display text in the dropdown. If you have a very large amount of content, a dropdown would be inappropriate and should display a searchable set instead to avoid listing thousands of things on an awkward dropdown. It has a search mode to help with this:

[Data("search", "title")]
public uint PageId;

This search Data attribute is a prop recognised by the Admin/ContentSelect component, so you can turn it on wherever you're using that component. The attributes value is the name of the field that is used during the search - in this case, we're searching pages based on if the search term matches anything in the page title.

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

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.

• [Module(true)] - This attribute tells the admin panel to hide your field with the given module.

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

• [Meta("metaFieldName")] - Marks this field as the source of a given named meta field.