SocialStack - User contributions [en-gb]

Migration Framework

2026-01-24T12:24:23Z

Luke: /* Compatibility */

If you'd like to move your data in either direction between any database engine (currently 3) supported by Socialstack, there is a built in migration mechanism at /v1/migration/migrate. This mechanism is best used for sidegrades rather than up/downgrading.

The following example assumes MySQL to MongoDB.

= Configuration =

You first need to have installed Api/DatabaseMySQL and Api/DatabaseMongoDB in to your project. In your appsettings.json, you then connect to both:

<syntaxhighlight lang="json">

"ConnectionStrings": {
"DefaultConnection": "server=localhost;port=3306;SslMode=none;AllowPublicKeyRetrieval=true;database=X;user=Y;password=Z"
},
"MongoConnectionStrings": {
"IsPrimary": true,
"DefaultConnection": "mongodb://localhost:27017/X?ssl=false"
}

</syntaxhighlight>

Mark the target database engine as IsPrimary: true. Start it up and you should see "MySQL is installed and configured but not mounting as it is not the primary DBE" appear in the console.

From here, login as the admin account as normal (using details from the primary database, Mongo in this case). Then, load the migrate URL:

/v1/migration/migrate?from=mysql&to=mongodb

The files for this are in Api/Database/Migration/ - it is recommended to look over that to understand how it works and what it will do. Importantly, it does not delete anything at any point by default, it essentially just loads objects from one database engine and creates them in the other, transferring the ID's as-is. You may want to delete any generated contents of your target database in between starting up the site and running this.

= Compatibility =

Due to the copy transfer mechanism, note that it does not passively upgrade or downgrade. Most things are cross-compatible through a wide range of socialstack versions, however there are two notable compatibility points:

* Any mappings from core 2024 and earlier would be skipped. This is because in core 2025 and onwards, they changed to being inline in rows/documents instead.

* Permalinks did not exist in core 2024 and earlier. There is a custom built routing engine inside core 2025 which made automated link preservation possible, complex multi-directory slugs as well as removing the dependency on having a reverse proxy (you can run core 2026 onwards without NGINX, redirect rules included). In a core 2024 -> 2025+ migration, the URLs on pages will implicitly be dropped. The page structure itself is the same however, albeit a core 2025+ project defaults to generating pages with wrapping templates.

If you need any assistance with generating permalinks or migrating mappings as well please do ask! In short you can see the target format if you allow core 2025+ to startup and generate its default data, and then look at e.g. the site_page table. In there is a JSON column called Mappings which holds that data instead. For permalinks, it is site_permalink where you will see a relatively simple source URL and target locator, usually of the form "page:X" where X is an ID.

Migration Framework

2026-01-24T12:23:33Z

Luke: /* Compatibility */

If you'd like to move your data in either direction between any database engine (currently 3) supported by Socialstack, there is a built in migration mechanism at /v1/migration/migrate. This mechanism is best used for sidegrades rather than up/downgrading.

The following example assumes MySQL to MongoDB.

= Configuration =

You first need to have installed Api/DatabaseMySQL and Api/DatabaseMongoDB in to your project. In your appsettings.json, you then connect to both:

<syntaxhighlight lang="json">

"ConnectionStrings": {
"DefaultConnection": "server=localhost;port=3306;SslMode=none;AllowPublicKeyRetrieval=true;database=X;user=Y;password=Z"
},
"MongoConnectionStrings": {
"IsPrimary": true,
"DefaultConnection": "mongodb://localhost:27017/X?ssl=false"
}

</syntaxhighlight>

Mark the target database engine as IsPrimary: true. Start it up and you should see "MySQL is installed and configured but not mounting as it is not the primary DBE" appear in the console.

From here, login as the admin account as normal (using details from the primary database, Mongo in this case). Then, load the migrate URL:

/v1/migration/migrate?from=mysql&to=mongodb

The files for this are in Api/Database/Migration/ - it is recommended to look over that to understand how it works and what it will do. Importantly, it does not delete anything at any point by default, it essentially just loads objects from one database engine and creates them in the other, transferring the ID's as-is. You may want to delete any generated contents of your target database in between starting up the site and running this.

= Compatibility =

Due to the copy transfer mechanism, note that it does not passively upgrade or downgrade. Most things are cross-compatible through a wide range of socialstack versions, however there are two notable compatibility points:

* Any mappings from core 2024 and earlier would be skipped. This is because in core 2025 and onwards, they changed to being inline in rows/documents instead.

* Permalinks did not exist in core 2024 and earlier. There is a custom built routing engine inside core 2025 which made automated link preservation possible, complex multi-directory slugs as well as removing the dependency on having a reverse proxy (you can run core 2026 onwards without NGINX, redirect rules included). In a core 2024 -> 2025+ migration, the URLs on pages will implicitly be dropped. The page structure itself is the same however.

If you need any assistance with generating permalinks or migrating mappings as well please do ask! In short you can see the target format if you allow core 2025+ to startup and generate its default data, and then look at e.g. the site_page table. In there is a JSON column called Mappings which holds that data instead. For permalinks, it is site_permalink where you will see a relatively simple source URL and target locator, usually of the form "page:X" where X is an ID.

Migration Framework

2026-01-24T12:21:59Z

Luke: Created page with "If you'd like to move your data in either direction between any database engine (currently 3) supported by Socialstack, there is a built in migration mechanism at /v1/migratio..."

If you'd like to move your data in either direction between any database engine (currently 3) supported by Socialstack, there is a built in migration mechanism at /v1/migration/migrate. This mechanism is best used for sidegrades rather than up/downgrading.

The following example assumes MySQL to MongoDB.

= Configuration =

You first need to have installed Api/DatabaseMySQL and Api/DatabaseMongoDB in to your project. In your appsettings.json, you then connect to both:

<syntaxhighlight lang="json">

"ConnectionStrings": {
"DefaultConnection": "server=localhost;port=3306;SslMode=none;AllowPublicKeyRetrieval=true;database=X;user=Y;password=Z"
},
"MongoConnectionStrings": {
"IsPrimary": true,
"DefaultConnection": "mongodb://localhost:27017/X?ssl=false"
}

</syntaxhighlight>

Mark the target database engine as IsPrimary: true. Start it up and you should see "MySQL is installed and configured but not mounting as it is not the primary DBE" appear in the console.

From here, login as the admin account as normal (using details from the primary database, Mongo in this case). Then, load the migrate URL:

/v1/migration/migrate?from=mysql&to=mongodb

The files for this are in Api/Database/Migration/ - it is recommended to look over that to understand how it works and what it will do. Importantly, it does not delete anything at any point by default, it essentially just loads objects from one database engine and creates them in the other, transferring the ID's as-is. You may want to delete any generated contents of your target database in between starting up the site and running this.

= Compatibility =

Due to the copy transfer mechanism, note that it does not passively upgrade or downgrade. Most things are cross-compatible through a wide range of socialstack versions, however there are two notable compatibility points:

* Any mappings from core 2024 and earlier would be skipped. This is because in core 2025 and onwards, they changed to being inline in rows/documents instead. Similarly you would also be missing

* Permalinks did not exist in core 2024 and earlier. There is a custom built routing engine inside core 2025 which made automated link preservation possible, complex multi-directory slugs as well as removing the dependency on having a reverse proxy (you can run core 2026 onwards without NGINX, redirect rules included). In a core 2024 -> 2025+ migration, the URLs on pages will implicitly be dropped. The page structure itself is the same however.

If you need any assistance with generating permalinks or migrating mappings as well please do ask! In short you can see the target format if you allow core 2025+ to startup and generate its default data, and then look at e.g. the site_page table. In there is a JSON column called Mappings which holds that data instead. For permalinks, it is site_permalink where you will see a relatively simple source URL and target locator, usually of the form "page:X" where X is an ID.

API Caching

2023-08-30T19:35:57Z

Luke:

It's often the case that you have at least a few [[entities]] which are accessed much more often than they are updated. Typically a site's throughput is limited by the database so the less database traffic that happens the higher that throughput will be. SocialStack has a built in caching mechanism which allows you to mark an entity as cached. This means the list of all entities of that type is obtained once during server startup and then kept up to date through the [[ContentSync|internal server mesh network]].

Caching therefore works best if you cache things accessed frequently but changed rarely. As cached objects are stored in your web servers memory, be careful not to cache something huge such as a type with 10M+ rows unless you have the RAM to spare. Some built in examples are site configuration, locales and the pages of your site. These are all cached by default.

= Usage =

To make an entity use the cache, simply call Cache(); from within the service constructor:

<syntaxhighlight lang="csharp">

public ThingService() {

// "Thing" entities will be cached.
Cache();

}

</syntaxhighlight>

If it is a thirdparty service and you would like to avoid editing its source to allow for easier updates, you can also call Cache(); via the Events.Service.AfterStart event.

= Functionality =

The cache reuses objects whenever possible so when you ask a caching service to get or list objects then little to no allocations actually happen. These calls also return instantaneously as the object is coming from an already loaded in-memory data structure. In the example above, if you ask "ThingService" to get object with ID #14, that returned object is returned immediately, comes from the cache and is also reused.

'''Because the object is reused, avoid changing its fields anywhere other than via Update'''.

<syntaxhighlight lang="csharp">

// private ThingService _thingService;

// This returns instantly with a reused object.
var thing14 = await _thingService.Get(context, 14);

// Because it's reused, do not edit fields!
// thing14.Name = "do not do this";

// The only correct way to update fields is via the usual update call:
thing14 = await _thingService.Update(context, thing14, (Context c, Thing updateable) => {
updateable.Name = "Updated Name";
});

</syntaxhighlight>

= Performance =

Because cached services are not depending on the database and do not allocate, they have extremely high throughput. You can use service Get hundreds of millions of times per second without risking long GC pauses (not that you would ever put this much traffic on one server though!). The JSON serialisation process also avoids as many allocations as possible and can also return more than 10 million results per second via a websocket. The limiting factor is usually the network bandwidth.

Note that the use of the websocket is important if you are expecting this level of throughput being necessary. That is because the context needs to collect the user information which usually involves the database (the user service is rarely set to being cached, but you can do that too) and this context load only occurs once on a websocket.

= ID Assignment =

Because caching a service is primarily done for performance, enabling the cache also makes a service switch ID assignment model. This is covered in more detail on the [[ContentSync|clustering mechanics page]].

ContentSync

2023-08-30T19:27:18Z

Luke: /* AWS Elastic Loadbalancing */

SocialStack sites are built for high throughput out of the box, however, there always comes a scale where you need to expand on to multiple servers. You need to measure this for your site, but that scale tends to be around 5000 simultaneous users. Beyond this value, NGINX and Linux start to struggle with file pointers and the database connection pool starts getting too busy. Usually the step from 1 to 2 servers requires large amounts of engineering to ensure everything works together correctly. SocialStack has built in clustering mechanics, ContentSync, which helps servers work together on most things automatically by default.

= How ContentSync works =

Servers in a SocialStack site cluster register themselves with an entry in your database, as an entity called ClusteredServer. This entity tracks the servers current public and private IP addresses to allow servers to communicate directly with each other via a mesh network, over a datacenter private LAN whenever possible. Depending on the host(s) you're on, private VLANs can extend beyond a particular datacenter meaning the private IPs of your servers are reachable from any of your servers worldwide.

Once a server is registered as a ClusteredServer and has started communicating with other servers, they talk about 2 main things: the status of network rooms and [[API Caching|cached entities]]. Network rooms provide an abstract mechanism for messaging a group of people (or a single person) who can be connected to any combination of servers, including one user connected to multiple servers. Cached entities, when edited on a server, triggers a message to all other present servers to tell them about the update. This allows cached objects to completely avoid hitting the database except for the server which triggered the update message in the first place.

== AWS Elastic Load Balancing ==

Because SocialStack servers just need to exist and point at your database to start taking load and working together, SocialStack naturally works well with ELB. There is just one very important note: When ELB destroys and recreates servers, you need to make sure your hostnames are based on reused values. For example, if you have 3 servers in your ELB pool, their hostnames are always 1, 2 and 3. If 2 dies, the new replacement node gains hostname 2. This avoids your ClusteredServer table growing with hundreds of entries of dead servers. That is mostly only problematic for the block ID assignment mentioned below as it results in large chunks of your ID space becoming permanently unusable otherwise.

= ID Assignment =

SocialStack has multiple methods for assigning an ID to a new object.

== Database assignment ==

The default for most entities is to use the method provided by the database: the latest database insertion ID. This has two problems:

* Not all database engines support it. MySQL is just the default - SocialStack doesn't actually rely on MySQL exclusively.
* It requires a centralised, singular counter. At high throughputs, keeping IDs from colliding becomes a bottleneck.

As a result, alternate methods are also present for the purpose of solving these problems. Most sites however won't actually encounter this as an issue.

== Block assignment ==

The high throughput ID assignment mode, also activated when an entity is set to cache, is where each server in a cluster has exclusive ownership of a block of IDs. These blocks are spaced very far apart as they are formed by combining the ClusteredServer ID with the latest rolling number for that particular server.

If you are seeing very large IDs appear in your database, it is because there are multiple entries in your ClusteredServer table (site_clusteredserver) and block assignment is active. If your site is not live yet, or there is only 1 server in your live cluster, you can truncate this table and restart the server to have it assign lower IDs if you would like it to do so.

== Low frequency block assignment ==

In this mode, clustered servers assume the object will be created at very low frequency and will self-assign IDs but will do it by discovering the latest assigned ID and adding 1. This always creates compact linear IDs and is similar to database assignment, except it does not rely on a central counter.

An example of an entity that uses low frequency block assignment is locales. Locales are edited rarely so they are cached meaning block assignment is active, but they also benefit greatly from having compact close together IDs due to the way how many SocialsStack features internally optimise localised sets. So, by setting it to low frequency block assignment the locales will end up tightly next to each other in the ID space - even if the database increment value is incorrect.

Because of this methods simplcitity ("latest plus one") - it is vulnerable to ID collisions if the object is actually created at a high frequency and the servers knowledge of the latest object is simply fractionally out of date.

ContentSync

2023-08-30T19:24:02Z

Luke: /* How ContentSync works */

SocialStack sites are built for high throughput out of the box, however, there always comes a scale where you need to expand on to multiple servers. You need to measure this for your site, but that scale tends to be around 5000 simultaneous users. Beyond this value, NGINX and Linux start to struggle with file pointers and the database connection pool starts getting too busy. Usually the step from 1 to 2 servers requires large amounts of engineering to ensure everything works together correctly. SocialStack has built in clustering mechanics, ContentSync, which helps servers work together on most things automatically by default.

= How ContentSync works =

Servers in a SocialStack site cluster register themselves with an entry in your database, as an entity called ClusteredServer. This entity tracks the servers current public and private IP addresses to allow servers to communicate directly with each other via a mesh network, over a datacenter private LAN whenever possible. Depending on the host(s) you're on, private VLANs can extend beyond a particular datacenter meaning the private IPs of your servers are reachable from any of your servers worldwide.

Once a server is registered as a ClusteredServer and has started communicating with other servers, they talk about 2 main things: the status of network rooms and [[API Caching|cached entities]]. Network rooms provide an abstract mechanism for messaging a group of people (or a single person) who can be connected to any combination of servers, including one user connected to multiple servers. Cached entities, when edited on a server, triggers a message to all other present servers to tell them about the update. This allows cached objects to completely avoid hitting the database except for the server which triggered the update message in the first place.

== AWS Elastic Loadbalancing ==

Because SocialStack servers just need to exist and point at your database to start taking load and working together, SocialStack naturally works well with ELB. There is just one very important note: When ELB destroys and recreates servers, you need to make sure your hostnames are based on reused values. For example, if you have 3 servers in your ELB pool, their hostnames are always 1, 2 and 3. If 2 dies, the new replacement node gains hostname 2. This avoids your ClusteredServer table growing with hundreds of entries of dead servers. That is mostly only problematic for the block ID assignment mentioned below as it results in large chunks of your ID space becoming permanently unusable otherwise.

= ID Assignment =

SocialStack has multiple methods for assigning an ID to a new object.

== Database assignment ==

The default for most entities is to use the method provided by the database: the latest database insertion ID. This has two problems:

* Not all database engines support it. MySQL is just the default - SocialStack doesn't actually rely on MySQL exclusively.
* It requires a centralised, singular counter. At high throughputs, keeping IDs from colliding becomes a bottleneck.

As a result, alternate methods are also present for the purpose of solving these problems. Most sites however won't actually encounter this as an issue.

== Block assignment ==

The high throughput ID assignment mode, also activated when an entity is set to cache, is where each server in a cluster has exclusive ownership of a block of IDs. These blocks are spaced very far apart as they are formed by combining the ClusteredServer ID with the latest rolling number for that particular server.

If you are seeing very large IDs appear in your database, it is because there are multiple entries in your ClusteredServer table (site_clusteredserver) and block assignment is active. If your site is not live yet, or there is only 1 server in your live cluster, you can truncate this table and restart the server to have it assign lower IDs if you would like it to do so.

== Low frequency block assignment ==

In this mode, clustered servers assume the object will be created at very low frequency and will self-assign IDs but will do it by discovering the latest assigned ID and adding 1. This always creates compact linear IDs and is similar to database assignment, except it does not rely on a central counter.

An example of an entity that uses low frequency block assignment is locales. Locales are edited rarely so they are cached meaning block assignment is active, but they also benefit greatly from having compact close together IDs due to the way how many SocialsStack features internally optimise localised sets. So, by setting it to low frequency block assignment the locales will end up tightly next to each other in the ID space - even if the database increment value is incorrect.

Because of this methods simplcitity ("latest plus one") - it is vulnerable to ID collisions if the object is actually created at a high frequency and the servers knowledge of the latest object is simply fractionally out of date.

ContentSync

2023-08-30T19:05:45Z

Luke: /* Low frequency block assignment */

SocialStack sites are built for high throughput out of the box, however, there always comes a scale where you need to expand on to multiple servers. You need to measure this for your site, but that scale tends to be around 5000 simultaneous users. Beyond this value, NGINX and Linux start to struggle with file pointers and the database connection pool starts getting too busy. Usually the step from 1 to 2 servers requires large amounts of engineering to ensure everything works together correctly. SocialStack has built in clustering mechanics, ContentSync, which helps servers work together on most things automatically by default.

= How ContentSync works =

Servers in a SocialStack site cluster register themselves with an entry in your database, as an entity called ClusteredServer. This entity tracks the servers current public and private IP addresses to allow servers to communicate directly with each other via a mesh network, over a datacenter private LAN whenever possible. Depending on the host(s) you're on, private VLANs can extend beyond a particular datacenter meaning the private IPs of your servers are reachable from any of your servers worldwide.

Once a server is registered as a ClusteredServer and has started communicating with other servers, they talk about 2 main things: the status of network rooms and [[API Caching|cached entities]]. Network rooms provide an abstract mechanism for messaging a group of people (or a single person) who can be connected to any combination of servers, including one user connected to multiple servers. Cached entities, when edited on a server, triggers a message to all other present servers to tell them about the update. This allows cached objects to completely avoid hitting the database except for the server which triggered the update message in the first place.

= ID Assignment =

SocialStack has multiple methods for assigning an ID to a new object.

== Database assignment ==

The default for most entities is to use the method provided by the database: the latest database insertion ID. This has two problems:

* Not all database engines support it. MySQL is just the default - SocialStack doesn't actually rely on MySQL exclusively.
* It requires a centralised, singular counter. At high throughputs, keeping IDs from colliding becomes a bottleneck.

As a result, alternate methods are also present for the purpose of solving these problems. Most sites however won't actually encounter this as an issue.

== Block assignment ==

The high throughput ID assignment mode, also activated when an entity is set to cache, is where each server in a cluster has exclusive ownership of a block of IDs. These blocks are spaced very far apart as they are formed by combining the ClusteredServer ID with the latest rolling number for that particular server.

If you are seeing very large IDs appear in your database, it is because there are multiple entries in your ClusteredServer table (site_clusteredserver) and block assignment is active. If your site is not live yet, or there is only 1 server in your live cluster, you can truncate this table and restart the server to have it assign lower IDs if you would like it to do so.

== Low frequency block assignment ==

In this mode, clustered servers assume the object will be created at very low frequency and will self-assign IDs but will do it by discovering the latest assigned ID and adding 1. This always creates compact linear IDs and is similar to database assignment, except it does not rely on a central counter.

An example of an entity that uses low frequency block assignment is locales. Locales are edited rarely so they are cached meaning block assignment is active, but they also benefit greatly from having compact close together IDs due to the way how many SocialsStack features internally optimise localised sets. So, by setting it to low frequency block assignment the locales will end up tightly next to each other in the ID space - even if the database increment value is incorrect.

Because of this methods simplcitity ("latest plus one") - it is vulnerable to ID collisions if the object is actually created at a high frequency and the servers knowledge of the latest object is simply fractionally out of date.

ContentSync

2023-08-30T19:04:22Z

Luke: /* Low frequency block assignment */

SocialStack sites are built for high throughput out of the box, however, there always comes a scale where you need to expand on to multiple servers. You need to measure this for your site, but that scale tends to be around 5000 simultaneous users. Beyond this value, NGINX and Linux start to struggle with file pointers and the database connection pool starts getting too busy. Usually the step from 1 to 2 servers requires large amounts of engineering to ensure everything works together correctly. SocialStack has built in clustering mechanics, ContentSync, which helps servers work together on most things automatically by default.

= How ContentSync works =

Servers in a SocialStack site cluster register themselves with an entry in your database, as an entity called ClusteredServer. This entity tracks the servers current public and private IP addresses to allow servers to communicate directly with each other via a mesh network, over a datacenter private LAN whenever possible. Depending on the host(s) you're on, private VLANs can extend beyond a particular datacenter meaning the private IPs of your servers are reachable from any of your servers worldwide.

Once a server is registered as a ClusteredServer and has started communicating with other servers, they talk about 2 main things: the status of network rooms and [[API Caching|cached entities]]. Network rooms provide an abstract mechanism for messaging a group of people (or a single person) who can be connected to any combination of servers, including one user connected to multiple servers. Cached entities, when edited on a server, triggers a message to all other present servers to tell them about the update. This allows cached objects to completely avoid hitting the database except for the server which triggered the update message in the first place.

= ID Assignment =

SocialStack has multiple methods for assigning an ID to a new object.

== Database assignment ==

The default for most entities is to use the method provided by the database: the latest database insertion ID. This has two problems:

* Not all database engines support it. MySQL is just the default - SocialStack doesn't actually rely on MySQL exclusively.
* It requires a centralised, singular counter. At high throughputs, keeping IDs from colliding becomes a bottleneck.

As a result, alternate methods are also present for the purpose of solving these problems. Most sites however won't actually encounter this as an issue.

== Block assignment ==

The high throughput ID assignment mode, also activated when an entity is set to cache, is where each server in a cluster has exclusive ownership of a block of IDs. These blocks are spaced very far apart as they are formed by combining the ClusteredServer ID with the latest rolling number for that particular server.

If you are seeing very large IDs appear in your database, it is because there are multiple entries in your ClusteredServer table (site_clusteredserver) and block assignment is active. If your site is not live yet, or there is only 1 server in your live cluster, you can truncate this table and restart the server to have it assign lower IDs if you would like it to do so.

== Low frequency block assignment ==

In this mode, clustered servers assume the object will be created at very low frequency and will self-assign IDs but will do it by discovering the latest assigned ID and adding 1. This always creates compact linear IDs and is similar to database assignment, except it does not rely on a central counter.

An example of an entity that uses low frequency block assignment is locales. Locales are edited rarely so they are cached meaning block assignment is active, but they also benefit greatly from having compact close together IDs due to the way how many SocialsStack features internally optimise localised sets. So, by setting it to low frequency block assignment the locales will end up tightly next to each other in the ID space - even if the database increment value is incorrect.

ContentSync

2023-08-30T19:00:45Z

Luke: /* Database assignment */

SocialStack sites are built for high throughput out of the box, however, there always comes a scale where you need to expand on to multiple servers. You need to measure this for your site, but that scale tends to be around 5000 simultaneous users. Beyond this value, NGINX and Linux start to struggle with file pointers and the database connection pool starts getting too busy. Usually the step from 1 to 2 servers requires large amounts of engineering to ensure everything works together correctly. SocialStack has built in clustering mechanics, ContentSync, which helps servers work together on most things automatically by default.

= How ContentSync works =

Servers in a SocialStack site cluster register themselves with an entry in your database, as an entity called ClusteredServer. This entity tracks the servers current public and private IP addresses to allow servers to communicate directly with each other via a mesh network, over a datacenter private LAN whenever possible. Depending on the host(s) you're on, private VLANs can extend beyond a particular datacenter meaning the private IPs of your servers are reachable from any of your servers worldwide.

Once a server is registered as a ClusteredServer and has started communicating with other servers, they talk about 2 main things: the status of network rooms and [[API Caching|cached entities]]. Network rooms provide an abstract mechanism for messaging a group of people (or a single person) who can be connected to any combination of servers, including one user connected to multiple servers. Cached entities, when edited on a server, triggers a message to all other present servers to tell them about the update. This allows cached objects to completely avoid hitting the database except for the server which triggered the update message in the first place.

= ID Assignment =

SocialStack has multiple methods for assigning an ID to a new object.

== Database assignment ==

The default for most entities is to use the method provided by the database: the latest database insertion ID. This has two problems:

* Not all database engines support it. MySQL is just the default - SocialStack doesn't actually rely on MySQL exclusively.
* It requires a centralised, singular counter. At high throughputs, keeping IDs from colliding becomes a bottleneck.

As a result, alternate methods are also present for the purpose of solving these problems. Most sites however won't actually encounter this as an issue.

== Block assignment ==

The high throughput ID assignment mode, also activated when an entity is set to cache, is where each server in a cluster has exclusive ownership of a block of IDs. These blocks are spaced very far apart as they are formed by combining the ClusteredServer ID with the latest rolling number for that particular server.

If you are seeing very large IDs appear in your database, it is because there are multiple entries in your ClusteredServer table (site_clusteredserver) and block assignment is active. If your site is not live yet, or there is only 1 server in your live cluster, you can truncate this table and restart the server to have it assign lower IDs if you would like it to do so.

== Low frequency block assignment ==

In this mode, clustered servers assume the object will be created at very low frequency and will self-assign IDs but will do it by discovering the latest assigned ID and adding 1. This always creates compact linear IDs and is similar to database assignment, except it does not rely on a central counter.

ContentSync

2023-08-30T19:00:01Z

Luke: Created page with "SocialStack sites are built for high throughput out of the box, however, there always comes a scale where you need to expand on to multiple servers. You need to measure this f..."

API Caching

2023-08-30T18:36:41Z

Luke: /* Functionality */

It's often the case that you have at least a few [[entities]] which are accessed much more often than they are updated. Typically a site's throughput is limited by the database so the less database traffic that happens the higher that throughput will be. SocialStack has a built in caching mechanism which allows you to mark an entity as cached. This means the list of all entities of that type is obtained once during server startup and then kept up to date through the [[ContentSync|internal server mesh network]].

Caching therefore works best if you cache things accessed frequently but changed rarely. Some built in examples are site configuration, locales and the pages of your site. These are all cached by default.

= Usage =

To make an entity use the cache, simply call Cache(); from within the service constructor:

<syntaxhighlight lang="csharp">

public ThingService() {

// "Thing" entities will be cached.
Cache();

}

</syntaxhighlight>

If it is a thirdparty service and you would like to avoid editing its source to allow for easier updates, you can also call Cache(); via the Events.Service.AfterStart event.

= Functionality =

The cache reuses objects whenever possible so when you ask a caching service to get or list objects then little to no allocations actually happen. These calls also return instantaneously as the object is coming from an already loaded in-memory data structure. In the example above, if you ask "ThingService" to get object with ID #14, that returned object is returned immediately, comes from the cache and is also reused.

'''Because the object is reused, avoid changing its fields anywhere other than via Update'''.

<syntaxhighlight lang="csharp">

// private ThingService _thingService;

// This returns instantly with a reused object.
var thing14 = await _thingService.Get(context, 14);

// Because it's reused, do not edit fields!
// thing14.Name = "do not do this";

// The only correct way to update fields is via the usual update call:
thing14 = await _thingService.Update(context, thing14, (Context c, Thing updateable) => {
updateable.Name = "Updated Name";
});

</syntaxhighlight>

= Performance =

Because cached services are not depending on the database and do not allocate, they have extremely high throughput. You can use service Get hundreds of millions of times per second without risking long GC pauses (not that you would ever put this much traffic on one server though!). The JSON serialisation process also avoids as many allocations as possible and can also return more than 10 million results per second via a websocket. The limiting factor is usually the network bandwidth.

Note that the use of the websocket is important if you are expecting this level of throughput being necessary. That is because the context needs to collect the user information which usually involves the database (the user service is rarely set to being cached, but you can do that too) and this context load only occurs once on a websocket.

= ID Assignment =

Because caching a service is primarily done for performance, enabling the cache also makes a service switch ID assignment model. This is covered in more detail on the [[ContentSync|clustering mechanics page]].

API Caching

2023-08-30T18:35:36Z

Luke: Created page with "It's often the case that you have at least a few entities which are accessed much more often than they are updated. Typically a site's throughput is limited by the databas..."

It's often the case that you have at least a few [[entities]] which are accessed much more often than they are updated. Typically a site's throughput is limited by the database so the less database traffic that happens the higher that throughput will be. SocialStack has a built in caching mechanism which allows you to mark an entity as cached. This means the list of all entities of that type is obtained once during server startup and then kept up to date through the [[ContentSync|internal server mesh network]].

Caching therefore works best if you cache things accessed frequently but changed rarely. Some built in examples are site configuration, locales and the pages of your site. These are all cached by default.

= Usage =

To make an entity use the cache, simply call Cache(); from within the service constructor:

<syntaxhighlight lang="csharp">

public ThingService() {

// "Thing" entities will be cached.
Cache();

}

</syntaxhighlight>

If it is a thirdparty service and you would like to avoid editing its source to allow for easier updates, you can also call Cache(); via the Events.Service.AfterStart event.

= Functionality =

The cache reuses objects whenever possible so when you ask a caching service to get or list objects then little to no allocations actually happen. These calls also return instantaneously as the object is coming from an already loaded in-memory data structure. In the example above, if you ask "ThingService" to get object with ID #14, that returned object is returned immediately, comes from the cache and is also reused.

***Because the object is reused, avoid changing its fields anywhere other than via Update***.

<syntaxhighlight lang="csharp">

// private ThingService _thingService;

// This returns instantly with a reused object.
var thing14 = await _thingService.Get(context, 14);

// Because it's reused, do not edit fields!
// thing14.Name = "do not do this";

// The only correct way to update fields is via the usual update call:
thing14 = await _thingService.Update(context, thing14, (Context c, Thing updateable) => {
updateable.Name = "Updated Name";
});

</syntaxhighlight>

= Performance =

Because cached services are not depending on the database and do not allocate, they have extremely high throughput. You can use service Get hundreds of millions of times per second without risking long GC pauses (not that you would ever put this much traffic on one server though!). The JSON serialisation process also avoids as many allocations as possible and can also return more than 10 million results per second via a websocket. The limiting factor is usually the network bandwidth.

Note that the use of the websocket is important if you are expecting this level of throughput being necessary. That is because the context needs to collect the user information which usually involves the database (the user service is rarely set to being cached, but you can do that too) and this context load only occurs once on a websocket.

= ID Assignment =

Because caching a service is primarily done for performance, enabling the cache also makes a service switch ID assignment model. This is covered in more detail on the [[ContentSync|clustering mechanics page]].

Using npm packages

2023-08-30T16:34:17Z

Luke: Created page with "SocialStack puts performance first out of the box, with frontend javascript .js builds compiling near instantly on edits and being often less than 60kb when minified. SocialSt..."

SocialStack puts performance first out of the box, with frontend javascript .js builds compiling near instantly on edits and being often less than 60kb when minified. SocialStack is also used to make native mobile app UIs which have a strong requirement of no remote dependencies and that is not a guarantee from npm packages. Many npm packages also only compile properly through webpack. This is often because the package specifically has configuration for webpack builds. As a result, webpack is largely unavoidable for building projects containing npm packages.

Webpack builds are typically large and require usually very custom project specific configuration to tune it to the modules and build preferences you are using. For these reasons, SocialStack does not include webpack by default. To make use of npm modules, you'll need to create an empty npm project with your prefered build chain in it, with only one small note: you'll need to setup react (specifically it's actually preact) as a remote alias. This is because preact is included directly inline in the HTML of the page rather than in any of the js builds such that preact can start warming the DOM whilst the rest of the page is still downloading.

Tips:

* Use a watcher based setup such that you can save files and then wait for your js to recompile - it's a lot faster than it compiling from scratch.

* Put your build output into the UI/Source directory. If it is small, it can just go directly in there and be bundled in with the rest of your UI. If it is large, you should put it in a folder called static. Contents of static directories are ignored by the built in js build chain but are still treated as part of the UI and copied automatically by the socialstack deployment helpers. You can then add its relative URL as a script tag in to the HtmlService site configuration. /pack/static/ is the effective location of the UI/Source directory. For example, UI/Source/Npm/static/hello.js is present at /pack/static/npm/static/hello.js.

Loop

2023-08-29T00:06:05Z

Luke: /* Live loops */

<Loop> is a very commonly used [https://reactjs.org/docs/react-component.html React component] installed by default in SocialStack projects. It is used to loop over lists of items typically from the API.

=Sample Usage=

Simple loop over everything of a given type (user in this case). Note that it will always be restricted by what you are permitted to see.

<syntaxhighlight lang="dart" line="1">

import Loop from 'UI/Loop';

...

<Loop over='user'>
{
user=> {
return <p>{user.username}</p>;
}
}
</Loop>

</syntaxhighlight>

Optionally you can filter your results based on some particular [[Filters|where filter]].

<syntaxhighlight lang="dart" line="1">

import Loop from 'UI/Loop';

...

<Loop over='page' filter={
{
where: {
url: {
startsWith: '/en-admin/'
}
}
}
}>
{
page => {
return <p>{page.title}</p>;
}
}
</Loop>

</syntaxhighlight>

=Live loops=

Sometimes you'll want a loop to update in realtime - whenever someone else on the site sends you a message, for example. By default any loop can update live like this, and all it takes is the live prop:

<syntaxhighlight lang="dart" line="1">
import Loop from 'UI/Loop';

...

<Loop over='user' live>
{
user=> {
return <p>{user.username}</p>;
}
}
</Loop>

</syntaxhighlight>

Try creating a new user account - you'll see it appear on this loop without needing to do anything else, again assuming that you are permitted to see the content.

If you would like a callback whenever a new object is added via the live mechanism, you can use the onLiveCreate prop on your Loop.

=Sorting=

Filters support an order clause - see the [[Filters|page on filters]] for more information here.

=Pagination=

A loop can be automatically paginated using the UI/Paginator component. This is done using the paged prop:

<syntaxhighlight lang="dart" line="1">
import Loop from 'UI/Loop';

...

<Loop over='user' paged={10}>
{
user=> {
return <p>{user.username}</p>;
}
}
</Loop>

</syntaxhighlight>

Paged itself has multiple configuration options, including the ability to specify which pagination component to use. At its basics though, just setting it to the number of items to display per page will get things moving.

For advanced usage, the available configuration options are like so:

<syntaxhighlight lang="dart" line="1">
import Loop from 'UI/Loop';

...

<Loop paged={{
pageSize: 10,
showInput: false,
showSummary: false,
maxLinks: 3,
module: 'UI/MyCustomPaginator'
}} ...>
</syntaxhighlight>

The module option should be used carefully to avoid inconsistency (i.e. a need to specify it on every loop would potentially arise). Instead, it's recommended to uninstall the default UI/Paginator and create a custom component of the same name.

If you'd like to restrict the result count but without a paginator visible, you can directly set pageSize and pageIndex into the filter. This is effectively what the paged prop does, along with displaying its additional UI.

<syntaxhighlight lang="dart" line="1">
import Loop from 'UI/Loop';

...

<Loop filter={{
pageSize: 10,
pageIndex: 0 // optional
}} ...>
</syntaxhighlight>

=Includes=

[[Includes]] are a mechanism in SocialStack for obtaining related data in the same API call. They are a feature of the [[public API]] but are exposed via Loop too:

<syntaxhighlight lang="js">
import Loop from 'UI/Loop';

...

<Loop over='page' includes={['creatorUser']}>
{page => {
return <div>
The page "{page.title}" was created by {page.creatorUser.username}
</div>;
}}
</Loop>
</syntaxhighlight>

= Looping over just included items =

If you'd like to have live includes or loop over items which are "on" something else, then you can use the on filter:

<syntaxhighlight lang="js">
import Loop from 'UI/Loop';

...

<Loop over='tag' filter={{on: {type: 'Page', id: 4}}}>
{tag => {
return {tag.name};
}}
</Loop>
</syntaxhighlight>

Unlike regular includes, these loops support going live too.

Presence

2023-08-16T16:44:25Z

Luke:

It can often be useful to track online status of users on a website. By default, SocialStack sites use authenticated websockets which are typically the foundation of all presence checking as you can identify when they disconnect as well. There are some caveats to this which it helps to be aware of as it may affect your design goals and those are noted below too.

= Websocket based presence =

The simplest way to handle user presence is by [[Events|handling]] the following events:

* Events.WebSocket.AfterLogin

* Events.WebSocket.AfterLogout

These events are triggered whenever a user account has authenticated via the websocket. If you don't care about user accounts and are more interested in the raw number of sessions, anonymous users included, use the underlying disconnect and connect events instead:

* Events.WebSocket.Connected

* Events.WebSocket.Disconnected

If a user is authenticated, it is often the case that Connected triggers immediately before AfterLogin does, and similarly, AfterLogout triggers immediately before Disconnected.

= Active logins =

There is nothing stopping someone opening multiple tabs of your website across multiple devices. Indeed this is very common with people frequently switching between mobile devices and desktops. A user is therefore not necessarily present or not - they can be present in 3 places, and all 3 sessions must end before their overall online state can change. If this sounds like a situation you need to handle, consider installing the ActiveLogins module which does it for you and keeps a user OnlineState field up to date.

<syntaxhighlight lang="bash">
socialstack install Api/ActiveLogins
</syntaxhighlight>

This module creates a personal "network room" which keeps track of a users presence from multiple devices, potentially also across multiple servers if you have a larger cluster too. The current state of the personal network room is tracked via "ActiveLoginHistory" records which can be used to identify a user logging in and out over time. These login audit trails are also often necessary on sites where unauthorised access is a concern due to the potential for privacy or property breaches.

= Web presence caveats =

Your website is likely to be left open in a tab for days or longer as well. In Chrome, an idle tab can actually keep the websocket connection open for a while (days) too. This means a user is "present" because the tab is open, but they are not active - often because the tab is one of dozens. If user activity is important to you, it is suggested to send a websocket message indicating activity and handle that directly. If you don't receive such an activity message, then you can mark the websocket connection as "away".

Presence

2023-08-16T16:34:59Z

Luke: Created page with "It can often be useful to track online status of users on a website. By default, SocialStack sites use authenticated websockets which are typically the foundation of all prese..."

It can often be useful to track online status of users on a website. By default, SocialStack sites use authenticated websockets which are typically the foundation of all presense checking, as you can identify when they disconnect as well. There are some caveats to this which it helps to be aware of as it may affect your design goals and those are noted below too.

= Websocket based presence =

The simplest way to handle user presence is by [[Events|handling]] the following events:

* Events.WebSocket.AfterLogin

* Events.WebSocket.AfterLogout

These events are triggered whenever a user account has authenticated via the websocket. If you don't care about user accounts and are more interested in the raw number of sessions, anonymous users included, use the underlying disconnect and connect events instead:

* Events.WebSocket.Connected

* Events.WebSocket.Disconnected

If a user is authenticated, it is often the case that Connected triggers immediately before AfterLogin does, and similarly, AfterLogout triggers immediately before Disconnected.

= Active logins =

There is nothing stopping someone opening multiple tabs of your website across multiple devices. Indeed this is very common with people frequently switching between mobile devices and desktops. A user is therefore not necessarily present or not - they can be present in 3 places, and all 3 sessions must end before their overall online state can change. If this sounds like a situation you need to handle, consider installing the ActiveLogins module which does it for you and keeps a user OnlineState field up to date.

<syntaxhighlight lang="bash">
socialstack install Api/ActiveLogins
</syntaxhighlight>

This module creates a personal "network room" which keeps track of a users presence from multiple devices, potentially also across multiple servers if you have a larger cluster too. The current state of the personal network room is tracked via "ActiveLoginHistory" records which can be used to identify a user logging in and out over time. These login audit trails are also often necessary on sites where unauthorised access is a concern due to the potential for privacy or property breaches.

= Web presence caveats =

Your website is likely to be left open in a tab for days or longer as well. In Chrome, an idle tab can actually keep the websocket connection open for a while (days) too. This means a user is "present" because the tab is open, but they are not active - often because the tab is one of dozens. If user activity is important to you, it is suggested to send a websocket message indicating activity and handle that directly. If you don't receive such an activity message, then you can mark the websocket connection as "away".

Raw Database Queries

2023-08-03T19:01:14Z

Luke: /* Getting one result */

SocialStack like many platforms suggests using its general purpose API's instead of going under the hood to the database level to execute queries. This is because SocialStack isn't strictly tied to any particular database engine (MySQL being just the default one) and as a result for code to be easier to share the general use API's are always recommended. However though there are certainly times when you need an escape hatch and being able to just run a query can be useful.

= MySQL Environment =

SocialStack installs the [https://dev.mysql.com/doc/connector-net/en/connector-net-installation-binary-nuget.html Oracle MySQL C# library] via nuget which you can directly use to run MySqlCommand objects at the rawest level with its API. SocialStack also provides some abstractions to help catch common cases too which are available via the MySQLDatabaseService. You can access this service the same way as [[Services|any other service]] which is to say you can either use dependency injection or Services.Get like so:

<syntaxhighlight lang="csharp">
using Api.Database;

...

var database = Services.Get<MySQLDatabaseService>();
</syntaxhighlight>

= Running a raw query =

As SocialStack can't guess what kind of result fields will be in your query results, there are a few different convenience methods for running queries on the database.

== Executing a command with no results ==

If you have no results and only want a true/ false if the query succeeded, use database.Run like so:

<syntaxhighlight lang="csharp">
using Api.Database;

...

var database = Services.Get<MySQLDatabaseService>();

var succeeded = await database.Run("UPDATE ...");
</syntaxhighlight>

These are sometimes used from [[Automations]] to do bulk database maintenance on a schedule.

== Getting one result ==

If you'd like just one result row, use database.Select:

<syntaxhighlight lang="csharp">

using Api.Database;

...
var query = Query.Select(typeof(UserCountResult), "site_user"); // Give a hint of which main table you are using.
query.SetRawQuery("SELECT MyStoredFunction() as Count, Id from site_user where Id=@id"); // Set the query.

// Get the result for user with ID 14:
var userCounts = await database.Select<UserCountResult, uint>(context, query, typeof(UserCountResult), 14);
</syntaxhighlight>

The Select method supports one parameter called ''@id'' and its value is of the type you specify (uint in the example above). It is used with @id in your raw query and can also be ignored - you don't have to use it if you don't need it, in which case, just pass a 0 as its value.

If you need additional parameters, it is suggested to use MySqlCommand directly instead. See below for more details on that.

Elsewhere you will need a class which describes the result row. In the example above, it is the class called UserCountResult, and it has at least 2 fields in the select statement so it would be at least like this:

<syntaxhighlight lang="csharp">

public class UserCountResult{
public int Id;
public int Count;
}

</syntaxhighlight>

== Getting one or more results ==

A list of multiple results can be obtained using database.List:

<syntaxhighlight lang="csharp">

using Api.Database;

...
var query = Query.Select(typeof(UserCountResult), "site_user"); // Give a hint of which main table you are using.
query.SetRawQuery("SELECT count(*) as Count, Id from site_user"); // Set the query.

// Get the result(s):
var userCounts = await database.List<UserCountResult>(context, query, typeof(UserCountResult));
</syntaxhighlight>

Elsewhere you will need a class which describes the result row. In the example above, it is the class called UserCountResult, and it has at least 2 fields in the select statement so it would be at least like this:

<syntaxhighlight lang="csharp">

public class UserCountResult{
public int Id;
public int Count;
}

</syntaxhighlight>

== Using MySqlCommand directly ==

The main thing you'll want in order to use the underlying Oracle MySqlCommand object is a database connection instance. You can get this connection via MySQLDatabaseService's GetConnection() method:

<syntaxhighlight lang="csharp">
using var connection = db.GetConnection();
await connection.OpenAsync();
var cmd = new MySqlCommand("SELECT * ..", connection);

// cmd.Parameters.Add - see Oracle's documentation for more on those.

if(await cmd.ExecuteNonQueryAsync() > 0) {
// Success!
}

</syntaxhighlight>

This of course gives you more options but you'll need to map any results to an object yourself.

Raw Database Queries

2023-08-03T19:00:57Z

Luke: /* Getting one or more results */

SocialStack like many platforms suggests using its general purpose API's instead of going under the hood to the database level to execute queries. This is because SocialStack isn't strictly tied to any particular database engine (MySQL being just the default one) and as a result for code to be easier to share the general use API's are always recommended. However though there are certainly times when you need an escape hatch and being able to just run a query can be useful.

= MySQL Environment =

SocialStack installs the [https://dev.mysql.com/doc/connector-net/en/connector-net-installation-binary-nuget.html Oracle MySQL C# library] via nuget which you can directly use to run MySqlCommand objects at the rawest level with its API. SocialStack also provides some abstractions to help catch common cases too which are available via the MySQLDatabaseService. You can access this service the same way as [[Services|any other service]] which is to say you can either use dependency injection or Services.Get like so:

<syntaxhighlight lang="csharp">
using Api.Database;

...

var database = Services.Get<MySQLDatabaseService>();
</syntaxhighlight>

= Running a raw query =

As SocialStack can't guess what kind of result fields will be in your query results, there are a few different convenience methods for running queries on the database.

== Executing a command with no results ==

If you have no results and only want a true/ false if the query succeeded, use database.Run like so:

<syntaxhighlight lang="csharp">
using Api.Database;

...

var database = Services.Get<MySQLDatabaseService>();

var succeeded = await database.Run("UPDATE ...");
</syntaxhighlight>

These are sometimes used from [[Automations]] to do bulk database maintenance on a schedule.

== Getting one result ==

If you'd like just one result row, use database.Select:

<syntaxhighlight lang="csharp">

using Api.Database;

...
var query = Query.Select(typeof(User), "site_user"); // Give a hint of which main table you are using.
query.SetRawQuery("SELECT MyStoredFunction() as Count, Id from site_user where Id=@id"); // Set the query.

// Get the result for user with ID 14:
var userCounts = await database.Select<UserCountResult, uint>(context, query, typeof(UserCountResult), 14);
</syntaxhighlight>

The Select method supports one parameter called ''@id'' and its value is of the type you specify (uint in the example above). It is used with @id in your raw query and can also be ignored - you don't have to use it if you don't need it, in which case, just pass a 0 as its value.

If you need additional parameters, it is suggested to use MySqlCommand directly instead. See below for more details on that.

Elsewhere you will need a class which describes the result row. In the example above, it is the class called UserCountResult, and it has at least 2 fields in the select statement so it would be at least like this:

<syntaxhighlight lang="csharp">

public class UserCountResult{
public int Id;
public int Count;
}

</syntaxhighlight>

== Getting one or more results ==

A list of multiple results can be obtained using database.List:

<syntaxhighlight lang="csharp">

using Api.Database;

...
var query = Query.Select(typeof(UserCountResult), "site_user"); // Give a hint of which main table you are using.
query.SetRawQuery("SELECT count(*) as Count, Id from site_user"); // Set the query.

// Get the result(s):
var userCounts = await database.List<UserCountResult>(context, query, typeof(UserCountResult));
</syntaxhighlight>

Elsewhere you will need a class which describes the result row. In the example above, it is the class called UserCountResult, and it has at least 2 fields in the select statement so it would be at least like this:

<syntaxhighlight lang="csharp">

public class UserCountResult{
public int Id;
public int Count;
}

</syntaxhighlight>

== Using MySqlCommand directly ==

The main thing you'll want in order to use the underlying Oracle MySqlCommand object is a database connection instance. You can get this connection via MySQLDatabaseService's GetConnection() method:

<syntaxhighlight lang="csharp">
using var connection = db.GetConnection();
await connection.OpenAsync();
var cmd = new MySqlCommand("SELECT * ..", connection);

// cmd.Parameters.Add - see Oracle's documentation for more on those.

if(await cmd.ExecuteNonQueryAsync() > 0) {
// Success!
}

</syntaxhighlight>

This of course gives you more options but you'll need to map any results to an object yourself.

Raw Database Queries

2023-08-03T18:51:36Z

Luke: /* Getting one result */

SocialStack like many platforms suggests using its general purpose API's instead of going under the hood to the database level to execute queries. This is because SocialStack isn't strictly tied to any particular database engine (MySQL being just the default one) and as a result for code to be easier to share the general use API's are always recommended. However though there are certainly times when you need an escape hatch and being able to just run a query can be useful.

= MySQL Environment =

SocialStack installs the [https://dev.mysql.com/doc/connector-net/en/connector-net-installation-binary-nuget.html Oracle MySQL C# library] via nuget which you can directly use to run MySqlCommand objects at the rawest level with its API. SocialStack also provides some abstractions to help catch common cases too which are available via the MySQLDatabaseService. You can access this service the same way as [[Services|any other service]] which is to say you can either use dependency injection or Services.Get like so:

<syntaxhighlight lang="csharp">
using Api.Database;

...

var database = Services.Get<MySQLDatabaseService>();
</syntaxhighlight>

= Running a raw query =

As SocialStack can't guess what kind of result fields will be in your query results, there are a few different convenience methods for running queries on the database.

== Executing a command with no results ==

If you have no results and only want a true/ false if the query succeeded, use database.Run like so:

<syntaxhighlight lang="csharp">
using Api.Database;

...

var database = Services.Get<MySQLDatabaseService>();

var succeeded = await database.Run("UPDATE ...");
</syntaxhighlight>

These are sometimes used from [[Automations]] to do bulk database maintenance on a schedule.

== Getting one result ==

If you'd like just one result row, use database.Select:

<syntaxhighlight lang="csharp">

using Api.Database;

...
var query = Query.Select(typeof(User), "site_user"); // Give a hint of which main table you are using.
query.SetRawQuery("SELECT MyStoredFunction() as Count, Id from site_user where Id=@id"); // Set the query.

// Get the result for user with ID 14:
var userCounts = await database.Select<UserCountResult, uint>(context, query, typeof(UserCountResult), 14);
</syntaxhighlight>

The Select method supports one parameter called ''@id'' and its value is of the type you specify (uint in the example above). It is used with @id in your raw query and can also be ignored - you don't have to use it if you don't need it, in which case, just pass a 0 as its value.

If you need additional parameters, it is suggested to use MySqlCommand directly instead. See below for more details on that.

Elsewhere you will need a class which describes the result row. In the example above, it is the class called UserCountResult, and it has at least 2 fields in the select statement so it would be at least like this:

<syntaxhighlight lang="csharp">

public class UserCountResult{
public int Id;
public int Count;
}

</syntaxhighlight>

== Getting one or more results ==

A list of multiple results can be obtained using database.List:

<syntaxhighlight lang="csharp">

using Api.Database;

...
var query = Query.Select(typeof(User), "site_user"); // Give a hint of which main table you are using.
query.SetRawQuery("SELECT count(*) as Count, Id from site_user"); // Set the query.

// Get the result(s):
var userCounts = await database.List<UserCountResult>(context, query, typeof(UserCountResult));
</syntaxhighlight>

Elsewhere you will need a class which describes the result row. In the example above, it is the class called UserCountResult, and it has at least 2 fields in the select statement so it would be at least like this:

<syntaxhighlight lang="csharp">

public class UserCountResult{
public int Id;
public int Count;
}

</syntaxhighlight>

== Using MySqlCommand directly ==

The main thing you'll want in order to use the underlying Oracle MySqlCommand object is a database connection instance. You can get this connection via MySQLDatabaseService's GetConnection() method:

<syntaxhighlight lang="csharp">
using var connection = db.GetConnection();
await connection.OpenAsync();
var cmd = new MySqlCommand("SELECT * ..", connection);

// cmd.Parameters.Add - see Oracle's documentation for more on those.

if(await cmd.ExecuteNonQueryAsync() > 0) {
// Success!
}

</syntaxhighlight>

This of course gives you more options but you'll need to map any results to an object yourself.

Raw Database Queries

2023-08-03T18:51:14Z

Luke: /* Getting one result */

SocialStack like many platforms suggests using its general purpose API's instead of going under the hood to the database level to execute queries. This is because SocialStack isn't strictly tied to any particular database engine (MySQL being just the default one) and as a result for code to be easier to share the general use API's are always recommended. However though there are certainly times when you need an escape hatch and being able to just run a query can be useful.

= MySQL Environment =

SocialStack installs the [https://dev.mysql.com/doc/connector-net/en/connector-net-installation-binary-nuget.html Oracle MySQL C# library] via nuget which you can directly use to run MySqlCommand objects at the rawest level with its API. SocialStack also provides some abstractions to help catch common cases too which are available via the MySQLDatabaseService. You can access this service the same way as [[Services|any other service]] which is to say you can either use dependency injection or Services.Get like so:

<syntaxhighlight lang="csharp">
using Api.Database;

...

var database = Services.Get<MySQLDatabaseService>();
</syntaxhighlight>

= Running a raw query =

As SocialStack can't guess what kind of result fields will be in your query results, there are a few different convenience methods for running queries on the database.

== Executing a command with no results ==

If you have no results and only want a true/ false if the query succeeded, use database.Run like so:

<syntaxhighlight lang="csharp">
using Api.Database;

...

var database = Services.Get<MySQLDatabaseService>();

var succeeded = await database.Run("UPDATE ...");
</syntaxhighlight>

These are sometimes used from [[Automations]] to do bulk database maintenance on a schedule.

== Getting one result ==

If you'd like just one result row, use database.Select:

<syntaxhighlight lang="csharp">

using Api.Database;

...
var query = Query.Select(typeof(User), "site_user"); // Give a hint of which main table you are using.
query.SetRawQuery("SELECT MyStoredFunction() as Count, Id from site_user where Id=@id"); // Set the query.

// Get the result for user with ID 14:
var userCounts = await database.Select<UserCountResult, uint>(context, query, typeof(UserCountResult), 14);
</syntaxhighlight>

The Select method supports one parameter called ''@id'' and its value is of the type you specify (uint in the example above). It is used with @id in your raw query and can also be ignored - you don't have to use it if you don't need it, in which case, just pass a 0 as its value.

If you need additional parameters, it is suggested to use MySqlCommand directly instead.

Elsewhere you will need a class which describes the result row. In the example above, it is the class called UserCountResult, and it has at least 2 fields in the select statement so it would be at least like this:

<syntaxhighlight lang="csharp">

public class UserCountResult{
public int Id;
public int Count;
}

</syntaxhighlight>

== Getting one or more results ==

A list of multiple results can be obtained using database.List:

<syntaxhighlight lang="csharp">

using Api.Database;

...
var query = Query.Select(typeof(User), "site_user"); // Give a hint of which main table you are using.
query.SetRawQuery("SELECT count(*) as Count, Id from site_user"); // Set the query.

// Get the result(s):
var userCounts = await database.List<UserCountResult>(context, query, typeof(UserCountResult));
</syntaxhighlight>

Elsewhere you will need a class which describes the result row. In the example above, it is the class called UserCountResult, and it has at least 2 fields in the select statement so it would be at least like this:

<syntaxhighlight lang="csharp">

public class UserCountResult{
public int Id;
public int Count;
}

</syntaxhighlight>

== Using MySqlCommand directly ==

The main thing you'll want in order to use the underlying Oracle MySqlCommand object is a database connection instance. You can get this connection via MySQLDatabaseService's GetConnection() method:

<syntaxhighlight lang="csharp">
using var connection = db.GetConnection();
await connection.OpenAsync();
var cmd = new MySqlCommand("SELECT * ..", connection);

// cmd.Parameters.Add - see Oracle's documentation for more on those.

if(await cmd.ExecuteNonQueryAsync() > 0) {
// Success!
}

</syntaxhighlight>

This of course gives you more options but you'll need to map any results to an object yourself.

Raw Database Queries

2023-08-03T18:50:19Z

Luke:

SocialStack like many platforms suggests using its general purpose API's instead of going under the hood to the database level to execute queries. This is because SocialStack isn't strictly tied to any particular database engine (MySQL being just the default one) and as a result for code to be easier to share the general use API's are always recommended. However though there are certainly times when you need an escape hatch and being able to just run a query can be useful.

= MySQL Environment =

SocialStack installs the [https://dev.mysql.com/doc/connector-net/en/connector-net-installation-binary-nuget.html Oracle MySQL C# library] via nuget which you can directly use to run MySqlCommand objects at the rawest level with its API. SocialStack also provides some abstractions to help catch common cases too which are available via the MySQLDatabaseService. You can access this service the same way as [[Services|any other service]] which is to say you can either use dependency injection or Services.Get like so:

<syntaxhighlight lang="csharp">
using Api.Database;

...

var database = Services.Get<MySQLDatabaseService>();
</syntaxhighlight>

= Running a raw query =

As SocialStack can't guess what kind of result fields will be in your query results, there are a few different convenience methods for running queries on the database.

== Executing a command with no results ==

If you have no results and only want a true/ false if the query succeeded, use database.Run like so:

<syntaxhighlight lang="csharp">
using Api.Database;

...

var database = Services.Get<MySQLDatabaseService>();

var succeeded = await database.Run("UPDATE ...");
</syntaxhighlight>

These are sometimes used from [[Automations]] to do bulk database maintenance on a schedule.

== Getting one result ==

If you'd like just one result row, use database.Select:

<syntaxhighlight lang="csharp">

using Api.Database;

...
var query = Query.Select(typeof(User), "site_user"); // Give a hint of which main table you are using.
query.SetRawQuery("SELECT MyStoredFunction() as Count, Id from site_user where Id=@id"); // Set the query.

// Get the result for user with ID 14:
var userCounts = await database.Select<UserCountResult, uint>(context, query, typeof(UserCountResult), 14);
</syntaxhighlight>

The Select method supports one parameter called ID and its value is of the type you specify (uint in the example above). It is used with @id in your raw query and can also be ignored - you don't have to use it if you don't need it, in which case, just pass a 0 as its value.

If you need additional args, it is suggested to use MySqlCommand directly instead.

Elsewhere you will need a class which describes the result row. In the example above, it is the class called UserCountResult, and it has at least 2 fields in the select statement so it would be at least like this:

<syntaxhighlight lang="csharp">

public class UserCountResult{
public int Id;
public int Count;
}

</syntaxhighlight>

== Getting one or more results ==

A list of multiple results can be obtained using database.List:

<syntaxhighlight lang="csharp">

using Api.Database;

...
var query = Query.Select(typeof(User), "site_user"); // Give a hint of which main table you are using.
query.SetRawQuery("SELECT count(*) as Count, Id from site_user"); // Set the query.

// Get the result(s):
var userCounts = await database.List<UserCountResult>(context, query, typeof(UserCountResult));
</syntaxhighlight>

Elsewhere you will need a class which describes the result row. In the example above, it is the class called UserCountResult, and it has at least 2 fields in the select statement so it would be at least like this:

<syntaxhighlight lang="csharp">

public class UserCountResult{
public int Id;
public int Count;
}

</syntaxhighlight>

== Using MySqlCommand directly ==

The main thing you'll want in order to use the underlying Oracle MySqlCommand object is a database connection instance. You can get this connection via MySQLDatabaseService's GetConnection() method:

<syntaxhighlight lang="csharp">
using var connection = db.GetConnection();
await connection.OpenAsync();
var cmd = new MySqlCommand("SELECT * ..", connection);

// cmd.Parameters.Add - see Oracle's documentation for more on those.

if(await cmd.ExecuteNonQueryAsync() > 0) {
// Success!
}

</syntaxhighlight>

This of course gives you more options but you'll need to map any results to an object yourself.

Raw Database Queries

2023-08-03T18:34:46Z

Luke: Created page with "SocialStack like many platforms suggests using its general purpose API's instead of going under the hood to the database level to execute queries. This is because SocialStack..."

Includes

2023-06-15T12:44:30Z

Luke: /* Dynamic Includes */

Includes are a mechanism in SocialStack which allow you to request additional content when obtaining an entity (or a list of entities) from the API. For example, you have a loop of things and would like to also display the name of the user who created each one. Includes are not case sensitive.

=Frontend Usage=

Typically includes are used from either Loop or Content:

<syntaxhighlight lang="dart" line="1">
import Loop from 'UI/Loop';

...

<Loop over='page/list' includes={['creatorUser']}>
{page => {
return <div>
The page "{page.title}" was created by {page.creatorUser.username}
</div>;
}}
</Loop>

</syntaxhighlight>

<syntaxhighlight lang="dart" line="1">
import Content from 'UI/Content';

...

<Content type='page' id={1} includes={['creatorUser']}>
{page => {
if(!page){
// Just an example. The page might also not exist. See <Content> usage for more info.
return 'Loading..';
}

return <div>
The page "{page.title}" was created by {page.creatorUser.username}
</div>;
}}
</Content>

</syntaxhighlight>

If you aren't in the React render scope, you can specify includes via a webRequest as well:

<syntaxhighlight lang="js" line="1">
webRequest('page/1', null, {includes: ['creatorUser']});
</syntaxhighlight>

In some rare cases you may need a [[forms|<Form>]] response to include something custom. By default edit and create include * with their response, but they don't know about any nested includes that you may need. Form has a requestOpts prop which gives you the ability to set raw values on the webRequest that it makes, allowing us to essentially do the same as above but with a form instead:

<syntaxhighlight lang="js" line="1">
<Form action='page' requestOpts={{includes: ['*', 'creatorUser.tags']}}>
..
</syntaxhighlight>

=API Usage=

The frontend is actually just adding any includes on as a GET parameter, like so. If you have more than one, they are comma separated:

https://www.example.com/v1/page/1?includes=creatorUser

=Nested Includes=

You will often have situations where you want to include things on the included objects as well. This is done with a dot:

<syntaxhighlight lang="js" line="1">
['creatorUser', 'creatorUser.tags']
</syntaxhighlight>

Nesting has no depth limit - you can use 3+ layers deep if you need to. Because you're spelling out each depth, there is no risk of recursion or cyclical behaviour either - you can include the creatorUser of a creatorUser, even if they are the same object. (And yes, Users do have a creatorUser as well - it can be used to identify if a user account was created by an admin for example).

=Wildcards=

You can wildcard include to show all available current level includes, and this is available nested as well:

<syntaxhighlight lang="js" line="1">
['*', 'creatorUser.*']
</syntaxhighlight>

Note that the wildcard is only supported as the last field (*.creatorUser is not available for example, as not everything necessarily supports the named field you want).

Wildcards also do not show explicit includes (ones where you must explicitly list the field name).

=Making something includable=

Includable things are either singular objects (like the creator user - a piece of content only ever has 1 of those), or a list of things.

==Single objects==

To make a single object, you'll need to create a "virtual field" on your C# type:

<syntaxhighlight lang="csharp" line="1">
[HasVirtualField("OtherTypeName", typeof(OtherTypeName), "OtherTypeNameId")]
public partial class MyCustomType : VersionedContent<uint>
{
public uint OtherTypeNameId;
}
</syntaxhighlight>

You can declare as many virtual fields as you need, but essentially you define:

* The virtual fields name (this is the text which goes inside the includes array)
* The type of thing that will be included. This must always be a Content type.
* The name of the field where the ID for your included thing will come from.

For example, this is how creatorUser is actually defined:

<syntaxhighlight lang="csharp" line="1">
[HasVirtualField("CreatorUser", typeof(User), "UserId")]
</syntaxhighlight>

"Create an includable field called CreatorUser, which will be a User type, and the ID of the user to include comes from the UserId field".

=== On the admin panel ===

A virtual field declared in this way will cause a convenient dropdown selector to appear for the ID field on the admin panel (UI/ContentSelect). Sometimes though your included type may have thousands or millions of rows, so a dropdown is not appropriate and instead a search first mechanism is required. You can turn on search mode like so:

<syntaxhighlight lang="csharp" line="1">

[Data("titleField", "Name")] /* The field name to use as the title in the results list (or in the dropdown) */
[Data("search", "true")] /* Use search mode instead of a dropdown of all */
public uint OtherTypeNameId;

</syntaxhighlight>

==Lists==

To include a list of things on a type (for example, a list of answers on a poll), you'll need to mark the C# type as listable:

<syntaxhighlight lang="csharp" line="1">
[ListAs("MyCustomTypes")]
[HasVirtualField("OtherTypeName", typeof(OtherTypeName), "OtherTypeNameId")]
public partial class MyCustomType : VersionedContent<uint>
{
public uint OtherTypeNameId;

public string Name;
}
</syntaxhighlight>

You can use multiple ListAs declarations. Users is a good example of a use case for this - there is a list of permitted users on other types, but also you might want a list of members etc.

=== On the admin panel ===

By default a ListAs field will appear as a content selector on the admin panel. This content selector uses a searchbar to find the content you're after and it will default to using the [[Content_Type_Meta_Fields|meta title field]] of the thing being marked with ListAs. Meta title fields take a guess at an appropriate field to use if they are not explicitly marked and it will ultimately default to searching by a field called "Name" otherwise.

For example, if you have the MyCustomType above, it has a field called Name so the search bar that appears will use that. If it did not have a field called Name, it will also attempt to use fields like "Title" and similar if they exist, based on the rules of the [[Content_Type_Meta_Fields|meta title field]]. If you want some other field to be searched by, mark it as the meta title field instead:

<syntaxhighlight lang="csharp" line="1">
[Meta("title")]
public string Registration;
</syntaxhighlight>

With that, the admin UI will then search by this field called Registration.

===Explicit Lists===

There is a special consideration for listing though: by default, your ListAs field will be available to get included on anything. This is great for generic things like tags or categories, but the chances are you probably have something specific in mind. You can just ignore it of course, but the field will list on your admin panel and cause some unwanted clutter.

So, to clamp down where your ListAs field actually appears, use the explicit and implicit modes:

<syntaxhighlight lang="csharp" line="1">
[ListAs("MyCustomTypes", Explicit=true)]
</syntaxhighlight>

Explicit means the field name must be explicitly used - it won't appear when the wildcard is used. You can, for example, do this for your includes array:

<syntaxhighlight lang="js" line="1">
['*', 'MyCustomTypes']
</syntaxhighlight>

The wildcard is what the admin panel uses, so an explicit include will no longer appear there. So, we now have an includable field that exists but appears nowhere by default. We can then make it appear on specific types with ImplicitFor:

<syntaxhighlight lang="csharp" line="1">
[ListAs("MyCustomTypes", Explicit=true)]
[ImplicitFor("MyCustomTypes", typeof(ParentTypeToListOn))]
</syntaxhighlight>

You can list as many ImplicitFor attributes as you need. The above means the following:

* This type will be includable with the name 'MyCustomTypes'
* This 'MyCustomTypes' include will not appear on wildcard inclusions
* But it will appear on wildcard inclusions specifically for the type called 'ParentTypeToListOn'

=On: Includes without the entity=

There are situations where you'd like a list of includable things but without the thing they're included on. For example, if you want a paginated list of members. Maybe it's also live. Ideally we'd want to make use of Loop for this as it has those features, and you can do so using the On filter:

<syntaxhighlight lang="dart" line="1">
<Loop over='user' filter={{On: {type: 'MyCustomType', id: 1, map: 'UserPermits'}}}>
...
</Loop>
</syntaxhighlight>

The above loop will have the same results as having included UserPermits on MyCustomType with ID #1. This allows full access to Loop features on these specialised lists of things.

=Permissions=

Includes are a powerful way to get simple secondary and tertiary permissions - those are permissions where being able to see something relies on being able to see something else. For example, lets say you're permitted to see messages in a chat if you are a member of the chat.

We can structure this such that the user has a userPermit in the chat, with chat list/load access restricted by the custom rule <code>HasUserPermit()</code>, and we can restrict message list/load with the custom rule <code>IsIncluded()</code>. This means a message can only be displayed if you arrived at it via an include, and you can only load the chat (and thus include its messages) if you have a permit. Because includes can be deeply nested, so too can these permissions. The above section about "On" is particularly useful if you want, for example, a live loop of messages which are include restricted.

One important aspect of this is being able to create a new message with the connection to the parent chat immediately. To allow for this, "On" is supported during create calls as well.

<syntaxhighlight lang="js" line="1">
import webRequest from 'UI/Functions/WebRequest';

...

// also from <Form>'s onValues
webRequest(
"chatmessage",
{
text: 'Hello! This is a chat message',
on: {
type: 'Chat',
id: 1,
map: 'Messages' // If ChatMessage only has one ListAs, i.e. ListAs("Messages"), declaring map here is optional
}
}
);
</syntaxhighlight>

= Functional Includes =

It can be useful to run some code on a particular object whilst its JSON is generating. Whilst you can do this with the List and Load event handlers, it is generally recommended to use a functional include instead as it has less overhead. Their downside is they are global: they operate on any type. If you would like the primary URL of a piece of content, it is available as a functional include called "primaryUrl". In other words, including primaryUrl on a piece of content will provide a field called primaryUrl which would contain the page URL that content of that type is the primary content on.

As with all includes, functional includes can also be nested. You can, for example include "tags,tags.primaryUrl" - to get a list of tags on this object, plus a primaryUrl for each tag - assuming some sort of /tags/{tag.slug} page exists.

See also: PrimaryUrlValueGenerator for an example in your code.

= Dynamic Includes =

Dynamic includes are a mechanism where you can include something of a database specified type. This is useful in, for example, featured content scenario's where the thing being featured could be a product, a business or really any other kind of content. In other words: the database is specifying what the content type is, and also the ID of the content too.

To use dynamic includes, declare the field name containing the type as well as the field name containing the ID. Note that the content type field must be a string, and the ID field must be a ulong.

<syntaxhighlight lang="csharp">

// Including "item" when obtaining this featured content would also obtain the referenced type
// provided permission checks pass too of course.
[HasVirtualField("Item", "ContentType", "ContentId")]
public partial class FeaturedContent : VersionedContent<uint>
{
/// <summary>
/// The content type name, e.g. "Product".
/// </summary>
public string ContentType;

/// <summary>
/// The content ID. e.g. A product ID.
/// </summary>
public ulong ContentId;
}

</syntaxhighlight>

Dynamic includes should however be considered a feature of last resort. If you know that something will be one of two types, then it is suggested to include lists of both of those types instead. As anything can be included this way, the UI is less structured as it doesn't necessarily know for certain what it will have to display.

Globally available includes can be nested on dynamic includes too. For example, "item,item.tags" will obtain the dynamic item plus any tags on it. As functional includes such as primaryUrl are global, they are are available as well. If you use a wildcard, it will use all available implicit global includes.

Includes

2023-06-15T12:44:03Z

Luke: /* Dynamic Includes */

Includes are a mechanism in SocialStack which allow you to request additional content when obtaining an entity (or a list of entities) from the API. For example, you have a loop of things and would like to also display the name of the user who created each one. Includes are not case sensitive.

=Frontend Usage=

Typically includes are used from either Loop or Content:

<syntaxhighlight lang="dart" line="1">
import Loop from 'UI/Loop';

...

<Loop over='page/list' includes={['creatorUser']}>
{page => {
return <div>
The page "{page.title}" was created by {page.creatorUser.username}
</div>;
}}
</Loop>

</syntaxhighlight>

<syntaxhighlight lang="dart" line="1">
import Content from 'UI/Content';

...

<Content type='page' id={1} includes={['creatorUser']}>
{page => {
if(!page){
// Just an example. The page might also not exist. See <Content> usage for more info.
return 'Loading..';
}

return <div>
The page "{page.title}" was created by {page.creatorUser.username}
</div>;
}}
</Content>

</syntaxhighlight>

If you aren't in the React render scope, you can specify includes via a webRequest as well:

<syntaxhighlight lang="js" line="1">
webRequest('page/1', null, {includes: ['creatorUser']});
</syntaxhighlight>

In some rare cases you may need a [[forms|<Form>]] response to include something custom. By default edit and create include * with their response, but they don't know about any nested includes that you may need. Form has a requestOpts prop which gives you the ability to set raw values on the webRequest that it makes, allowing us to essentially do the same as above but with a form instead:

<syntaxhighlight lang="js" line="1">
<Form action='page' requestOpts={{includes: ['*', 'creatorUser.tags']}}>
..
</syntaxhighlight>

=API Usage=

The frontend is actually just adding any includes on as a GET parameter, like so. If you have more than one, they are comma separated:

https://www.example.com/v1/page/1?includes=creatorUser

=Nested Includes=

You will often have situations where you want to include things on the included objects as well. This is done with a dot:

<syntaxhighlight lang="js" line="1">
['creatorUser', 'creatorUser.tags']
</syntaxhighlight>

Nesting has no depth limit - you can use 3+ layers deep if you need to. Because you're spelling out each depth, there is no risk of recursion or cyclical behaviour either - you can include the creatorUser of a creatorUser, even if they are the same object. (And yes, Users do have a creatorUser as well - it can be used to identify if a user account was created by an admin for example).

=Wildcards=

You can wildcard include to show all available current level includes, and this is available nested as well:

<syntaxhighlight lang="js" line="1">
['*', 'creatorUser.*']
</syntaxhighlight>

Note that the wildcard is only supported as the last field (*.creatorUser is not available for example, as not everything necessarily supports the named field you want).

Wildcards also do not show explicit includes (ones where you must explicitly list the field name).

=Making something includable=

Includable things are either singular objects (like the creator user - a piece of content only ever has 1 of those), or a list of things.

==Single objects==

To make a single object, you'll need to create a "virtual field" on your C# type:

<syntaxhighlight lang="csharp" line="1">
[HasVirtualField("OtherTypeName", typeof(OtherTypeName), "OtherTypeNameId")]
public partial class MyCustomType : VersionedContent<uint>
{
public uint OtherTypeNameId;
}
</syntaxhighlight>

You can declare as many virtual fields as you need, but essentially you define:

* The virtual fields name (this is the text which goes inside the includes array)
* The type of thing that will be included. This must always be a Content type.
* The name of the field where the ID for your included thing will come from.

For example, this is how creatorUser is actually defined:

<syntaxhighlight lang="csharp" line="1">
[HasVirtualField("CreatorUser", typeof(User), "UserId")]
</syntaxhighlight>

"Create an includable field called CreatorUser, which will be a User type, and the ID of the user to include comes from the UserId field".

=== On the admin panel ===

A virtual field declared in this way will cause a convenient dropdown selector to appear for the ID field on the admin panel (UI/ContentSelect). Sometimes though your included type may have thousands or millions of rows, so a dropdown is not appropriate and instead a search first mechanism is required. You can turn on search mode like so:

<syntaxhighlight lang="csharp" line="1">

[Data("titleField", "Name")] /* The field name to use as the title in the results list (or in the dropdown) */
[Data("search", "true")] /* Use search mode instead of a dropdown of all */
public uint OtherTypeNameId;

</syntaxhighlight>

==Lists==

To include a list of things on a type (for example, a list of answers on a poll), you'll need to mark the C# type as listable:

<syntaxhighlight lang="csharp" line="1">
[ListAs("MyCustomTypes")]
[HasVirtualField("OtherTypeName", typeof(OtherTypeName), "OtherTypeNameId")]
public partial class MyCustomType : VersionedContent<uint>
{
public uint OtherTypeNameId;

public string Name;
}
</syntaxhighlight>

You can use multiple ListAs declarations. Users is a good example of a use case for this - there is a list of permitted users on other types, but also you might want a list of members etc.

=== On the admin panel ===

By default a ListAs field will appear as a content selector on the admin panel. This content selector uses a searchbar to find the content you're after and it will default to using the [[Content_Type_Meta_Fields|meta title field]] of the thing being marked with ListAs. Meta title fields take a guess at an appropriate field to use if they are not explicitly marked and it will ultimately default to searching by a field called "Name" otherwise.

For example, if you have the MyCustomType above, it has a field called Name so the search bar that appears will use that. If it did not have a field called Name, it will also attempt to use fields like "Title" and similar if they exist, based on the rules of the [[Content_Type_Meta_Fields|meta title field]]. If you want some other field to be searched by, mark it as the meta title field instead:

<syntaxhighlight lang="csharp" line="1">
[Meta("title")]
public string Registration;
</syntaxhighlight>

With that, the admin UI will then search by this field called Registration.

===Explicit Lists===

There is a special consideration for listing though: by default, your ListAs field will be available to get included on anything. This is great for generic things like tags or categories, but the chances are you probably have something specific in mind. You can just ignore it of course, but the field will list on your admin panel and cause some unwanted clutter.

So, to clamp down where your ListAs field actually appears, use the explicit and implicit modes:

<syntaxhighlight lang="csharp" line="1">
[ListAs("MyCustomTypes", Explicit=true)]
</syntaxhighlight>

Explicit means the field name must be explicitly used - it won't appear when the wildcard is used. You can, for example, do this for your includes array:

<syntaxhighlight lang="js" line="1">
['*', 'MyCustomTypes']
</syntaxhighlight>

The wildcard is what the admin panel uses, so an explicit include will no longer appear there. So, we now have an includable field that exists but appears nowhere by default. We can then make it appear on specific types with ImplicitFor:

<syntaxhighlight lang="csharp" line="1">
[ListAs("MyCustomTypes", Explicit=true)]
[ImplicitFor("MyCustomTypes", typeof(ParentTypeToListOn))]
</syntaxhighlight>

You can list as many ImplicitFor attributes as you need. The above means the following:

* This type will be includable with the name 'MyCustomTypes'
* This 'MyCustomTypes' include will not appear on wildcard inclusions
* But it will appear on wildcard inclusions specifically for the type called 'ParentTypeToListOn'

=On: Includes without the entity=

There are situations where you'd like a list of includable things but without the thing they're included on. For example, if you want a paginated list of members. Maybe it's also live. Ideally we'd want to make use of Loop for this as it has those features, and you can do so using the On filter:

<syntaxhighlight lang="dart" line="1">
<Loop over='user' filter={{On: {type: 'MyCustomType', id: 1, map: 'UserPermits'}}}>
...
</Loop>
</syntaxhighlight>

The above loop will have the same results as having included UserPermits on MyCustomType with ID #1. This allows full access to Loop features on these specialised lists of things.

=Permissions=

Includes are a powerful way to get simple secondary and tertiary permissions - those are permissions where being able to see something relies on being able to see something else. For example, lets say you're permitted to see messages in a chat if you are a member of the chat.

We can structure this such that the user has a userPermit in the chat, with chat list/load access restricted by the custom rule <code>HasUserPermit()</code>, and we can restrict message list/load with the custom rule <code>IsIncluded()</code>. This means a message can only be displayed if you arrived at it via an include, and you can only load the chat (and thus include its messages) if you have a permit. Because includes can be deeply nested, so too can these permissions. The above section about "On" is particularly useful if you want, for example, a live loop of messages which are include restricted.

One important aspect of this is being able to create a new message with the connection to the parent chat immediately. To allow for this, "On" is supported during create calls as well.

<syntaxhighlight lang="js" line="1">
import webRequest from 'UI/Functions/WebRequest';

...

// also from <Form>'s onValues
webRequest(
"chatmessage",
{
text: 'Hello! This is a chat message',
on: {
type: 'Chat',
id: 1,
map: 'Messages' // If ChatMessage only has one ListAs, i.e. ListAs("Messages"), declaring map here is optional
}
}
);
</syntaxhighlight>

= Functional Includes =

It can be useful to run some code on a particular object whilst its JSON is generating. Whilst you can do this with the List and Load event handlers, it is generally recommended to use a functional include instead as it has less overhead. Their downside is they are global: they operate on any type. If you would like the primary URL of a piece of content, it is available as a functional include called "primaryUrl". In other words, including primaryUrl on a piece of content will provide a field called primaryUrl which would contain the page URL that content of that type is the primary content on.

As with all includes, functional includes can also be nested. You can, for example include "tags,tags.primaryUrl" - to get a list of tags on this object, plus a primaryUrl for each tag - assuming some sort of /tags/{tag.slug} page exists.

See also: PrimaryUrlValueGenerator for an example in your code.

= Dynamic Includes =

Dynamic includes are a mechanism where you can include something of a database specified type. This is useful in, for example, featured content scenario's where the thing being featured could be a product, a business or really any other kind of content. In other words: the database is specifying what the content type is, and also the ID of the content too.

To use dynamic includes, declare the field name containing the type as well as the field name containing the ID. Note that the content type field MUST be a string, and the ID field must be a ulong.

<syntaxhighlight lang="csharp">

// Including "item" when obtaining this featured content would also obtain the referenced type
// provided permission checks pass too of course.
[HasVirtualField("Item", "ContentType", "ContentId")]
public partial class FeaturedContent : VersionedContent<uint>
{
/// <summary>
/// The content type name, e.g. "Product".
/// </summary>
public string ContentType;

/// <summary>
/// The content ID. e.g. A product ID.
/// </summary>
public ulong ContentId;
}

</syntaxhighlight>

Dynamic includes should however be considered a feature of last resort. If you know that something will be one of two types, then it is suggested to include lists of both of those types instead. As anything can be included this way, the UI is less structured as it doesn't necessarily know for certain what it will have to display.

Globally available includes can be nested on dynamic includes too. For example, "item,item.tags" will obtain the dynamic item plus any tags on it. As functional includes such as primaryUrl are global, they are are available as well. If you use a wildcard, it will use all available implicit global includes.

Includes

2023-06-15T12:42:08Z

Luke: /* Functional Includes */

Includes are a mechanism in SocialStack which allow you to request additional content when obtaining an entity (or a list of entities) from the API. For example, you have a loop of things and would like to also display the name of the user who created each one. Includes are not case sensitive.

=Frontend Usage=

Typically includes are used from either Loop or Content:

<syntaxhighlight lang="dart" line="1">
import Loop from 'UI/Loop';

...

<Loop over='page/list' includes={['creatorUser']}>
{page => {
return <div>
The page "{page.title}" was created by {page.creatorUser.username}
</div>;
}}
</Loop>

</syntaxhighlight>

<syntaxhighlight lang="dart" line="1">
import Content from 'UI/Content';

...

<Content type='page' id={1} includes={['creatorUser']}>
{page => {
if(!page){
// Just an example. The page might also not exist. See <Content> usage for more info.
return 'Loading..';
}

return <div>
The page "{page.title}" was created by {page.creatorUser.username}
</div>;
}}
</Content>

</syntaxhighlight>

If you aren't in the React render scope, you can specify includes via a webRequest as well:

<syntaxhighlight lang="js" line="1">
webRequest('page/1', null, {includes: ['creatorUser']});
</syntaxhighlight>

In some rare cases you may need a [[forms|<Form>]] response to include something custom. By default edit and create include * with their response, but they don't know about any nested includes that you may need. Form has a requestOpts prop which gives you the ability to set raw values on the webRequest that it makes, allowing us to essentially do the same as above but with a form instead:

<syntaxhighlight lang="js" line="1">
<Form action='page' requestOpts={{includes: ['*', 'creatorUser.tags']}}>
..
</syntaxhighlight>

=API Usage=

The frontend is actually just adding any includes on as a GET parameter, like so. If you have more than one, they are comma separated:

https://www.example.com/v1/page/1?includes=creatorUser

=Nested Includes=

You will often have situations where you want to include things on the included objects as well. This is done with a dot:

<syntaxhighlight lang="js" line="1">
['creatorUser', 'creatorUser.tags']
</syntaxhighlight>

Nesting has no depth limit - you can use 3+ layers deep if you need to. Because you're spelling out each depth, there is no risk of recursion or cyclical behaviour either - you can include the creatorUser of a creatorUser, even if they are the same object. (And yes, Users do have a creatorUser as well - it can be used to identify if a user account was created by an admin for example).

=Wildcards=

You can wildcard include to show all available current level includes, and this is available nested as well:

<syntaxhighlight lang="js" line="1">
['*', 'creatorUser.*']
</syntaxhighlight>

Note that the wildcard is only supported as the last field (*.creatorUser is not available for example, as not everything necessarily supports the named field you want).

Wildcards also do not show explicit includes (ones where you must explicitly list the field name).

=Making something includable=

Includable things are either singular objects (like the creator user - a piece of content only ever has 1 of those), or a list of things.

==Single objects==

To make a single object, you'll need to create a "virtual field" on your C# type:

<syntaxhighlight lang="csharp" line="1">
[HasVirtualField("OtherTypeName", typeof(OtherTypeName), "OtherTypeNameId")]
public partial class MyCustomType : VersionedContent<uint>
{
public uint OtherTypeNameId;
}
</syntaxhighlight>

You can declare as many virtual fields as you need, but essentially you define:

* The virtual fields name (this is the text which goes inside the includes array)
* The type of thing that will be included. This must always be a Content type.
* The name of the field where the ID for your included thing will come from.

For example, this is how creatorUser is actually defined:

<syntaxhighlight lang="csharp" line="1">
[HasVirtualField("CreatorUser", typeof(User), "UserId")]
</syntaxhighlight>

"Create an includable field called CreatorUser, which will be a User type, and the ID of the user to include comes from the UserId field".

=== On the admin panel ===

A virtual field declared in this way will cause a convenient dropdown selector to appear for the ID field on the admin panel (UI/ContentSelect). Sometimes though your included type may have thousands or millions of rows, so a dropdown is not appropriate and instead a search first mechanism is required. You can turn on search mode like so:

<syntaxhighlight lang="csharp" line="1">

[Data("titleField", "Name")] /* The field name to use as the title in the results list (or in the dropdown) */
[Data("search", "true")] /* Use search mode instead of a dropdown of all */
public uint OtherTypeNameId;

</syntaxhighlight>

==Lists==

To include a list of things on a type (for example, a list of answers on a poll), you'll need to mark the C# type as listable:

<syntaxhighlight lang="csharp" line="1">
[ListAs("MyCustomTypes")]
[HasVirtualField("OtherTypeName", typeof(OtherTypeName), "OtherTypeNameId")]
public partial class MyCustomType : VersionedContent<uint>
{
public uint OtherTypeNameId;

public string Name;
}
</syntaxhighlight>

You can use multiple ListAs declarations. Users is a good example of a use case for this - there is a list of permitted users on other types, but also you might want a list of members etc.

=== On the admin panel ===

By default a ListAs field will appear as a content selector on the admin panel. This content selector uses a searchbar to find the content you're after and it will default to using the [[Content_Type_Meta_Fields|meta title field]] of the thing being marked with ListAs. Meta title fields take a guess at an appropriate field to use if they are not explicitly marked and it will ultimately default to searching by a field called "Name" otherwise.

For example, if you have the MyCustomType above, it has a field called Name so the search bar that appears will use that. If it did not have a field called Name, it will also attempt to use fields like "Title" and similar if they exist, based on the rules of the [[Content_Type_Meta_Fields|meta title field]]. If you want some other field to be searched by, mark it as the meta title field instead:

<syntaxhighlight lang="csharp" line="1">
[Meta("title")]
public string Registration;
</syntaxhighlight>

With that, the admin UI will then search by this field called Registration.

===Explicit Lists===

There is a special consideration for listing though: by default, your ListAs field will be available to get included on anything. This is great for generic things like tags or categories, but the chances are you probably have something specific in mind. You can just ignore it of course, but the field will list on your admin panel and cause some unwanted clutter.

So, to clamp down where your ListAs field actually appears, use the explicit and implicit modes:

<syntaxhighlight lang="csharp" line="1">
[ListAs("MyCustomTypes", Explicit=true)]
</syntaxhighlight>

Explicit means the field name must be explicitly used - it won't appear when the wildcard is used. You can, for example, do this for your includes array:

<syntaxhighlight lang="js" line="1">
['*', 'MyCustomTypes']
</syntaxhighlight>

The wildcard is what the admin panel uses, so an explicit include will no longer appear there. So, we now have an includable field that exists but appears nowhere by default. We can then make it appear on specific types with ImplicitFor:

<syntaxhighlight lang="csharp" line="1">
[ListAs("MyCustomTypes", Explicit=true)]
[ImplicitFor("MyCustomTypes", typeof(ParentTypeToListOn))]
</syntaxhighlight>

You can list as many ImplicitFor attributes as you need. The above means the following:

* This type will be includable with the name 'MyCustomTypes'
* This 'MyCustomTypes' include will not appear on wildcard inclusions
* But it will appear on wildcard inclusions specifically for the type called 'ParentTypeToListOn'

=On: Includes without the entity=

There are situations where you'd like a list of includable things but without the thing they're included on. For example, if you want a paginated list of members. Maybe it's also live. Ideally we'd want to make use of Loop for this as it has those features, and you can do so using the On filter:

<syntaxhighlight lang="dart" line="1">
<Loop over='user' filter={{On: {type: 'MyCustomType', id: 1, map: 'UserPermits'}}}>
...
</Loop>
</syntaxhighlight>

The above loop will have the same results as having included UserPermits on MyCustomType with ID #1. This allows full access to Loop features on these specialised lists of things.

=Permissions=

Includes are a powerful way to get simple secondary and tertiary permissions - those are permissions where being able to see something relies on being able to see something else. For example, lets say you're permitted to see messages in a chat if you are a member of the chat.

We can structure this such that the user has a userPermit in the chat, with chat list/load access restricted by the custom rule <code>HasUserPermit()</code>, and we can restrict message list/load with the custom rule <code>IsIncluded()</code>. This means a message can only be displayed if you arrived at it via an include, and you can only load the chat (and thus include its messages) if you have a permit. Because includes can be deeply nested, so too can these permissions. The above section about "On" is particularly useful if you want, for example, a live loop of messages which are include restricted.

One important aspect of this is being able to create a new message with the connection to the parent chat immediately. To allow for this, "On" is supported during create calls as well.

<syntaxhighlight lang="js" line="1">
import webRequest from 'UI/Functions/WebRequest';

...

// also from <Form>'s onValues
webRequest(
"chatmessage",
{
text: 'Hello! This is a chat message',
on: {
type: 'Chat',
id: 1,
map: 'Messages' // If ChatMessage only has one ListAs, i.e. ListAs("Messages"), declaring map here is optional
}
}
);
</syntaxhighlight>

= Functional Includes =

It can be useful to run some code on a particular object whilst its JSON is generating. Whilst you can do this with the List and Load event handlers, it is generally recommended to use a functional include instead as it has less overhead. Their downside is they are global: they operate on any type. If you would like the primary URL of a piece of content, it is available as a functional include called "primaryUrl". In other words, including primaryUrl on a piece of content will provide a field called primaryUrl which would contain the page URL that content of that type is the primary content on.

As with all includes, functional includes can also be nested. You can, for example include "tags,tags.primaryUrl" - to get a list of tags on this object, plus a primaryUrl for each tag - assuming some sort of /tags/{tag.slug} page exists.

See also: PrimaryUrlValueGenerator for an example in your code.

= Dynamic Includes =

Dynamic includes are a mechanism where you can include something of a database specified type. This is useful in, for example, featured content scenario's where the thing being featured could be a product, a business or really any other kind of content. In other words: the database is specifying what the content type is, and also the ID of the content too.

To use dynamic includes, declare the field name containing the type as well as the field name containing the ID. Note that the content type field MUST be a string, and the ID field must be a ulong.

<syntaxhighlight lang="csharp">

// Including "item" when obtaining this featured content would also obtain the referenced type
// provided permission checks pass too of course.
[HasVirtualField("Item", "ContentType", "ContentId")]
public partial class FeaturedContent : VersionedContent<uint>
{
/// <summary>
/// The content type name, e.g. "Product".
/// </summary>
public string ContentType;

/// <summary>
/// The content ID. e.g. A product ID.
/// </summary>
public ulong ContentId;
}

</syntaxhighlight>

Dynamic includes should however be considered a feature of last resort. As anything can be included this way, the UI is less structured as it doesn't necessarily know for certain what it will have to display.

Globally available includes can be nested on dynamic includes too. For example, "item,item.tags" will obtain the dynamic item plus any tags on it. As functional includes such as primaryUrl are global, they are are available as well. If you use a wildcard, it will use all available implicit global includes.

Includes

2023-06-15T12:40:53Z

Luke:

Includes are a mechanism in SocialStack which allow you to request additional content when obtaining an entity (or a list of entities) from the API. For example, you have a loop of things and would like to also display the name of the user who created each one. Includes are not case sensitive.

=Frontend Usage=

Typically includes are used from either Loop or Content:

<syntaxhighlight lang="dart" line="1">
import Loop from 'UI/Loop';

...

<Loop over='page/list' includes={['creatorUser']}>
{page => {
return <div>
The page "{page.title}" was created by {page.creatorUser.username}
</div>;
}}
</Loop>

</syntaxhighlight>

<syntaxhighlight lang="dart" line="1">
import Content from 'UI/Content';

...

<Content type='page' id={1} includes={['creatorUser']}>
{page => {
if(!page){
// Just an example. The page might also not exist. See <Content> usage for more info.
return 'Loading..';
}

return <div>
The page "{page.title}" was created by {page.creatorUser.username}
</div>;
}}
</Content>

</syntaxhighlight>

If you aren't in the React render scope, you can specify includes via a webRequest as well:

<syntaxhighlight lang="js" line="1">
webRequest('page/1', null, {includes: ['creatorUser']});
</syntaxhighlight>

In some rare cases you may need a [[forms|<Form>]] response to include something custom. By default edit and create include * with their response, but they don't know about any nested includes that you may need. Form has a requestOpts prop which gives you the ability to set raw values on the webRequest that it makes, allowing us to essentially do the same as above but with a form instead:

<syntaxhighlight lang="js" line="1">
<Form action='page' requestOpts={{includes: ['*', 'creatorUser.tags']}}>
..
</syntaxhighlight>

=API Usage=

The frontend is actually just adding any includes on as a GET parameter, like so. If you have more than one, they are comma separated:

https://www.example.com/v1/page/1?includes=creatorUser

=Nested Includes=

You will often have situations where you want to include things on the included objects as well. This is done with a dot:

<syntaxhighlight lang="js" line="1">
['creatorUser', 'creatorUser.tags']
</syntaxhighlight>

Nesting has no depth limit - you can use 3+ layers deep if you need to. Because you're spelling out each depth, there is no risk of recursion or cyclical behaviour either - you can include the creatorUser of a creatorUser, even if they are the same object. (And yes, Users do have a creatorUser as well - it can be used to identify if a user account was created by an admin for example).

=Wildcards=

You can wildcard include to show all available current level includes, and this is available nested as well:

<syntaxhighlight lang="js" line="1">
['*', 'creatorUser.*']
</syntaxhighlight>

Note that the wildcard is only supported as the last field (*.creatorUser is not available for example, as not everything necessarily supports the named field you want).

Wildcards also do not show explicit includes (ones where you must explicitly list the field name).

=Making something includable=

Includable things are either singular objects (like the creator user - a piece of content only ever has 1 of those), or a list of things.

==Single objects==

To make a single object, you'll need to create a "virtual field" on your C# type:

<syntaxhighlight lang="csharp" line="1">
[HasVirtualField("OtherTypeName", typeof(OtherTypeName), "OtherTypeNameId")]
public partial class MyCustomType : VersionedContent<uint>
{
public uint OtherTypeNameId;
}
</syntaxhighlight>

You can declare as many virtual fields as you need, but essentially you define:

* The virtual fields name (this is the text which goes inside the includes array)
* The type of thing that will be included. This must always be a Content type.
* The name of the field where the ID for your included thing will come from.

For example, this is how creatorUser is actually defined:

<syntaxhighlight lang="csharp" line="1">
[HasVirtualField("CreatorUser", typeof(User), "UserId")]
</syntaxhighlight>

"Create an includable field called CreatorUser, which will be a User type, and the ID of the user to include comes from the UserId field".

=== On the admin panel ===

A virtual field declared in this way will cause a convenient dropdown selector to appear for the ID field on the admin panel (UI/ContentSelect). Sometimes though your included type may have thousands or millions of rows, so a dropdown is not appropriate and instead a search first mechanism is required. You can turn on search mode like so:

<syntaxhighlight lang="csharp" line="1">

[Data("titleField", "Name")] /* The field name to use as the title in the results list (or in the dropdown) */
[Data("search", "true")] /* Use search mode instead of a dropdown of all */
public uint OtherTypeNameId;

</syntaxhighlight>

==Lists==

To include a list of things on a type (for example, a list of answers on a poll), you'll need to mark the C# type as listable:

<syntaxhighlight lang="csharp" line="1">
[ListAs("MyCustomTypes")]
[HasVirtualField("OtherTypeName", typeof(OtherTypeName), "OtherTypeNameId")]
public partial class MyCustomType : VersionedContent<uint>
{
public uint OtherTypeNameId;

public string Name;
}
</syntaxhighlight>

You can use multiple ListAs declarations. Users is a good example of a use case for this - there is a list of permitted users on other types, but also you might want a list of members etc.

=== On the admin panel ===

By default a ListAs field will appear as a content selector on the admin panel. This content selector uses a searchbar to find the content you're after and it will default to using the [[Content_Type_Meta_Fields|meta title field]] of the thing being marked with ListAs. Meta title fields take a guess at an appropriate field to use if they are not explicitly marked and it will ultimately default to searching by a field called "Name" otherwise.

For example, if you have the MyCustomType above, it has a field called Name so the search bar that appears will use that. If it did not have a field called Name, it will also attempt to use fields like "Title" and similar if they exist, based on the rules of the [[Content_Type_Meta_Fields|meta title field]]. If you want some other field to be searched by, mark it as the meta title field instead:

<syntaxhighlight lang="csharp" line="1">
[Meta("title")]
public string Registration;
</syntaxhighlight>

With that, the admin UI will then search by this field called Registration.

===Explicit Lists===

There is a special consideration for listing though: by default, your ListAs field will be available to get included on anything. This is great for generic things like tags or categories, but the chances are you probably have something specific in mind. You can just ignore it of course, but the field will list on your admin panel and cause some unwanted clutter.

So, to clamp down where your ListAs field actually appears, use the explicit and implicit modes:

<syntaxhighlight lang="csharp" line="1">
[ListAs("MyCustomTypes", Explicit=true)]
</syntaxhighlight>

Explicit means the field name must be explicitly used - it won't appear when the wildcard is used. You can, for example, do this for your includes array:

<syntaxhighlight lang="js" line="1">
['*', 'MyCustomTypes']
</syntaxhighlight>

The wildcard is what the admin panel uses, so an explicit include will no longer appear there. So, we now have an includable field that exists but appears nowhere by default. We can then make it appear on specific types with ImplicitFor:

<syntaxhighlight lang="csharp" line="1">
[ListAs("MyCustomTypes", Explicit=true)]
[ImplicitFor("MyCustomTypes", typeof(ParentTypeToListOn))]
</syntaxhighlight>

You can list as many ImplicitFor attributes as you need. The above means the following:

* This type will be includable with the name 'MyCustomTypes'
* This 'MyCustomTypes' include will not appear on wildcard inclusions
* But it will appear on wildcard inclusions specifically for the type called 'ParentTypeToListOn'

=On: Includes without the entity=

There are situations where you'd like a list of includable things but without the thing they're included on. For example, if you want a paginated list of members. Maybe it's also live. Ideally we'd want to make use of Loop for this as it has those features, and you can do so using the On filter:

<syntaxhighlight lang="dart" line="1">
<Loop over='user' filter={{On: {type: 'MyCustomType', id: 1, map: 'UserPermits'}}}>
...
</Loop>
</syntaxhighlight>

The above loop will have the same results as having included UserPermits on MyCustomType with ID #1. This allows full access to Loop features on these specialised lists of things.

=Permissions=

Includes are a powerful way to get simple secondary and tertiary permissions - those are permissions where being able to see something relies on being able to see something else. For example, lets say you're permitted to see messages in a chat if you are a member of the chat.

We can structure this such that the user has a userPermit in the chat, with chat list/load access restricted by the custom rule <code>HasUserPermit()</code>, and we can restrict message list/load with the custom rule <code>IsIncluded()</code>. This means a message can only be displayed if you arrived at it via an include, and you can only load the chat (and thus include its messages) if you have a permit. Because includes can be deeply nested, so too can these permissions. The above section about "On" is particularly useful if you want, for example, a live loop of messages which are include restricted.

One important aspect of this is being able to create a new message with the connection to the parent chat immediately. To allow for this, "On" is supported during create calls as well.

<syntaxhighlight lang="js" line="1">
import webRequest from 'UI/Functions/WebRequest';

...

// also from <Form>'s onValues
webRequest(
"chatmessage",
{
text: 'Hello! This is a chat message',
on: {
type: 'Chat',
id: 1,
map: 'Messages' // If ChatMessage only has one ListAs, i.e. ListAs("Messages"), declaring map here is optional
}
}
);
</syntaxhighlight>

= Functional Includes =

It can be useful to run some code on a particular object whilst its JSON is generating. Whilst you can do this with the List and Load event handlers, it is generally recommended to use a functional include instead as it has less overhead. Their downside is they are global: they operate on any type. If you would like the primary URL of a piece of content, it is available as a functional include called "primaryUrl". In other words, including primaryUrl on a piece of content will provide a field called primaryUrl which would contain the page URL that content of that type is the primary content on.

See also: PrimaryUrlValueGenerator for an example in your code.

= Dynamic Includes =

Dynamic includes are a mechanism where you can include something of a database specified type. This is useful in, for example, featured content scenario's where the thing being featured could be a product, a business or really any other kind of content. In other words: the database is specifying what the content type is, and also the ID of the content too.

To use dynamic includes, declare the field name containing the type as well as the field name containing the ID. Note that the content type field MUST be a string, and the ID field must be a ulong.

<syntaxhighlight lang="csharp">

// Including "item" when obtaining this featured content would also obtain the referenced type
// provided permission checks pass too of course.
[HasVirtualField("Item", "ContentType", "ContentId")]
public partial class FeaturedContent : VersionedContent<uint>
{
/// <summary>
/// The content type name, e.g. "Product".
/// </summary>
public string ContentType;

/// <summary>
/// The content ID. e.g. A product ID.
/// </summary>
public ulong ContentId;
}

</syntaxhighlight>

Dynamic includes should however be considered a feature of last resort. As anything can be included this way, the UI is less structured as it doesn't necessarily know for certain what it will have to display.

Globally available includes can be nested on dynamic includes too. For example, "item,item.tags" will obtain the dynamic item plus any tags on it. As functional includes such as primaryUrl are global, they are are available as well. If you use a wildcard, it will use all available implicit global includes.

Permissions

2023-06-11T16:02:00Z

Luke: /* How the permission system runs */

SocialStack has a largely automated roles and capabilities permission system. In summary, a user has exactly one role, and a role is granted capabilities.

= Core Roles =

All SocialStack API's have 6 core roles, in order of typical privilege:

* Developer
The ultimate super user, defaults to no restrictions on anything.

* Admin
An administrator which is typically locked from changing potentially site breaking configuration.

* Member
A fully setup logged in user on the site.
* Guest
Typically this is someone who has created a user account but has not yet activated it in some way.

* Public
Anonymous users of the internet.

* Banned
A banned user account which typically gets bricked from most things.

Via the admin panel, you can edit the name and grants of these roles. You can also create a custom role which derives from any of them (or derives from none of them if you want a clean slate).

= Default Grants =

The above core roles are important for thirdparty modules. Ideally you want to be able to install a module and by default its permissions are set well, regardless of what actual roles you have on your website. The pattern here is that a module can optionally define a set of default grants, usually in a file called Permissions.cs, and those grants target the above 6 core roles. Custom roles then inherit from a most appropriate core role in order for it to automatically also inherit general module default grants like this.

If a module does not define a Permissions.cs, it will still gain basic best guess grants which are as follows:

* Anyone can read it
* Only developer role can create new ones.
* You must be either a developer or the owner of a content (it's UserId column equals your ID) to update or delete it.

Importantly, all default grants can be overriden in the admin panel. If you set a grant rule on the admin panel, it will be the rule that wins always, meaning that the admin panels representation of the grants is always accurate.

= Capabilities =

Each role has a list of capabilities, which themselves are automatically generated based on what is in your project. In general they come in a group of 5:

* _list
* _load
* _create
* _update
* _delete

They aren't restricted to this though - custom ones can also be defined. For a given capability in a given role, a grant rule is defined.

= Grant Rules =

Grant rules are the mechanism to indicate if a particular role is able to do something. They have 4 possible values:

* Always deny (false)
Anyone with this role will not be able to perform this capability.

* Always allow (true)
Anyone with this role will be able to perform this capability.

* Inherit (null, the default)
The grant is based on what the inherited role, if any, specifies. If the grant is not specified by any inherited role, then the grant is based on the default grants from the code.

* Custom Rule (a string)
This is a [[Filters|filter]] string, but one which supports constants. Typically you'd use filter functions in here.

Whenever the API is considering returning a result, the grant rule is effectively AND'ed with any user provided filter.

= How the permission system runs =

The permission system adds itself as a Before* event handler with priority 1. For example, page_create is tested by some code in Events.Page.BeforeCreate.AddEventListener(..., 1). Because of the way how [[Events|the event system works]], this means all default event handlers run after the permission system does, but you can also run code just before it by using priority 0:

<syntaxhighlight lang="csharp">

Events.Page.BeforeCreate.AddEventListener(async (Context context, Page page) => {
// Runs *before* the permission system
return page;
}, 0);

</syntaxhighlight>

Permissions

2023-06-11T16:01:26Z

Luke:

SocialStack has a largely automated roles and capabilities permission system. In summary, a user has exactly one role, and a role is granted capabilities.

= Core Roles =

All SocialStack API's have 6 core roles, in order of typical privilege:

* Developer
The ultimate super user, defaults to no restrictions on anything.

* Admin
An administrator which is typically locked from changing potentially site breaking configuration.

* Member
A fully setup logged in user on the site.
* Guest
Typically this is someone who has created a user account but has not yet activated it in some way.

* Public
Anonymous users of the internet.

* Banned
A banned user account which typically gets bricked from most things.

Via the admin panel, you can edit the name and grants of these roles. You can also create a custom role which derives from any of them (or derives from none of them if you want a clean slate).

= Default Grants =

The above core roles are important for thirdparty modules. Ideally you want to be able to install a module and by default its permissions are set well, regardless of what actual roles you have on your website. The pattern here is that a module can optionally define a set of default grants, usually in a file called Permissions.cs, and those grants target the above 6 core roles. Custom roles then inherit from a most appropriate core role in order for it to automatically also inherit general module default grants like this.

If a module does not define a Permissions.cs, it will still gain basic best guess grants which are as follows:

* Anyone can read it
* Only developer role can create new ones.
* You must be either a developer or the owner of a content (it's UserId column equals your ID) to update or delete it.

Importantly, all default grants can be overriden in the admin panel. If you set a grant rule on the admin panel, it will be the rule that wins always, meaning that the admin panels representation of the grants is always accurate.

= Capabilities =

Each role has a list of capabilities, which themselves are automatically generated based on what is in your project. In general they come in a group of 5:

* _list
* _load
* _create
* _update
* _delete

They aren't restricted to this though - custom ones can also be defined. For a given capability in a given role, a grant rule is defined.

= Grant Rules =

Grant rules are the mechanism to indicate if a particular role is able to do something. They have 4 possible values:

* Always deny (false)
Anyone with this role will not be able to perform this capability.

* Always allow (true)
Anyone with this role will be able to perform this capability.

* Inherit (null, the default)
The grant is based on what the inherited role, if any, specifies. If the grant is not specified by any inherited role, then the grant is based on the default grants from the code.

* Custom Rule (a string)
This is a [[Filters|filter]] string, but one which supports constants. Typically you'd use filter functions in here.

Whenever the API is considering returning a result, the grant rule is effectively AND'ed with any user provided filter.

= How the permission system runs =

The permission system adds itself as a Before* event handler with priority 1. For example, page_create is tested by some code in Events.Page.BeforeCreate.AddEventListener(..., 1). Because of the way how the event system works, this means all default event handlers run after the permission system does, but you can also run code just before it by using priority 0:

<syntaxhighlight lang="csharp">

Events.Page.BeforeCreate.AddEventListener(async (Context context, Page page) => {
// Runs *before* the permission system
return page;
}, 0);

</syntaxhighlight>

Search Component

2023-05-23T12:00:17Z

Luke:

UI/Search is a simple component which displays a search bar. It can display the results or just provide the bar itself. It is widely used on the admin panel for searching content behind the scenes.

= Render a search bar =

A simple search bar which displays its own results is as follows:

<syntaxhighlight lang="javascript">
import Search from 'UI/Search';

..

<Search for='page' field='url' onFind={page => { ..do something with page.. }}/>

</syntaxhighlight>

This will search the content type called "Page" by checking if the "Url" field contains the specified text, then list the results using the default rendering as a suggestions dropdown. When one of the suggestions is clicked on, onFind is triggered with the selected page.

= Custom results handling =

In many cases though you'll just want to have the search bar just provide you with the inputted text - i.e. it just visually looks like a search bar and does nothing else. The search component provides a debounced onQuery prop which can be used to update other filters - particularly ones used by Loop. Because it is already debounced, you won't need to worry about fast typers spamming a server - as would be the case if you directly used input onChange or keyup events.

<syntaxhighlight lang="javascript">
import Search from 'UI/Search';

..

<Search onSearch={text => {
.. do something with the searched for text here ..
}}/>

</syntaxhighlight>

The resulting text is then often well paired with <Loop> to create filtered results.

<syntaxhighlight lang="javascript">
import Loop from 'UI/Loop';

<Loop over='page' filter={{where: {
url: {contains: theSearchText}
}}}>
{page => {

.. render page as you wish here..

}}</Loop>

</syntaxhighlight>

Search Component

2023-05-23T11:59:54Z

Luke: /* Custom results handling */

UI/Search is a simple component which displays a search bar. It can display the results or just provide the bar itself. It is widely used on the admin panel for searching content behind the scenes.

= Render a search bar =

A simple search bar which displays its own results is as follows:

<syntaxhighlight lang="jsx">
import Search from 'UI/Search';

..

<Search for='page' field='url' onFind={page => { ..do something with page.. }}/>

</syntaxhighlight>

This will search the content type called "Page" by checking if the "Url" field contains the specified text, then list the results using the default rendering as a suggestions dropdown. When one of the suggestions is clicked on, onFind is triggered with the selected page.

= Custom results handling =

In many cases though you'll just want to have the search bar just provide you with the inputted text - i.e. it just visually looks like a search bar and does nothing else. The search component provides a debounced onQuery prop which can be used to update other filters - particularly ones used by Loop. Because it is already debounced, you won't need to worry about fast typers spamming a server - as would be the case if you directly used input onChange or keyup events.

<syntaxhighlight lang="jsx">
import Search from 'UI/Search';

..

<Search onSearch={text => {
.. do something with the searched for text here ..
}}/>

</syntaxhighlight>

The resulting text is then often well paired with <Loop> to create filtered results.

<syntaxhighlight lang="jsx">
import Loop from 'UI/Loop';

<Loop over='page' filter={{where: {
url: {contains: theSearchText}
}}}>
{page => {

.. render page as you wish here..

}}</Loop>

</syntaxhighlight>

Search Component

2023-05-23T11:58:20Z

Luke: /* Custom results handling */

UI/Search is a simple component which displays a search bar. It can display the results or just provide the bar itself. It is widely used on the admin panel for searching content behind the scenes.

= Render a search bar =

A simple search bar which displays its own results is as follows:

<syntaxhighlight lang="jsx">
import Search from 'UI/Search';

..

<Search for='page' field='url' onFind={page => { ..do something with page.. }}/>

</syntaxhighlight>

This will search the content type called "Page" by checking if the "Url" field contains the specified text, then list the results using the default rendering as a suggestions dropdown. When one of the suggestions is clicked on, onFind is triggered with the selected page.

= Custom results handling =

In many cases though you'll just want to have the search bar just provide you with the inputted text - i.e. it just visually looks like a search bar and does nothing else. The search component provides a debounced onQuery prop which can be used to update other filters - particularly ones used by Loop. Because it is already debounced, you won't need to worry about fast typers spamming a server - as would be the case if you directly used input onChange or keyup events.

<syntaxhighlight lang="jsx">
import Search from 'UI/Search';

..

<Search onSearch={text => {
.. do something with the searched for text here ..
}}/>

</syntaxhighlight>

Search Component

2023-05-23T11:56:45Z

Luke: Created page with "UI/Search is a simple component which displays a search bar. It can display the results or just provide the bar itself. It is widely used on the admin panel for searching cont..."

UI/Search is a simple component which displays a search bar. It can display the results or just provide the bar itself. It is widely used on the admin panel for searching content behind the scenes.

= Render a search bar =

A simple search bar which displays its own results is as follows:

<syntaxhighlight lang="jsx">
import Search from 'UI/Search';

..

<Search for='page' field='url' onFind={page => { ..do something with page.. }}/>

</syntaxhighlight>

This will search the content type called "Page" by checking if the "Url" field contains the specified text, then list the results using the default rendering as a suggestions dropdown. When one of the suggestions is clicked on, onFind is triggered with the selected page.

= Custom results handling =

In many cases though you'll just want to have the search bar just provide you with the inputted text - i.e. it just visually looks like a search bar and does nothing else. The search component provides a debounced onQuery prop which can be used to update other filters - particularly ones used by Loop. Because it is already debounced, you won't need to worry about fast typers spamming a server - as would be the case if you directly used input onChange or keyup events.

<syntaxhighlight lang="jsx">
import Search from 'UI/Search';

..

<Search onQuery={text => {
.. do something with the searched for text here ..
}}/>

</syntaxhighlight>

User Authentication

2023-05-05T18:33:14Z

Luke: /* How authentication works */

User authentication is the process of users providing some sort of information and in return getting a token (usually stored as a cookie) which can then be used automatically on multiple requests. The flow is not specific to passwords and is also highly pluggable, with the ability to add multiple authentication requirements like two factor authentication (install '''Api/TwoFactorGoogleAuth''') on the same user request, or use more advanced authentication mechanisms like SSO.

= How authentication works =

* First a request is sent to /v1/user/login. The JSON payload is mapped to a Api.Users.UserLogin object which is a partial class (extensible), meaning you can add custom fields to it if you need them.

* Next, the UserLogin object is passed to an event handler called Events.UserOnAuthenticate

* Multiple authentication providers can listen to this event. They can also work together, such as requiring both a password and a 2FA code. An authentication provider should attempt to identify the user account that it is authenticating, and then attempt to authenticate.

* If you're creating an authentication module which is intended to be used on multiple projects, it's suggested to make sure that your module checks if some previous provider has already authenticated a user. Do this by checking if there is a LoginResult currently, and if there is, return it.

* Two factor modules however require a LoginResult to exist. I.e. A previous authentication provider successfully authenticated, and now your secondary one must authenticate as well using other details from the UserLogin object. To signal that a successful authentication happened and that 2FA is required but the secondary auth has not passed yet, set MoreDetailRequired on the LoginResult object. This object is simply a canvas structured object, meaning it can indicate a UI component to display. See [https://github.com/socialstack-core/modules/blob/master/Api/TwoFactorGoogleAuth/TwoFactorGoogleAuthService.cs#L74 the Api/TwoFactorGoogleAuth] module for an example of that.

* Projects default to having the password authentication module installed. You can uninstall it if you want, but its job is to provide username or email and password authentication behaviour. It's '''Api/PasswordAuth'''.

* The PasswordAuth module selects a user to authenticate by checking if PasswordAuthService.OnSelectUser exists. This is a simple event method which you can set in order to change the actual query which runs when choosing a user to authenticate. Typically this event handler is set from within a small service such that it can have easy access to the UserService:

<syntaxhighlight lang="csharp">

using Api.Users;
using Api.Eventing;
using Api.Contexts;
using Api.PasswordAuth;

namespace Api.CustomUserQuery;

public partial class CustomUserQueryService : AutoService
{

public CustomUserQueryService(PasswordAuthService passwordAuth)
{
passwordAuth.OnSelectUser = async (Context context, UserLogin loginDetails) => {
// Use any query you'd like along with custom fields in loginDetails to select the user account you would
// like to use. Note that this does not handle authentication - only account identification.
return await users.Where("Email=?", DataOptions.IgnorePermissions).Bind(loginDetails.Email).First(context);
};
}

}

</syntaxhighlight>

Includes

2023-04-26T01:19:56Z

Luke: /* Single objects */

Includes

2023-04-26T00:39:48Z

Luke: /* Lists */

Includes are a mechanism in SocialStack which allow you to request additional content when obtaining an entity (or a list of entities) from the API. For example, you have a loop of things and would like to also display the name of the user who created each one. Includes are not case sensitive.

=Frontend Usage=

Typically includes are used from either Loop or Content:

<syntaxhighlight lang="dart" line="1">
import Loop from 'UI/Loop';

...

<Loop over='page/list' includes={['creatorUser']}>
{page => {
return <div>
The page "{page.title}" was created by {page.creatorUser.username}
</div>;
}}
</Loop>

</syntaxhighlight>

<syntaxhighlight lang="dart" line="1">
import Content from 'UI/Content';

...

<Content type='page' id={1} includes={['creatorUser']}>
{page => {
if(!page){
// Just an example. The page might also not exist. See <Content> usage for more info.
return 'Loading..';
}

return <div>
The page "{page.title}" was created by {page.creatorUser.username}
</div>;
}}
</Content>

</syntaxhighlight>

If you aren't in the React render scope, you can specify includes via a webRequest as well:

<syntaxhighlight lang="js" line="1">
webRequest('page/1', null, {includes: ['creatorUser']});
</syntaxhighlight>

In some rare cases you may need a [[forms|<Form>]] response to include something custom. By default edit and create include * with their response, but they don't know about any nested includes that you may need. Form has a requestOpts prop which gives you the ability to set raw values on the webRequest that it makes, allowing us to essentially do the same as above but with a form instead:

<syntaxhighlight lang="js" line="1">
<Form action='page' requestOpts={{includes: ['*', 'creatorUser.tags']}}>
..
</syntaxhighlight>

=API Usage=

The frontend is actually just adding any includes on as a GET parameter, like so. If you have more than one, they are comma separated:

https://www.example.com/v1/page/1?includes=creatorUser

=Nested Includes=

You will often have situations where you want to include things on the included objects as well. This is done with a dot:

<syntaxhighlight lang="js" line="1">
['creatorUser', 'creatorUser.tags']
</syntaxhighlight>

Nesting has no depth limit - you can use 3+ layers deep if you need to. Because you're spelling out each depth, there is no risk of recursion or cyclical behaviour either - you can include the creatorUser of a creatorUser, even if they are the same object. (And yes, Users do have a creatorUser as well - it can be used to identify if a user account was created by an admin for example).

=Wildcards=

You can wildcard include to show all available current level includes, and this is available nested as well:

<syntaxhighlight lang="js" line="1">
['*', 'creatorUser.*']
</syntaxhighlight>

Note that the wildcard is only supported as the last field (*.creatorUser is not available for example, as not everything necessarily supports the named field you want).

Wildcards also do not show explicit includes (ones where you must explicitly list the field name).

=Making something includable=

Includable things are either singular objects (like the creator user - a piece of content only ever has 1 of those), or a list of things.

==Single objects==

To make a single object, you'll need to create a "virtual field" on your C# type:

<syntaxhighlight lang="csharp" line="1">
[HasVirtualField("OtherTypeName", typeof(OtherTypeName), "OtherTypeNameId")]
public partial class MyCustomType : VersionedContent<uint>
{
public uint OtherTypeNameId;
}
</syntaxhighlight>

You can declare as many virtual fields as you need, but essentially you define:

* The virtual fields name (this is the text which goes inside the includes array)
* The type of thing that will be included. This must always be a Content type.
* The name of the field where the ID for your included thing will come from.

For example, this is how creatorUser is actually defined:

<syntaxhighlight lang="csharp" line="1">
[HasVirtualField("CreatorUser", typeof(User), "UserId")]
</syntaxhighlight>

"Create an includable field called CreatorUser, which will be a User type, and the ID of the user to include comes from the UserId field".

==Lists==

To include a list of things on a type (for example, a list of answers on a poll), you'll need to mark the C# type as listable:

<syntaxhighlight lang="csharp" line="1">
[ListAs("MyCustomTypes")]
[HasVirtualField("OtherTypeName", typeof(OtherTypeName), "OtherTypeNameId")]
public partial class MyCustomType : VersionedContent<uint>
{
public uint OtherTypeNameId;

public string Name;
}
</syntaxhighlight>

You can use multiple ListAs declarations. Users is a good example of a use case for this - there is a list of permitted users on other types, but also you might want a list of members etc.

=== On the admin panel ===

By default a ListAs field will appear as a content selector on the admin panel. This content selector uses a searchbar to find the content you're after and it will default to using the [[Content_Type_Meta_Fields|meta title field]] of the thing being marked with ListAs. Meta title fields take a guess at an appropriate field to use if they are not explicitly marked and it will ultimately default to searching by a field called "Name" otherwise.

For example, if you have the MyCustomType above, it has a field called Name so the search bar that appears will use that. If it did not have a field called Name, it will also attempt to use fields like "Title" and similar if they exist, based on the rules of the [[Content_Type_Meta_Fields|meta title field]]. If you want some other field to be searched by, mark it as the meta title field instead:

<syntaxhighlight lang="csharp" line="1">
[Meta("title")]
public string Registration;
</syntaxhighlight>

With that, the admin UI will then search by this field called Registration.

===Explicit Lists===

There is a special consideration for listing though: by default, your ListAs field will be available to get included on anything. This is great for generic things like tags or categories, but the chances are you probably have something specific in mind. You can just ignore it of course, but the field will list on your admin panel and cause some unwanted clutter.

So, to clamp down where your ListAs field actually appears, use the explicit and implicit modes:

<syntaxhighlight lang="csharp" line="1">
[ListAs("MyCustomTypes", Explicit=true)]
</syntaxhighlight>

Explicit means the field name must be explicitly used - it won't appear when the wildcard is used. You can, for example, do this for your includes array:

<syntaxhighlight lang="js" line="1">
['*', 'MyCustomTypes']
</syntaxhighlight>

The wildcard is what the admin panel uses, so an explicit include will no longer appear there. So, we now have an includable field that exists but appears nowhere by default. We can then make it appear on specific types with ImplicitFor:

<syntaxhighlight lang="csharp" line="1">
[ListAs("MyCustomTypes", Explicit=true)]
[ImplicitFor("MyCustomTypes", typeof(ParentTypeToListOn))]
</syntaxhighlight>

You can list as many ImplicitFor attributes as you need. The above means the following:

* This type will be includable with the name 'MyCustomTypes'
* This 'MyCustomTypes' include will not appear on wildcard inclusions
* But it will appear on wildcard inclusions specifically for the type called 'ParentTypeToListOn'

=On: Includes without the entity=

There are situations where you'd like a list of includable things but without the thing they're included on. For example, if you want a paginated list of members. Maybe it's also live. Ideally we'd want to make use of Loop for this as it has those features, and you can do so using the On filter:

<syntaxhighlight lang="dart" line="1">
<Loop over='user' filter={{On: {type: 'MyCustomType', id: 1, map: 'UserPermits'}}}>
...
</Loop>
</syntaxhighlight>

The above loop will have the same results as having included UserPermits on MyCustomType with ID #1. This allows full access to Loop features on these specialised lists of things.

=Permissions=

Includes are a powerful way to get simple secondary and tertiary permissions - those are permissions where being able to see something relies on being able to see something else. For example, lets say you're permitted to see messages in a chat if you are a member of the chat.

We can structure this such that the user has a userPermit in the chat, with chat list/load access restricted by the custom rule <code>HasUserPermit()</code>, and we can restrict message list/load with the custom rule <code>IsIncluded()</code>. This means a message can only be displayed if you arrived at it via an include, and you can only load the chat (and thus include its messages) if you have a permit. Because includes can be deeply nested, so too can these permissions. The above section about "On" is particularly useful if you want, for example, a live loop of messages which are include restricted.

One important aspect of this is being able to create a new message with the connection to the parent chat immediately. To allow for this, "On" is supported during create calls as well.

<syntaxhighlight lang="js" line="1">
import webRequest from 'UI/Functions/WebRequest';

...

// also from <Form>'s onValues
webRequest(
"chatmessage",
{
text: 'Hello! This is a chat message',
on: {
type: 'Chat',
id: 1,
map: 'Messages' // If ChatMessage only has one ListAs, i.e. ListAs("Messages"), declaring map here is optional
}
}
);
</syntaxhighlight>

Environments

2023-04-25T17:27:52Z

Luke: /* Code varying by environment */

Typically when a website is being created, it will go through 3 different "environments". The development environment - literally on a developers computer - to a staging environment where the project owner can review changes, then finally on in to production. These 3 are commonly called dev, stage and prod in short form. Socialstack has some convenience mechanisms to allow configuration and code to target specific environments, with the caveat of some important best practises around this.

= Code varying by environment =

This is best avoided for a reason which will be touched on shortly. If your code must vary by environment, you can use the Services class in the Api.Startup namespace:

<syntaxhighlight lang="csharp">

using Api.Startup;

Services.IsProduction(); // true/ false

Services.IsStaging(); // true/ false

Services.IsDevelopment(); // true/ false. This is almost never used and is instead more common to see #if DEBUG.

Services.Environment // The raw original name from appsettings

</syntaxhighlight>

On the frontend, Javascript and CSS can identify the current environment via the data-env-* attribute which is set on the <html> element:

<html data-env="dev" ..
<html data-env="stage" ..
<html data-env="prod" ..
<html data-env="..custom.." ..

The value used here is the normalised value, meaning if your appsettings originally specified "Production" then it would still be output as data-env="prod".

For the same reasons as described above, Javascript and CSS should also minimise their environment variance as much as possible and favour configuration settings instead of code.

= Best practises =

Code which checks if it is running on stage or production has a nasty caveat: It probably isn't going to be tested until it actually goes live. This can result in failed deployments and major downtime. If you do use environment specific code, make sure all code routes are at least tested beforehand. Instead though, favour environment specific configuration which is also easier to test before it goes live, as you can test it via quick configuration edits in the administration panel before it goes live too.

= How a server knows which environment it is =

A project's appsettings.json must always define an Environment field. Typically the value in here is one of "dev", "stage" or "prod". Deployed environments extend and override appsettings fields primarily with an appsettings.extension.json file.

For example, a site deployed on SocialStack cloud will have its project appsettings.json as-is and then an appsettings.extension.json which declares Environment:stage or Environment:prod, which overrides whatever was in the original appsettings.json file. This extension file is also how environment specific database and metrics tracking configuration is passed in.

If you are doing environment specific code, it is strongly advised to edit your appsettings.json to make your development instance think it is the environments you are affecting to test the code whilst it is being written.

= Environment specific configuration =

Based on the best practises above, you'll generally want to use environment specific configuration rather than code which varies based on the environment it detects. To do this, create multiple configuration entries in the configuration part of the admin panel with the same key. Configuration has a field called "Environments" which contains a comma separated list of the environments that this configuration entry applies to. Just like the Environment field, it is usually the environment shorthand name in lowercase.

When a server loads configuration, it checks the environment field to see if it contains the environment name that this server is running as. This is a loose test meaning "production" will match "prod" and "staging" will match "stage" but it's generally recommended to stick with the lowercase shorthand (dev, stage, prod) just in case custom code is explicitly checking this field for some unseen use cases.

For example, a configuration entry with "Environments" set to "dev,stage" will be ignored by a production server. You should then have a separate configuration entry with the same key with "Environments" set to "prod" to configure production instances as well. This has the advantage of all servers being able to use the same configuration table making database dumps straight forward and more portable.

Such environment varying configuration can also be used by Javascript via useConfig from UI/Configuration and marking the config in the API with the [Frontend] attribute.

Environments

2023-04-25T17:24:59Z

Luke: /* Code varying by environment */

Typically when a website is being created, it will go through 3 different "environments". The development environment - literally on a developers computer - to a staging environment where the project owner can review changes, then finally on in to production. These 3 are commonly called dev, stage and prod in short form. Socialstack has some convenience mechanisms to allow configuration and code to target specific environments, with the caveat of some important best practises around this.

= Code varying by environment =

This is best avoided for a reason which will be touched on shortly. If your code must vary by environment, you can use the Services class in the Api.Startup namespace:

<syntaxhighlight lang="csharp">

using Api.Startup;

Services.IsProduction(); // true/ false

Services.IsStaging(); // true/ false

Services.IsDevelopment(); // true/ false. This is almost never used and is instead more common to see #if DEBUG.

Services.Environment // The raw original name from appsettings

</syntaxhighlight>

On the frontend, Javascript and CSS can identify the current environment via the data-env-* attribute which is set on the <html> element:

<html data-env-dev ..
<html data-env-stage ..
<html data-env-prod ..
<html data-env="custom" ..

For the same reasons as described above, Javascript and CSS should also minimise their environment variance as much as possible and favour configuration settings instead of code.

= Best practises =

Code which checks if it is running on stage or production has a nasty caveat: It probably isn't going to be tested until it actually goes live. This can result in failed deployments and major downtime. If you do use environment specific code, make sure all code routes are at least tested beforehand. Instead though, favour environment specific configuration which is also easier to test before it goes live, as you can test it via quick configuration edits in the administration panel before it goes live too.

= How a server knows which environment it is =

A project's appsettings.json must always define an Environment field. Typically the value in here is one of "dev", "stage" or "prod". Deployed environments extend and override appsettings fields primarily with an appsettings.extension.json file.

For example, a site deployed on SocialStack cloud will have its project appsettings.json as-is and then an appsettings.extension.json which declares Environment:stage or Environment:prod, which overrides whatever was in the original appsettings.json file. This extension file is also how environment specific database and metrics tracking configuration is passed in.

If you are doing environment specific code, it is strongly advised to edit your appsettings.json to make your development instance think it is the environments you are affecting to test the code whilst it is being written.

= Environment specific configuration =

Based on the best practises above, you'll generally want to use environment specific configuration rather than code which varies based on the environment it detects. To do this, create multiple configuration entries in the configuration part of the admin panel with the same key. Configuration has a field called "Environments" which contains a comma separated list of the environments that this configuration entry applies to. Just like the Environment field, it is usually the environment shorthand name in lowercase.

When a server loads configuration, it checks the environment field to see if it contains the environment name that this server is running as. This is a loose test meaning "production" will match "prod" and "staging" will match "stage" but it's generally recommended to stick with the lowercase shorthand (dev, stage, prod) just in case custom code is explicitly checking this field for some unseen use cases.

For example, a configuration entry with "Environments" set to "dev,stage" will be ignored by a production server. You should then have a separate configuration entry with the same key with "Environments" set to "prod" to configure production instances as well. This has the advantage of all servers being able to use the same configuration table making database dumps straight forward and more portable.

Such environment varying configuration can also be used by Javascript via useConfig from UI/Configuration and marking the config in the API with the [Frontend] attribute.

Environments

2023-04-25T14:07:52Z

Luke: /* Environment specific configuration */

Typically when a website is being created, it will go through 3 different "environments". The development environment - literally on a developers computer - to a staging environment where the project owner can review changes, then finally on in to production. These 3 are commonly called dev, stage and prod in short form. Socialstack has some convenience mechanisms to allow configuration and code to target specific environments, with the caveat of some important best practises around this.

= Code varying by environment =

This is best avoided for a reason which will be touched on shortly. If your code must vary by environment, you can use the Services class in the Api.Startup namespace:

<syntaxhighlight lang="csharp">

using Api.Startup;

Services.IsProduction(); // true/ false

Services.IsStaging(); // true/ false

Services.IsDevelopment(); // true/ false. This is almost never used and is instead more common to see #if DEBUG.

Services.Environment // The raw original name from appsettings

</syntaxhighlight>

= Best practises =

Code which checks if it is running on stage or production has a nasty caveat: It probably isn't going to be tested until it actually goes live. This can result in failed deployments and major downtime. If you do use environment specific code, make sure all code routes are at least tested beforehand. Instead though, favour environment specific configuration which is also easier to test before it goes live, as you can test it via quick configuration edits in the administration panel before it goes live too.

= How a server knows which environment it is =

A project's appsettings.json must always define an Environment field. Typically the value in here is one of "dev", "stage" or "prod". Deployed environments extend and override appsettings fields primarily with an appsettings.extension.json file.

For example, a site deployed on SocialStack cloud will have its project appsettings.json as-is and then an appsettings.extension.json which declares Environment:stage or Environment:prod, which overrides whatever was in the original appsettings.json file. This extension file is also how environment specific database and metrics tracking configuration is passed in.

If you are doing environment specific code, it is strongly advised to edit your appsettings.json to make your development instance think it is the environments you are affecting to test the code whilst it is being written.

= Environment specific configuration =

Based on the best practises above, you'll generally want to use environment specific configuration rather than code which varies based on the environment it detects. To do this, create multiple configuration entries in the configuration part of the admin panel with the same key. Configuration has a field called "Environments" which contains a comma separated list of the environments that this configuration entry applies to. Just like the Environment field, it is usually the environment shorthand name in lowercase.

When a server loads configuration, it checks the environment field to see if it contains the environment name that this server is running as. This is a loose test meaning "production" will match "prod" and "staging" will match "stage" but it's generally recommended to stick with the lowercase shorthand (dev, stage, prod) just in case custom code is explicitly checking this field for some unseen use cases.

For example, a configuration entry with "Environments" set to "dev,stage" will be ignored by a production server. You should then have a separate configuration entry with the same key with "Environments" set to "prod" to configure production instances as well. This has the advantage of all servers being able to use the same configuration table making database dumps straight forward and more portable.

Such environment varying configuration can also be used by Javascript via useConfig from UI/Configuration and marking the config in the API with the [Frontend] attribute.

Environments

2023-04-25T13:52:26Z

Luke: /* Code varying by environment */

Typically when a website is being created, it will go through 3 different "environments". The development environment - literally on a developers computer - to a staging environment where the project owner can review changes, then finally on in to production. These 3 are commonly called dev, stage and prod in short form. Socialstack has some convenience mechanisms to allow configuration and code to target specific environments, with the caveat of some important best practises around this.

= Code varying by environment =

This is best avoided for a reason which will be touched on shortly. If your code must vary by environment, you can use the Services class in the Api.Startup namespace:

<syntaxhighlight lang="csharp">

using Api.Startup;

Services.IsProduction(); // true/ false

Services.IsStaging(); // true/ false

Services.IsDevelopment(); // true/ false. This is almost never used and is instead more common to see #if DEBUG.

Services.Environment // The raw original name from appsettings

</syntaxhighlight>

= Best practises =

Code which checks if it is running on stage or production has a nasty caveat: It probably isn't going to be tested until it actually goes live. This can result in failed deployments and major downtime. If you do use environment specific code, make sure all code routes are at least tested beforehand. Instead though, favour environment specific configuration which is also easier to test before it goes live, as you can test it via quick configuration edits in the administration panel before it goes live too.

= How a server knows which environment it is =

A project's appsettings.json must always define an Environment field. Typically the value in here is one of "dev", "stage" or "prod". Deployed environments extend and override appsettings fields primarily with an appsettings.extension.json file.

For example, a site deployed on SocialStack cloud will have its project appsettings.json as-is and then an appsettings.extension.json which declares Environment:stage or Environment:prod, which overrides whatever was in the original appsettings.json file. This extension file is also how environment specific database and metrics tracking configuration is passed in.

If you are doing environment specific code, it is strongly advised to edit your appsettings.json to make your development instance think it is the environments you are affecting to test the code whilst it is being written.

= Environment specific configuration =

Based on the best practises above, you'll generally want to use environment specific configuration rather than code which varies based on the environment it detects. To do this, create multiple configuration entries in the configuration part of the admin panel with the same key. Configuration has a field called "Environments" which contains a comma separated list of the environments that this configuration entry applies to. Just like the Environment field, it is usually the environment shorthand name in lowercase.

When a server loads configuration, it checks the environment field to see if it contains the environment name that this server is running as. This is a loose test meaning "production" will match "prod" and "staging" will match "stage" but it's generally recommended to stick with the lowercase shorthand (dev, stage, prod) just in case custom code is explicitly checking this field for some unseen use cases.

For example, a configuration entry with "Environments" set to "dev,stage" will be ignored by a production server. You should then have a separate configuration entry with the same key with "Environments" set to "prod" to configure production instances as well. This has the advantage of all servers being able to use the same configuration table making database dumps straight forward and more portable.

Environments

2023-04-25T13:44:02Z

Luke: /* How a server knows which environment it is */

Typically when a website is being created, it will go through 3 different "environments". The development environment - literally on a developers computer - to a staging environment where the project owner can review changes, then finally on in to production. These 3 are commonly called dev, stage and prod in short form. Socialstack has some convenience mechanisms to allow configuration and code to target specific environments, with the caveat of some important best practises around this.

= Code varying by environment =

This is best avoided for a reason which will be touched on shortly. If your code must vary by environment, you can use the Environment class in the Api.Configuration namespace:

<syntaxhighlight lang="csharp">

using Api.Configuration;

Environment.IsProduction(); // true/ false

Environment.IsStaging(); // true/ false

Environment.IsDevelopment(); // true/ false. This is almost never used and is instead more common to see #if DEBUG.

</syntaxhighlight>

= Best practises =

Code which checks if it is running on stage or production has a nasty caveat: It probably isn't going to be tested until it actually goes live. This can result in failed deployments and major downtime. If you do use environment specific code, make sure all code routes are at least tested beforehand. Instead though, favour environment specific configuration which is also easier to test before it goes live, as you can test it via quick configuration edits in the administration panel before it goes live too.

= How a server knows which environment it is =

A project's appsettings.json must always define an Environment field. Typically the value in here is one of "dev", "stage" or "prod". Deployed environments extend and override appsettings fields primarily with an appsettings.extension.json file.

For example, a site deployed on SocialStack cloud will have its project appsettings.json as-is and then an appsettings.extension.json which declares Environment:stage or Environment:prod, which overrides whatever was in the original appsettings.json file. This extension file is also how environment specific database and metrics tracking configuration is passed in.

If you are doing environment specific code, it is strongly advised to edit your appsettings.json to make your development instance think it is the environments you are affecting to test the code whilst it is being written.

= Environment specific configuration =

Based on the best practises above, you'll generally want to use environment specific configuration rather than code which varies based on the environment it detects. To do this, create multiple configuration entries in the configuration part of the admin panel with the same key. Configuration has a field called "Environments" which contains a comma separated list of the environments that this configuration entry applies to. Just like the Environment field, it is usually the environment shorthand name in lowercase.

When a server loads configuration, it checks the environment field to see if it contains the environment name that this server is running as. This is a loose test meaning "production" will match "prod" and "staging" will match "stage" but it's generally recommended to stick with the lowercase shorthand (dev, stage, prod) just in case custom code is explicitly checking this field for some unseen use cases.

For example, a configuration entry with "Environments" set to "dev,stage" will be ignored by a production server. You should then have a separate configuration entry with the same key with "Environments" set to "prod" to configure production instances as well. This has the advantage of all servers being able to use the same configuration table making database dumps straight forward and more portable.

Environments

2023-04-25T13:41:23Z

Luke: Created page with "Typically when a website is being created, it will go through 3 different "environments". The development environment - literally on a developers computer - to a staging envir..."

Typically when a website is being created, it will go through 3 different "environments". The development environment - literally on a developers computer - to a staging environment where the project owner can review changes, then finally on in to production. These 3 are commonly called dev, stage and prod in short form. Socialstack has some convenience mechanisms to allow configuration and code to target specific environments, with the caveat of some important best practises around this.

= Code varying by environment =

This is best avoided for a reason which will be touched on shortly. If your code must vary by environment, you can use the Environment class in the Api.Configuration namespace:

<syntaxhighlight lang="csharp">

using Api.Configuration;

Environment.IsProduction(); // true/ false

Environment.IsStaging(); // true/ false

Environment.IsDevelopment(); // true/ false. This is almost never used and is instead more common to see #if DEBUG.

</syntaxhighlight>

= Best practises =

Code which checks if it is running on stage or production has a nasty caveat: It probably isn't going to be tested until it actually goes live. This can result in failed deployments and major downtime. If you do use environment specific code, make sure all code routes are at least tested beforehand. Instead though, favour environment specific configuration which is also easier to test before it goes live, as you can test it via quick configuration edits in the administration panel before it goes live too.

= How a server knows which environment it is =

A project's appsettings.json must always define an Environment field. Typically the value in here is one of "dev", "stage" or "prod". Deployed environments extend and override appsettings fields primarily with an appsettings.extension.json file.

For example, a site deployed on SocialStack cloud will have its project appsettings.json as-is and then an appsettings.extension.json which declares Environment:stage or Environment:prod, which overrides whatever was in the original appsettings.json file. This extension file is also how environment specific database and metrics tracking configuration is passed in.

= Environment specific configuration =

Based on the best practises above, you'll generally want to use environment specific configuration rather than code which varies based on the environment it detects. To do this, create multiple configuration entries in the configuration part of the admin panel with the same key. Configuration has a field called "Environments" which contains a comma separated list of the environments that this configuration entry applies to. Just like the Environment field, it is usually the environment shorthand name in lowercase.

When a server loads configuration, it checks the environment field to see if it contains the environment name that this server is running as. This is a loose test meaning "production" will match "prod" and "staging" will match "stage" but it's generally recommended to stick with the lowercase shorthand (dev, stage, prod) just in case custom code is explicitly checking this field for some unseen use cases.

For example, a configuration entry with "Environments" set to "dev,stage" will be ignored by a production server. You should then have a separate configuration entry with the same key with "Environments" set to "prod" to configure production instances as well. This has the advantage of all servers being able to use the same configuration table making database dumps straight forward and more portable.

Editing Pages

2023-03-27T10:24:02Z

Luke: /* Primary content type */

Pages in SocialStack are a [[Entities|content type]] with a JSON structure that describes the [[Components|components]] on the page. We call this JSON structure [[Canvas|canvas JSON]]. A page can be both a singular URL, such as an about page on your website, or multiple, such as a page which displays blog posts.

That's quite a bit to unpack, so let's get into the details.

= What actually is a page anyway? =

Pages started life like most other modules in SocialStack - via the [[Generate|generate command]]. This means it fundamentally is no different from other modules, aside from it is simply included in the list of default modules as "Api/Pages". You can actually uninstall this module and you'll end up with an API only headless instance. This also means that they use an automated database structure as well as a service.

Pages have a database stored field called BodyJson which is a textual value that contains JSON. [[Canvas|Canvas JSON]] is a very light representation of a tree of components which, when rendered by the Canvas component on the frontend, results in your page on the screen.

Pages also have a URL field which indicates simply which URL(s) this page will be served for. For example, a page with a url of '''/about''' will be served on example.com/about. URLs can also support tokens such that one page can be used to display multiple dynamic objects - a blog or forum for example. See the section about tokens below for more information on this.

Canvas JSON is not specific to pages - it is used by emails too for example. The canvas JSON editor can be used by any content type by creating a string field which ends with "Json".

= How the editor works =

The [[Canvas Editor|canvas editor]] itself is designed to be a what-you-see-is-what-you-get experience, but there are some things to be aware of.

Firstly, it has an add component window which lists available components on the site. This window will only display components which have React propTypes set. It can be an empty object; it just needs to be not null. When generating a new UI component with the [[Generate|generate command]], it will also include a commented out propTypes too.

Secondly, the propTypes are directly used to establish what options a component has. For example if you drop an image onto the canvas, the UI/Image component has propTypes which include which actual file to display. A generated component also has some examples of these too.

Finally, the editor does also have a source view which lets you see and edit the underlying canvas JSON instead. This can often be useful for quickly fixing a layout which is otherwise awkward or ambiguous in the visual view. Check out the guide on [[Canvas|canvas JSON]] for more details on valid content here.

= URL Tokens =

You may have a page which displays, for example, blog posts. This is achieved by using tokens in your URL, like this:

/blog/{blogpost.slug}/

The value of a token is usually {contentType.fieldName} meaning tokens will work for most content including custom types. It doesn't have to be a content type though - you can also use arbritrary token values, like this:

/password-reset/{token}/

The value of this token is accessible in the same way (see the section below).

You can use multiple tokens in a single URL too, like this:

/blog/{blog.slug}/{blogpost.slug}/

== Accessing the values ==

On the frontend the token values are available via the page router, which can be used via a React hook or consumer:

<syntaxhighlight lang="js">
import {useRouter} from 'UI/Session';

...

var {pageState} = useRouter();

// pageState.tokens, pageState.tokenValues

</syntaxhighlight>

The tokens is an array of each token discovered from the URL.

Alternatively a [[Tokens|token resolver]] can be used which allows a CMS/editor friendly textual representation of the tokens as well:

<syntaxhighlight lang="js">

import {useTokens} from 'UI/Token';

...

// Assuming the original url was /blogs/{blogpost.slug}
// This would typically be a prop so someone can change the text with the editor
var inputText = 'The blog slug in the url is ${url.blogpost.slug}';

// Swaps the ${tokens} with their underlying value.
var processedText = useTokens(inputText);

return <h1>{processedText}</h1>;

</syntaxhighlight>

The token resolver works with either {typename.fieldName} or {typelessTokens} in the URL as well.

== Primary content type ==

If you use at least one content type token (such as {blogpost.slug}) in your URL, the '''very last''' of these tokens in the URL will be resolved to the content object it refers to, and this object is then called the primary content of the page.

For example going back to blog posts:

/blog/{blogpost.slug}/

The "primary content" of the page at /blog/hello-world/ will be a BlogPost with the field called "Slug" equal to the value "hello-world". The primary content on the page has some special use as it can be used in the page title, description etc amongst other things.

For convenience in React, you can quickly access the current primary content on a page like this:

<syntaxhighlight lang="js">
import Content from 'UI/Content';

...

<Content primary>
{primaryObject => {
if(!primaryObject) {
return 'Loading..';
}

// primaryObject is e.g. a BlogPost, depending on which page we're on
}}
</Content>

</syntaxhighlight>

If you need the URL for a piece of content, it must be the primary object on at least 1 page. So long as such as page exists, PageService.GetUrl will return the backwards resolved URL for you. Note that because the rule about the "very last" token above is important as it means you can have multiple pages with the same primary content. A situation where this happens might be, for example:

* /blog/hello-world/

* /blog/hello-world/comments

And similar "sub pages" for a piece of content. Because of this, the shortest one wins as being the one which will be used for the contents URL. I.e. if you ask for the URL for the blog with the slug "hello-world", then its URL would be "/blog/hello-world/".

= Page title =

The title field of a page is used for setting the title bar of the page and will also appear on e.g. search results. If your page has primary content on it (see above), you can use tokens in the page title as well. Again continuing with the BlogPost example, that may be simply the title of the post:

My Great Site | {blogpost.title}

Editing Pages

2023-03-27T10:23:20Z

Luke: /* Primary content type */

Pages in SocialStack are a [[Entities|content type]] with a JSON structure that describes the [[Components|components]] on the page. We call this JSON structure [[Canvas|canvas JSON]]. A page can be both a singular URL, such as an about page on your website, or multiple, such as a page which displays blog posts.

That's quite a bit to unpack, so let's get into the details.

= What actually is a page anyway? =

Pages started life like most other modules in SocialStack - via the [[Generate|generate command]]. This means it fundamentally is no different from other modules, aside from it is simply included in the list of default modules as "Api/Pages". You can actually uninstall this module and you'll end up with an API only headless instance. This also means that they use an automated database structure as well as a service.

Pages have a database stored field called BodyJson which is a textual value that contains JSON. [[Canvas|Canvas JSON]] is a very light representation of a tree of components which, when rendered by the Canvas component on the frontend, results in your page on the screen.

Pages also have a URL field which indicates simply which URL(s) this page will be served for. For example, a page with a url of '''/about''' will be served on example.com/about. URLs can also support tokens such that one page can be used to display multiple dynamic objects - a blog or forum for example. See the section about tokens below for more information on this.

Canvas JSON is not specific to pages - it is used by emails too for example. The canvas JSON editor can be used by any content type by creating a string field which ends with "Json".

= How the editor works =

The [[Canvas Editor|canvas editor]] itself is designed to be a what-you-see-is-what-you-get experience, but there are some things to be aware of.

Firstly, it has an add component window which lists available components on the site. This window will only display components which have React propTypes set. It can be an empty object; it just needs to be not null. When generating a new UI component with the [[Generate|generate command]], it will also include a commented out propTypes too.

Secondly, the propTypes are directly used to establish what options a component has. For example if you drop an image onto the canvas, the UI/Image component has propTypes which include which actual file to display. A generated component also has some examples of these too.

Finally, the editor does also have a source view which lets you see and edit the underlying canvas JSON instead. This can often be useful for quickly fixing a layout which is otherwise awkward or ambiguous in the visual view. Check out the guide on [[Canvas|canvas JSON]] for more details on valid content here.

= URL Tokens =

You may have a page which displays, for example, blog posts. This is achieved by using tokens in your URL, like this:

/blog/{blogpost.slug}/

The value of a token is usually {contentType.fieldName} meaning tokens will work for most content including custom types. It doesn't have to be a content type though - you can also use arbritrary token values, like this:

/password-reset/{token}/

The value of this token is accessible in the same way (see the section below).

You can use multiple tokens in a single URL too, like this:

/blog/{blog.slug}/{blogpost.slug}/

== Accessing the values ==

On the frontend the token values are available via the page router, which can be used via a React hook or consumer:

<syntaxhighlight lang="js">
import {useRouter} from 'UI/Session';

...

var {pageState} = useRouter();

// pageState.tokens, pageState.tokenValues

</syntaxhighlight>

The tokens is an array of each token discovered from the URL.

Alternatively a [[Tokens|token resolver]] can be used which allows a CMS/editor friendly textual representation of the tokens as well:

<syntaxhighlight lang="js">

import {useTokens} from 'UI/Token';

...

// Assuming the original url was /blogs/{blogpost.slug}
// This would typically be a prop so someone can change the text with the editor
var inputText = 'The blog slug in the url is ${url.blogpost.slug}';

// Swaps the ${tokens} with their underlying value.
var processedText = useTokens(inputText);

return <h1>{processedText}</h1>;

</syntaxhighlight>

The token resolver works with either {typename.fieldName} or {typelessTokens} in the URL as well.

== Primary content type ==

If you use at least one content type token (such as {blogpost.slug}) in your URL, the '''very last''' of these tokens in the URL will be resolved to the content object it refers to, and this object is then called the primary content of the page.

For example going back to blog posts:

/blog/{blogpost.slug}/

The "primary content" of the page at /blog/hello-world/ will be a BlogPost with the field called "Slug" equal to the value "hello-world". The primary content on the page has some special use as it can be used in the page title, description etc amongst other things.

For convenience in React, you can quickly access the current primary content on a page like this:

<syntaxhighlight lang="js">
import Content from 'UI/Content';

...

<Content primary>
{primaryObject => {
if(!primaryObject) {
return 'Loading..';
}

// primaryObject is e.g. a BlogPost, depending on which page we're on
}}
</Content>

</syntaxhighlight>

If you need the URL for a piece of content, it must be the primary object on at least 1 page. So long as such as page exists, PageService.GetUrl will return the backwards resolved URL for you.

Note that because the rule about the "very last" token above is important as it means you can have multiple pages with the same primary content. A situation where this happens might be, for example:

* /blog/hello-world/

* /blog/hello-world/comments

And similar "sub pages" for a piece of content. Because of this, the shortest one wins as being the one which will be used for the contents URL. I.e. if you ask for the URL for the blog with the slug "hello-world", then its URL would be "/blog/hello-world/".

= Page title =

The title field of a page is used for setting the title bar of the page and will also appear on e.g. search results. If your page has primary content on it (see above), you can use tokens in the page title as well. Again continuing with the BlogPost example, that may be simply the title of the post:

My Great Site | {blogpost.title}

Editing Pages

2023-03-27T10:23:07Z

Luke: /* Primary content type */

Pages in SocialStack are a [[Entities|content type]] with a JSON structure that describes the [[Components|components]] on the page. We call this JSON structure [[Canvas|canvas JSON]]. A page can be both a singular URL, such as an about page on your website, or multiple, such as a page which displays blog posts.

That's quite a bit to unpack, so let's get into the details.

= What actually is a page anyway? =

Pages started life like most other modules in SocialStack - via the [[Generate|generate command]]. This means it fundamentally is no different from other modules, aside from it is simply included in the list of default modules as "Api/Pages". You can actually uninstall this module and you'll end up with an API only headless instance. This also means that they use an automated database structure as well as a service.

Pages have a database stored field called BodyJson which is a textual value that contains JSON. [[Canvas|Canvas JSON]] is a very light representation of a tree of components which, when rendered by the Canvas component on the frontend, results in your page on the screen.

Pages also have a URL field which indicates simply which URL(s) this page will be served for. For example, a page with a url of '''/about''' will be served on example.com/about. URLs can also support tokens such that one page can be used to display multiple dynamic objects - a blog or forum for example. See the section about tokens below for more information on this.

Canvas JSON is not specific to pages - it is used by emails too for example. The canvas JSON editor can be used by any content type by creating a string field which ends with "Json".

= How the editor works =

The [[Canvas Editor|canvas editor]] itself is designed to be a what-you-see-is-what-you-get experience, but there are some things to be aware of.

Firstly, it has an add component window which lists available components on the site. This window will only display components which have React propTypes set. It can be an empty object; it just needs to be not null. When generating a new UI component with the [[Generate|generate command]], it will also include a commented out propTypes too.

Secondly, the propTypes are directly used to establish what options a component has. For example if you drop an image onto the canvas, the UI/Image component has propTypes which include which actual file to display. A generated component also has some examples of these too.

Finally, the editor does also have a source view which lets you see and edit the underlying canvas JSON instead. This can often be useful for quickly fixing a layout which is otherwise awkward or ambiguous in the visual view. Check out the guide on [[Canvas|canvas JSON]] for more details on valid content here.

= URL Tokens =

You may have a page which displays, for example, blog posts. This is achieved by using tokens in your URL, like this:

/blog/{blogpost.slug}/

The value of a token is usually {contentType.fieldName} meaning tokens will work for most content including custom types. It doesn't have to be a content type though - you can also use arbritrary token values, like this:

/password-reset/{token}/

The value of this token is accessible in the same way (see the section below).

You can use multiple tokens in a single URL too, like this:

/blog/{blog.slug}/{blogpost.slug}/

== Accessing the values ==

On the frontend the token values are available via the page router, which can be used via a React hook or consumer:

<syntaxhighlight lang="js">
import {useRouter} from 'UI/Session';

...

var {pageState} = useRouter();

// pageState.tokens, pageState.tokenValues

</syntaxhighlight>

The tokens is an array of each token discovered from the URL.

Alternatively a [[Tokens|token resolver]] can be used which allows a CMS/editor friendly textual representation of the tokens as well:

<syntaxhighlight lang="js">

import {useTokens} from 'UI/Token';

...

// Assuming the original url was /blogs/{blogpost.slug}
// This would typically be a prop so someone can change the text with the editor
var inputText = 'The blog slug in the url is ${url.blogpost.slug}';

// Swaps the ${tokens} with their underlying value.
var processedText = useTokens(inputText);

return <h1>{processedText}</h1>;

</syntaxhighlight>

The token resolver works with either {typename.fieldName} or {typelessTokens} in the URL as well.

== Primary content type ==

If you use at least one content type token (such as {blogpost.slug}) in your URL, the '''very last''' of these tokens in the URL will be resolved to the content object it refers to, and this object is then called the primary content of the page.

For example going back to blog posts:

/blog/{blogpost.slug}/

The "primary content" of the page at /blog/hello-world/ will be a BlogPost with the field called "Slug" equal to the value "hello-world". The primary content on the page has some special use as it can be used in the page title, description etc amongst other things.

For convenience in React, you can quickly access the current primary content on a page like this:

<syntaxhighlight lang="js">
import Content from 'UI/Content';

...

<Content primary>
{primaryObject => {
if(!primaryObject) {
return 'Loading..';
}

// primaryObject is e.g. a BlogPost, depending on which page we're on
}}
</Content>

</syntaxhighlight>

If you need the URL for a piece of content, it must be the primary object on at least 1 page. So long as such as page exists, PageService.GetUrl will return the backwards resolved URL for you.

Note that because the rule about the "very last" token above is important as it means you can have multiple pages with the same primary content. A situation where this happens might be, for example:

/blog/hello-world/
/blog/hello-world/comments

And similar "sub pages" for a piece of content. Because of this, the shortest one wins as being the one which will be used for the contents URL. I.e. if you ask for the URL for the blog with the slug "hello-world", then its URL would be "/blog/hello-world/".

= Page title =

The title field of a page is used for setting the title bar of the page and will also appear on e.g. search results. If your page has primary content on it (see above), you can use tokens in the page title as well. Again continuing with the BlogPost example, that may be simply the title of the post:

My Great Site | {blogpost.title}

Includes

2023-03-16T17:22:38Z

Luke: /* Frontend Usage */

Includes

2023-03-16T17:22:19Z

Luke: /* Frontend Usage */

Public API

2023-03-15T15:03:57Z

Luke:

SocialStack API's (the C# binary) have a REST web API whose available endpoints originate from the set of controllers in the project. For more detail on the controllers, see the page about [[API Modules|API modules]].

Note that it is somewhat uncommon to directly use the API via something like javascript fetch. Most of the time people use [[Loop]], [[Forms]], [[Content]] and occasionally [[webRequest]]. webRequest is a thin wrapper over fetch with a variety of conveniences built in.

The controllers themselves are extendible - for example if you wanted /v1/user/say-hello to exist, you can do so without editing the underlying ThirdParty default UserController as it is a partial class. Controllers for entity types, which is to say for most parts of a typical SocialStack API, have some common endpoints which are as follows:

''In all cases if you don't have permission, it will error on you.''

* GET /v1/thing/list - Lists everything of this entity type.

* POST /v1/thing/list - Lists based on a POSTed [[Filters|filter]], where the post payload is:

<syntaxhighlight lang="json">
{"query":"Token=?", "args":["the-token-value"]}
</syntaxhighlight>

It can also contain pageSize, pageIndex, sort and includeTotal to fine tune the list.

<syntaxhighlight lang="json">
{"query":"Token=?", "args":["the-token-value"], "pageSize": 10, "pageIndex": 0, "includeTotal": true, "sort": {"field": "Name", "direction": "asc"}}
</syntaxhighlight>

Including the total will return the total number of results when you are receiving a partial set of them, for example because you are specifying a page size which is less than the total number of matches.

* POST /v1/thing - Creates a new entity of the given type. The payload is simply the fields and properties of the entity.

Properties are set as well if you need some more advanced temporary values. This is used by, for example, "password" on User which is not directly stored but instead a hash of it is.

* POST /v1/thing/14 - Where 14 is an ID. Updates the entity with the given ID. The payload is the same as for creation.

* DELETE /v1/thing/14 - Deletes the given entity by its ID. Returns the entity as it was just before it was deleted.

* GET /v1/thing/14 - Loads a single item by its ID. This is what <[[Content]]> uses internally, via webRequest.

= Includes =

[[Includes]] are a mechanism in SocialStack for getting related data in the same API call. They are available on core endpoints such as load and list, and are simply a query string parameter of the includable fields that you would like to obtain.

GET /v1/thing/14?includes=creatorUser

If you're not sure what includes the API currently has, you can use a wildcard:

GET /v1/thing/14?includes=*

If there is more than one that you would like, they are comma separated:

GET /v1/thing/14?includes=creatorUser,tags

Loop

2023-03-15T15:01:06Z

Luke: /* Pagination */

<Loop> is a very commonly used [https://reactjs.org/docs/react-component.html React component] installed by default in SocialStack projects. It is used to loop over lists of items typically from the API.

=Sample Usage=

Simple loop over everything of a given type (user in this case). Note that it will always be restricted by what you are permitted to see.

<syntaxhighlight lang="dart" line="1">

import Loop from 'UI/Loop';

...

<Loop over='user'>
{
user=> {
return <p>{user.username}</p>;
}
}
</Loop>

</syntaxhighlight>

Optionally you can filter your results based on some particular [[Filters|where filter]].

<syntaxhighlight lang="dart" line="1">

import Loop from 'UI/Loop';

...

<Loop over='page' filter={
{
where: {
url: {
startsWith: '/en-admin/'
}
}
}
}>
{
page => {
return <p>{page.title}</p>;
}
}
</Loop>

</syntaxhighlight>

=Live loops=

Sometimes you'll want a loop to update in realtime - whenever someone else on the site sends you a message, for example. By default any loop can update live like this, and all it takes is the live prop:

<syntaxhighlight lang="dart" line="1">
import Loop from 'UI/Loop';

...

<Loop over='user' live>
{
user=> {
return <p>{user.username}</p>;
}
}
</Loop>

</syntaxhighlight>

Try creating a new user account - you'll see it appear on this loop without needing to do anything else, again assuming that you are permitted to see the content.

=Sorting=

Filters support an order clause - see the [[Filters|page on filters]] for more information here.

=Pagination=

A loop can be automatically paginated using the UI/Paginator component. This is done using the paged prop:

<syntaxhighlight lang="dart" line="1">
import Loop from 'UI/Loop';

...

<Loop over='user' paged={10}>
{
user=> {
return <p>{user.username}</p>;
}
}
</Loop>

</syntaxhighlight>

Paged itself has multiple configuration options, including the ability to specify which pagination component to use. At its basics though, just setting it to the number of items to display per page will get things moving.

For advanced usage, the available configuration options are like so:

<syntaxhighlight lang="dart" line="1">
import Loop from 'UI/Loop';

...

<Loop paged={{
pageSize: 10,
showInput: false,
maxLinks: 3,
module: 'UI/MyCustomPaginator'
}} ...>
</syntaxhighlight>

The module option should be used carefully to avoid inconsistency (i.e. a need to specify it on every loop would potentially arise). Instead, it's recommended to uninstall the default UI/Paginator and create a custom component of the same name.

If you'd like to restrict the result count but without a paginator visible, you can directly set pageSize and pageIndex into the filter. This is effectively what the paged prop does, along with displaying its additional UI.

<syntaxhighlight lang="dart" line="1">
import Loop from 'UI/Loop';

...

<Loop filter={{
pageSize: 10,
pageIndex: 0 // optional
}} ...>
</syntaxhighlight>

=Includes=

[[Includes]] are a mechanism in SocialStack for obtaining related data in the same API call. They are a feature of the [[public API]] but are exposed via Loop too:

<syntaxhighlight lang="js">
import Loop from 'UI/Loop';

...

<Loop over='page' includes={['creatorUser']}>
{page => {
return <div>
The page "{page.title}" was created by {page.creatorUser.username}
</div>;
}}
</Loop>
</syntaxhighlight>

= Looping over just included items =

If you'd like to have live includes or loop over items which are "on" something else, then you can use the on filter:

<syntaxhighlight lang="js">
import Loop from 'UI/Loop';

...

<Loop over='tag' filter={{on: {type: 'Page', id: 4}}}>
{tag => {
return {tag.name};
}}
</Loop>
</syntaxhighlight>

Unlike regular includes, these loops support going live too.

SocialStack Cloud

2023-03-10T16:33:58Z

Luke: /* Deployment rotation */

SocialStack Cloud is a service for simplifying the process of deploying and managing a cluster of servers running a dotnet project. It can create servers on a variety of cloud platforms (AWS, DigitalOcean, Azure) and then setup routing including DNS and loadbalancers. This is always in the form of "bring your own cloud platform account" to ensure that you have maximum access to your own sites and services.

Currently SocialStack Cloud is a non-public service and requires an administrator account to use. As SocialStack Cloud is itself a SocialStack site, anyone who is already an administrator can grant access to a new user account by changing its role [https://cloud.socialstack.dev/en-admin/ once they have registered here].

= Creating a project =

To create a new project, first go to the [https://cloud.socialstack.dev/projects/ project list] and click the new project button. You'll need to give your project a name and specify the cloud platform account to use. Cloud platform config is optional if you are only importing connection details for existing servers. You can also specify multiple platforms simultaneously which can be useful for large multicloud clusters. Here's sample platform configuration for the 3 main cloud platforms:

== AWS ==

Create an access key [https://docs.aws.amazon.com/sdk-for-net/latest/developer-guide/net-dg-users-roles.html following the guide here].

<syntaxhighlight lang="json">
{
"AWS": {
"AccessKeyId": "abcabc..",
"SecretAccessKey": "abcabc.."
}
}
</syntaxhighlight>

== DigitalOcean ==

Create an [https://cloud.digitalocean.com/account/api/tokens access token for the account you would like to use]. It's recommended to create a team, optionally per project, so you can better monitor individual project resources and their costs.

<syntaxhighlight lang="json">
{
"DigitalOcean": {
"ApiKey": "abcabcabcabc.."
}
}
</syntaxhighlight>

== Azure ==

Create an Azure active directory service principal [https://learn.microsoft.com/en-us/azure/active-directory/develop/howto-create-service-principal-portal following the guide here].

<syntaxhighlight lang="json">
{
"Azure": {
"TenantId": "...",
"ClientId": "...",
"ClientSecret": "...",
"SubscriptionId": "..."
}
}
</syntaxhighlight>

= Cloud Build =

Optionally during project creation, specify where your source is. Currently it must be a git repository and one which is accessible via classic git authentication (A personal access token over https rather than an SSH key).

Cloud build works by using the stage server of the project. This way the code of a given project is always isolated into a dedicated cluster of servers and it can do a pull rather than a full checkout for often large gains in build speed. Because of this, there are a few important notes:

* The stage server needs enough RAM to run your site and the build. The "medium" server option is usually appropriate. This is usually a battle between Babel (the javascript transpiler) which uses some 600MB on its own and MySQL which will take as much RAM as it can get. If a build is running very slowly or the stage site appears to have gone offline whilst a build is happening, it's because the server has ran out of RAM. Connecting to the server and stopping MySQL is usually the easiest way to allow a build through on a small stage server.

* The checkout goes in to /var/www/repo on the first stage server created.

* If the checkout failed because the git credentials are wrong, the git credentials go in a git store located at ~/.git-credential of the root user.

== Triggering builds ==

Projects with cloud build config have a Build button. This build button is simply a link to a URL which can be used from any pipeline to trigger a build automatically, as the link does not require authentication as it contains a non-guessable randomly generated unique project key. As a build is performed on a stage server, updating the stage service itself is near instantaneous and happens as part of a build cycle.

If you click the button manually, don't close the page that opens as it will give you the build log in realtime.

== Deploying builds ==

When you're ready to deploy, projects have a deploy button. Like the build button, this contains a link that can be used in external pipelines as well. This works by copying the build artifacts from the projects indicated build server (the first created stage server) and then uploading them to resources in the production environment via SSH. It waits for the upload to complete for every node before proceeding further. Once every node has a copy of the files, it then proceeds to one by one reload the services.

=== Deployment rotation ===

When Socialstack cloud deploys a project, it will move existing code out of the way by putting it into a directory called deploy which is usually found at either /var/www/stage/deploy or /var/www/prod/deploy. Note that it specifically does not do this with the Content directory as the Content directory is considered to be stateful. The previous build is put into a directory called ''prev''. Like this:

* If deploy/prev-2 exists, delete it.
* If deploy/prev-1 exists, rename it to prev-2.
* If deploy/prev exists, rename it to prev-1.
* Create deploy/prev and move the previous build into it.

This means only the previous 3 deployments are retained and you can find them in the deploy folder should you need to recover them. Note that because this happens primarily using the move command rather than by copying it is usually an extremely fast switching operation.

= Creating a server =

Once you've created a project, you'll be able to start creating resources. They can be created in any order but it is suggested to create a singular medium size stage server first:

[[File:Creating-stage-server.png]]

The available platform and region options are based on whichever platform(s) you have configured in your project.

= Adding existing servers =

This mechanism exists to add servers created manually/ externally. It is a way to use SocialStack Cloud features without providing an API key. It also works as a way to add things like managed MySQL instances via providing the username and password from the host.

= How servers are deployed =

This is a high level overview of the steps that SocialStack cloud goes through whilst deploying a resource. Because there is currently a very broad spectrum of combinations, it is suggested to either [https://source.socialstack.dev/infrastructure/socialstack-cloud/-/blob/master/Api/Servers/ServerService.cs check the source] or just deploy the combination you're interested in and then check its deploy log as it will list everything that it ran aside from the contents of uploaded files. There is a button to view the creation log on [https://cloud.socialstack.dev/projects/ a server's information panel].

SocialStack Cloud will go through a series of phases when setting up a server. The current phase a server is in can be seen on a particular servers information screen via the [https://cloud.socialstack.dev/projects/ project's page]. The setup process will vary depending on which resource is being setup, which cloud and which operating system it is on.

== Server creation ==

When the OS is unspecified, SocialStack cloud will deploy AL2 (Amazon Linux 2) on AWS and Ubuntu everywhere else. It will then wait for the server to exist and indicate that it is ready. It does this by connecting over SSH periodically as a user called "sscloud" to check the [https://cloudinit.readthedocs.io/en/latest/ cloudinit] status.

== Installing software ==

When the resource is ready for installation, SocialStack cloud then executes install commands over SSH. On most SocialStack servers, this installs dotnet, [https://www.nginx.com/ Nginx] and MySQL, then tunes the OS for typical SocialStack high volume throughput. The complete log of everything that is executed during server setup is available via the "view creation log" button on a particular resource.

== DNS ==

By default all SocialStack cloud projects are given an automatically generated DNS subdomain under .stage.socialstack.dev and the DNS records are added to the DNS zone for socialstack.dev which is currently hosted on rackspace.

'''Known issue with the rackspace DNS zone''': it is too large! Lately this has been surfacing as multiple failed certificate requests. You just have to be a little patient with it and retry.

== Certificates ==

SocialStack cloud uses the DNS authorization technique to obtain a Let's Encrypt certificate for the site too. DNS authorization is useful for multiple reasons: firstly it is a wildcard certificate so fewer are needed; larger deployments can typically all use the same wildcard certificate for example. Secondly http based authorization can be challenging when loadbalancers are involved as the response will be directed to a random server.

It is able to perform the DNS authorization technique for any domain that it has record access to. Currently that is any domain on the rackspace account.

Once a certificate has been obtained, SocialStack cloud then checks if it can apply it anywhere. It will apply it if a particular resource has a matching environment and address. The certificate is applied by connecting to the server over SSH and then uploading the certificate in to /etc/ssl/cert and then reloading nginx (the web server). This certificate location can also be seen in the nginx configuration which is usually located at /etc/nginx/sites-enabled/ (this can vary between OS's but is very commonly here).

= Managing Services =

As the deployment can vary due to both the software being deployed and the OS it is being deployed on, this is just a rough guideline for common scenarios. As before it's recommended to take a look at the creation log to get a better idea of what software is actually running, particularly if the

== SocialStack API on Ubuntu ==

SocialStack cloud installs a service called either "stage" or "prod" which is managed by systemD on ubuntu. This means you can restart it etc like so:

<syntaxhighlight lang="bash">
# superuser only
sudo su

service stage stop
service stage start
service stage restart
</syntaxhighlight>

And view its current log using journalctl like so:

<syntaxhighlight lang="bash">
journalctl -u stage -n 100
</syntaxhighlight>

= Accessing a server =

Because servers are deployed in to a "bring your own cloud" environment, there are two ways to access a server. Either through the underlying cloud platform if you have access to that, or via the "Let me in" button on a particular server's information panel. This button requires that your SocialStack cloud account has an SSH public key associated with it. This button tells SocialStack cloud to add your public key to the target server's user list if it wasn't already there, and SocialStack Cloud adds it via connecting over SSH to the target server.

When you use the "Let me in" button it will also provide a useful summary of the connection details.

= Server health reporting =

All resources created on SocialStack Cloud are configured with a ReportTo URL. This tells the resource to frequently ping SocialStack Cloud with a health update. The current list of healthy resources is used to configure loadbalancers.

SocialStack cloud retains historical health data in the form of (millions of) revisions of the "MonitoredHost" content type.

= SocialStack Cloud Source =

The SocialStack project is currently a private repository [https://source.socialstack.dev/infrastructure/socialstack-cloud located here].

SocialStack Cloud

2023-03-10T16:32:30Z

Luke: /* Deploying builds */

SocialStack Cloud is a service for simplifying the process of deploying and managing a cluster of servers running a dotnet project. It can create servers on a variety of cloud platforms (AWS, DigitalOcean, Azure) and then setup routing including DNS and loadbalancers. This is always in the form of "bring your own cloud platform account" to ensure that you have maximum access to your own sites and services.

Currently SocialStack Cloud is a non-public service and requires an administrator account to use. As SocialStack Cloud is itself a SocialStack site, anyone who is already an administrator can grant access to a new user account by changing its role [https://cloud.socialstack.dev/en-admin/ once they have registered here].

= Creating a project =

To create a new project, first go to the [https://cloud.socialstack.dev/projects/ project list] and click the new project button. You'll need to give your project a name and specify the cloud platform account to use. Cloud platform config is optional if you are only importing connection details for existing servers. You can also specify multiple platforms simultaneously which can be useful for large multicloud clusters. Here's sample platform configuration for the 3 main cloud platforms:

== AWS ==

Create an access key [https://docs.aws.amazon.com/sdk-for-net/latest/developer-guide/net-dg-users-roles.html following the guide here].

<syntaxhighlight lang="json">
{
"AWS": {
"AccessKeyId": "abcabc..",
"SecretAccessKey": "abcabc.."
}
}
</syntaxhighlight>

== DigitalOcean ==

Create an [https://cloud.digitalocean.com/account/api/tokens access token for the account you would like to use]. It's recommended to create a team, optionally per project, so you can better monitor individual project resources and their costs.

<syntaxhighlight lang="json">
{
"DigitalOcean": {
"ApiKey": "abcabcabcabc.."
}
}
</syntaxhighlight>

== Azure ==

Create an Azure active directory service principal [https://learn.microsoft.com/en-us/azure/active-directory/develop/howto-create-service-principal-portal following the guide here].

<syntaxhighlight lang="json">
{
"Azure": {
"TenantId": "...",
"ClientId": "...",
"ClientSecret": "...",
"SubscriptionId": "..."
}
}
</syntaxhighlight>

= Cloud Build =

Optionally during project creation, specify where your source is. Currently it must be a git repository and one which is accessible via classic git authentication (A personal access token over https rather than an SSH key).

Cloud build works by using the stage server of the project. This way the code of a given project is always isolated into a dedicated cluster of servers and it can do a pull rather than a full checkout for often large gains in build speed. Because of this, there are a few important notes:

* The stage server needs enough RAM to run your site and the build. The "medium" server option is usually appropriate. This is usually a battle between Babel (the javascript transpiler) which uses some 600MB on its own and MySQL which will take as much RAM as it can get. If a build is running very slowly or the stage site appears to have gone offline whilst a build is happening, it's because the server has ran out of RAM. Connecting to the server and stopping MySQL is usually the easiest way to allow a build through on a small stage server.

* The checkout goes in to /var/www/repo on the first stage server created.

* If the checkout failed because the git credentials are wrong, the git credentials go in a git store located at ~/.git-credential of the root user.

== Triggering builds ==

Projects with cloud build config have a Build button. This build button is simply a link to a URL which can be used from any pipeline to trigger a build automatically, as the link does not require authentication as it contains a non-guessable randomly generated unique project key. As a build is performed on a stage server, updating the stage service itself is near instantaneous and happens as part of a build cycle.

If you click the button manually, don't close the page that opens as it will give you the build log in realtime.

== Deploying builds ==

When you're ready to deploy, projects have a deploy button. Like the build button, this contains a link that can be used in external pipelines as well. This works by copying the build artifacts from the projects indicated build server (the first created stage server) and then uploading them to resources in the production environment via SSH. It waits for the upload to complete for every node before proceeding further. Once every node has a copy of the files, it then proceeds to one by one reload the services.

=== Deployment rotation ===

When Socialstack cloud deploys a project, it will move existing code out of the way by putting it into a directory called deploy which is usually found at either /var/www/stage/deploy or /var/www/prod/deploy. The previous build is put into a directory called ''prev''. Like this:

* If deploy/prev-2 exists, delete it.
* If deploy/prev-1 exists, rename it to prev-2.
* If deploy/prev exists, rename it to prev-1.
* Create deploy/prev and move the previous build into it.

This means only the previous 3 deployments are retained and you can find them in the deploy folder should you need to recover them. Note that because this happens primarily using the move command rather than by copying it is usually an extremely fast switching operation.

= Creating a server =

Once you've created a project, you'll be able to start creating resources. They can be created in any order but it is suggested to create a singular medium size stage server first:

[[File:Creating-stage-server.png]]

The available platform and region options are based on whichever platform(s) you have configured in your project.

= Adding existing servers =

This mechanism exists to add servers created manually/ externally. It is a way to use SocialStack Cloud features without providing an API key. It also works as a way to add things like managed MySQL instances via providing the username and password from the host.

= How servers are deployed =

This is a high level overview of the steps that SocialStack cloud goes through whilst deploying a resource. Because there is currently a very broad spectrum of combinations, it is suggested to either [https://source.socialstack.dev/infrastructure/socialstack-cloud/-/blob/master/Api/Servers/ServerService.cs check the source] or just deploy the combination you're interested in and then check its deploy log as it will list everything that it ran aside from the contents of uploaded files. There is a button to view the creation log on [https://cloud.socialstack.dev/projects/ a server's information panel].

SocialStack Cloud will go through a series of phases when setting up a server. The current phase a server is in can be seen on a particular servers information screen via the [https://cloud.socialstack.dev/projects/ project's page]. The setup process will vary depending on which resource is being setup, which cloud and which operating system it is on.

== Server creation ==

When the OS is unspecified, SocialStack cloud will deploy AL2 (Amazon Linux 2) on AWS and Ubuntu everywhere else. It will then wait for the server to exist and indicate that it is ready. It does this by connecting over SSH periodically as a user called "sscloud" to check the [https://cloudinit.readthedocs.io/en/latest/ cloudinit] status.

== Installing software ==

When the resource is ready for installation, SocialStack cloud then executes install commands over SSH. On most SocialStack servers, this installs dotnet, [https://www.nginx.com/ Nginx] and MySQL, then tunes the OS for typical SocialStack high volume throughput. The complete log of everything that is executed during server setup is available via the "view creation log" button on a particular resource.

== DNS ==

By default all SocialStack cloud projects are given an automatically generated DNS subdomain under .stage.socialstack.dev and the DNS records are added to the DNS zone for socialstack.dev which is currently hosted on rackspace.

'''Known issue with the rackspace DNS zone''': it is too large! Lately this has been surfacing as multiple failed certificate requests. You just have to be a little patient with it and retry.

== Certificates ==

SocialStack cloud uses the DNS authorization technique to obtain a Let's Encrypt certificate for the site too. DNS authorization is useful for multiple reasons: firstly it is a wildcard certificate so fewer are needed; larger deployments can typically all use the same wildcard certificate for example. Secondly http based authorization can be challenging when loadbalancers are involved as the response will be directed to a random server.

It is able to perform the DNS authorization technique for any domain that it has record access to. Currently that is any domain on the rackspace account.

Once a certificate has been obtained, SocialStack cloud then checks if it can apply it anywhere. It will apply it if a particular resource has a matching environment and address. The certificate is applied by connecting to the server over SSH and then uploading the certificate in to /etc/ssl/cert and then reloading nginx (the web server). This certificate location can also be seen in the nginx configuration which is usually located at /etc/nginx/sites-enabled/ (this can vary between OS's but is very commonly here).

= Managing Services =

As the deployment can vary due to both the software being deployed and the OS it is being deployed on, this is just a rough guideline for common scenarios. As before it's recommended to take a look at the creation log to get a better idea of what software is actually running, particularly if the

== SocialStack API on Ubuntu ==

SocialStack cloud installs a service called either "stage" or "prod" which is managed by systemD on ubuntu. This means you can restart it etc like so:

<syntaxhighlight lang="bash">
# superuser only
sudo su

service stage stop
service stage start
service stage restart
</syntaxhighlight>

And view its current log using journalctl like so:

<syntaxhighlight lang="bash">
journalctl -u stage -n 100
</syntaxhighlight>

= Accessing a server =

Because servers are deployed in to a "bring your own cloud" environment, there are two ways to access a server. Either through the underlying cloud platform if you have access to that, or via the "Let me in" button on a particular server's information panel. This button requires that your SocialStack cloud account has an SSH public key associated with it. This button tells SocialStack cloud to add your public key to the target server's user list if it wasn't already there, and SocialStack Cloud adds it via connecting over SSH to the target server.

When you use the "Let me in" button it will also provide a useful summary of the connection details.

= Server health reporting =

All resources created on SocialStack Cloud are configured with a ReportTo URL. This tells the resource to frequently ping SocialStack Cloud with a health update. The current list of healthy resources is used to configure loadbalancers.

SocialStack cloud retains historical health data in the form of (millions of) revisions of the "MonitoredHost" content type.

= SocialStack Cloud Source =

The SocialStack project is currently a private repository [https://source.socialstack.dev/infrastructure/socialstack-cloud located here].