SocialStack - User contributions [en-gb]

Canvas

2022-07-06T01:48:43Z

2A02:C7F:22BE:A500:498:3225:1A16:A72D:

Canvas is SocialStack's main mechanism for representing configurable structured content - that's mainly things like pages of your site and emails. It is stored as a JSON format and the JSON is passed to the React <Canvas> element usually as a child.

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

..

<Canvas>{"t":"UI/Header"}</Canvas>

</syntaxhighlight>

=Canvas Json=

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

{
"t": "UI/HelloWorld",
"d": {
"customProp": "This is a prop value passed to UI/HelloWorld"
},
"c": [
{
"t": "b",
"c": "This is bold text as a child of UI/HelloWorld."
}
]
}

</syntaxhighlight>

The JSON that Canvas uses is a very thin system for representing a tree of elements. A json object with these fields we'll refer to as a "canvas node" here. It has 3 main fields:

* t (type): The type of this element. It is either an absolute component path or the name of a HTML element usually in lowercase.

* d (data): Any custom data for the element. In React these are passed to your element as props as-is. Importantly though, HTML elements are not expected to support data (but where they do, the values are as-is attributes). This is such that canvas JSON is safe for use by frontend users to create and is not overly tied to HTML itself. I.e. "t": "b" indicates bold.

* c (children): Any child nodes of the element. These are processed as canvas nodes then passed as the children prop in React. It can be an array of canvas nodes/ strings, a single canvas node or a single string. Strings are treated as raw text.

There are some additional fields which can be used for diffing canvas JSON amongst other things:

* s (string): An object containing "s": "some text" works the same way as just a text string in children, but with the advantage of being able to have additional fields on it such as an id.

* i (id): A unique number for this particular node. Particularly useful for comparing changes in canvases. Editors must not reuse a removed id; it must only ever increase.

* ti (template ID): If a canvas node was imported from another canvas, it can be given both an ID and a template ID to identify where it originated from. This allows these remote nodes to have custom overrideable data values but are still easily diffable with the source canvas that they came from.

* r (roots): Sometimes you may want your props to be canvas formatted. You could pass a JSON string via data and then have your component internally render it but that is not particularly friendly for editors - it's nice if a canvas editor is aware that your prop is something it can edit too, potentially even inline. This is what roots are for - they are canvas root nodes which are then passed to your component as a prop after it has been rendered. I.e. in React, the value of the prop that you receive is a React node. A canvas root node has the restriction that it must be an object, not a string, but it can still contain strings as its child nodes.

Getting Started

2022-07-06T01:38:14Z

2A02:C7F:22BE:A500:498:3225:1A16:A72D: /* Creating frontend UI modules */

= Introduction =

Hello! Welcome to SocialStack, a fully open source modular collection of C# and javascript code used to create modern, ultra high throughput projects which has been tried and tested by big name brands. This guide is targeted at developers so with that in mind, let's get in to it!

= Installing dependencies =

So, to get started, you'll need a few things first. Whilst SocialStack does support using multiple database engines, we currently reccommend starting with MySQL. Here's what you'll need:

* An editor capable of working with dotnet 6. For example, Visual Studio Code or Visual Studio 2022.
* Node.js 8+ which is used to run the command line tools
* MySQL version 8 is reccommended
* Git, as a new project will also be created as a git repository.

= Setting up the command line tools =

Once you've got the dependencies ready, it's time to setup the [https://www.npmjs.com/package/socialstack command line tools] which we'll shortly use to create a project. In a nutshell, it is an optional npm package which can be installed globally by running this:

<syntaxhighlight lang="bash">
npm i -g socialstack
</syntaxhighlight>

Note that this command line tool set (and node.js) are not required by production sites. It's just a convenience system for installing modules and creating projects.

It's recommended to configure socialstack tools with the ability to create MySQL databases for you on your development computer. To do this, you'll need to create a MySQL account on your MySQL instance which it can use and which has the permission to create databases and users. Here's an example of how to do that:

<syntaxhighlight lang="sql">
-- Create the user account:
CREATE USER 'sstools'@'localhost' IDENTIFIED BY 'ssto0ls.dev'; -- Invent a password here!
-- Grant that user full access to the db:
GRANT ALL PRIVILEGES ON *.* TO 'sstools'@'localhost' WITH GRANT OPTION;
FLUSH PRIVILEGES;
</syntaxhighlight>

You can then add this account to your command line tools like so, making sure the password and username matches what you used:

<syntaxhighlight lang="bash">
socialstack configure -u "sstools" -p "ssto0ls.dev"
</syntaxhighlight>

This is a global thing, so once you've done it you won't need to do it again. You're ready to create a project!

= Creating a project =

With the command line tools ready to go, you can then go ahead and create a project like so:

<syntaxhighlight lang="bash">
cd myProjectDirectory
socialstack create helloworld
</syntaxhighlight>

This will ask if you want to install any additional modules straight away. Just skip this by pressing enter. If your configuration is ok, a database will be created for you as well as the project.

= Starting it up =

With your project created, start it up in a suitable editor (typically that is Visual Studio Code, or Visual Studio 2022) or via the command line by starting the Api.csproj project. Whilst it starts, it will give you a few bits of information:

* It will list which services (provided by modules) are installed and starting up.
* It will create the database tables and any initial data needed by those services. This is fully automated.
* It will let you know that a default administration account was created, and what its details are. This happens once; if you missed it you can check the site_user table in your database as it will have one row and the default password is simply '''admin'''.
* It lets you know how to get to the instance. This defaults to http://localhost:5050/ which you can navigate to in a browser.
* It compiles the UI and indicates when its done. This is usually the very last thing that appears and the UI won't display to you until it completes.

= Going exploring =

With your project started, head over to http://localhost:5050/ in a browser and you should see a barebones homepage with a welcome message. This brings us to the first key point:

> Pages in SocialStack entirely come from the editable CMS area - this includes administration panel pages too. There's no fighting against surrounding page templates as the root component(s) on the page are whatever you choose. More on components later!

So, let's head in to the administration panel and make some changes. Head over to http://localhost:5050/en-admin/ in a browser and you should see a login panel. At this point use the generated administration account to login which will currently default to:

* Username: '''admin'''
* Password: '''admin'''

Once you've logged in, in the top left corner is a menu which you can use to get to the list of pages. On this list, find the homepage and open the page editor. [[Editing Pages|Editing a page]] (and more generally how they actually work) is a broad topic on its own so please take a moment to check out [[Editing Pages|that article]] first, then head back here when you're ready.

= Creating API modules =

Next is a good point to have a go at creating your own API module. A video version of this part of the guide is [https://www.youtube.com/watch?v=4rrfyg4Wk_g available here]. We'll make something like a list of frequently asked questions. SocialStack tools has a [[generate|generate command]] which creates the basic scaffolding of a new API module for you, so let's generate that now:

<syntaxhighlight lang="bash">
socialstack generate Api/FrequentlyAskedQuestions
</syntaxhighlight>

All this does is create a directory with some generated files; i.e. copy/pasting or manually creating one of those directories has the same outcome as there are no hidden indexes or other files to update. In this case, it will be in the directory ProjectRoot/Api/FrequentlyAskedQuestions. It should also appear in the explorer inside an IDE such as Visual Studio. Inside this folder, you'll see a small collection of files with different purposes, which are explored in [[API Modules|this section of the wiki]]. Take a look there, then head back here when you're ready.

Next we'll need to add fields to the generated FAQ type as so far it is just an empty shell. To do that, edit FrequentlyAskedQuestion.cs and add 2 fields:

<syntaxhighlight lang="csharp">
/// <summary>
/// The question people ask.
/// </summary>
[Localized]
public string Question;

/// <summary>
/// The answer.
/// </summary>
[Localized]
public string AnswerJson;
</syntaxhighlight>

It would also help to be able to see and edit these FAQ's via the admin panel, so edit FrequentlyAskedQuestionService.cs and uncomment the admin panel pages line.

As you have made changes to C#, you'll need to restart the API for the changes to take effect. The easiest way is to stop/ start the running project in your IDE. When it starts back up, head back in to the admin panel at http://localhost:5050/en-admin/ and you should see a new link in the menu to your newly created FAQ's. Have a go at creating and editing some, and then when you're ready head back over here.

We now have some data in your database and an ability to see and manipulate it with the admin panel. So far so good!

= Creating frontend UI modules =

Next it would be great if you could also list out your FAQs on the actual website so let's explore that next. This part of the guide is also covered in [https://www.youtube.com/watch?v=YyFNVPwbIz4 a video about Loop], however just like before, it all starts with a generate command:

<syntaxhighlight lang="bash">
socialstack generate UI/Faq/List
</syntaxhighlight>

This will create a directory in ProjectRoot/UI/Source/Faq/List containing 2 files; a React component and some CSS to go with it.

Note: Changes to the UI are compiled immediately whenever the API is running. That includes creating files, generating modules, editing files and so on - and the updates are usually near instant too.

There's 3 main convenience ways to access data from the API via a React component - [[Loop|Loop]], [[Content]] and webRequest. [[Loop|Loop]] is for a list of things, [[Content]] is for just one and webRequest is for any other situation in e.g. useEffect or componentDidMount where you need to grab data without being in a React render function. [[Loop|Loop]] and Content simply sit on top of webRequest and use the [[Public API|public part of the projects API]] (that's controllers in your API, which use the services to return the data). We want a list of FAQs here, so we'll use Loop. Here's an example:

<syntaxhighlight lang="js">

import Canvas from 'UI/Canvas';
import Loop from 'UI/Loop';

export default function List(props){
// Loops over the FAQs from the API and also uses a
// canvas to display the answer which is visual editor content.
return <Loop over='frequentlyaskedquestion'>{
faq => {
return <div>
<h1>{faq.question}</h1>
<Canvas>{faq.answerJson}</Canvas>
</div>;
}
}</Loop>;

}

Loop.propTypes = {}; // No props used on this list.

</syntaxhighlight>

Save the file, and then because we specified an empty propTypes object, the page editor will now recognise the component and list it in the add window. So if you head back over to the admin panel, you'll then be able to add this component to the page. Alternatively if you prefer writing the JSON, the page JSON looks like this:

<syntaxhighlight lang="json">
{"t":"UI/Faq/List"}
</syntaxhighlight>

Notice that the name matches what you generated, and is the same as the filepath minus the "Source" folder.

API Modules

2022-07-06T01:30:48Z

2A02:C7F:22BE:A500:498:3225:1A16:A72D: /* ThingController.cs */

A newly regularly generated API module has 5 files. Assuming you did '''socialstack generate Api/Things''', here's what each of them is for:

= Events.cs =

When something happens in your API, an event is triggered. By default all entities have a common set of events for things like creation/ updates/ deletion etc, but it can be extended by defining a custom event type. This is detailed more on [[Events|the page about events]]. One of the core goals of events in SocialStack is for them to be extremely fast and also easy to use with IDE autofilling, so these auto generated files exist to enable those statically typed naming in the form of Events.Thing.BeforeCreate and so on.

Event handlers, including for a services own content type, are typically added inside service constructors.

= Thing.cs =

This is the entity description file. It describes what fields are on the entity. In a nutshell, fields are stored in the database and properties are not. There are some conveniences around field naming which is described on [[Entities|the entities page]].

= ThingService.cs =

The [[services|service]], a singleton (instanced once at startup), is used for getting/ listing/ deleting/ updating/ creating an entity. For example if you want to get hold of a user's information, you would ask the UserService. Services support C# dependency injection but can also be obtained via '''Services.Get<UserService>()''', with Services in the Startup namespace.

Often, event handlers are placed inside the service's constructor in order to validate your entity or e.g. add custom field values to it whilst it is being created. It's very common for e.g. ThingService to have Events.Thing.BeforeUpdate and so on inside its own constructor - this allows flexibility in the form of other modules actually unregistering those handlers, if it has a goal of heavily overriding default behaviours.

= ThingController.cs =

Controllers are the web API endpoints and effectively represent the main user facing frontage of your site. Just like with services, the controllers have a series of [[public API|common convenience endpoints]] which are usually accessed with webRequest or [[Loop|Loop]] on the frontend.

= Permissions.cs =

This file is used to define the installable, base permissions for your module. It should represent the most common scenario that you expect to happen. For example, password resets should never be publicly visible - and that is going to be quite universal on most websites. These base permission grants can however be overridden in the admin panel, or with other event listeners. When creating permission grants in code, they should target the core roles, particularly if the intent is to make a portable module which can be copied or installed easily on to other projects.

For more information on what the roles are and how the grants work, take a look at the [[permissions|permissions article]].

API Modules

2022-07-06T01:30:34Z

2A02:C7F:22BE:A500:498:3225:1A16:A72D: /* ThingController.cs */

A newly regularly generated API module has 5 files. Assuming you did '''socialstack generate Api/Things''', here's what each of them is for:

= Events.cs =

When something happens in your API, an event is triggered. By default all entities have a common set of events for things like creation/ updates/ deletion etc, but it can be extended by defining a custom event type. This is detailed more on [[Events|the page about events]]. One of the core goals of events in SocialStack is for them to be extremely fast and also easy to use with IDE autofilling, so these auto generated files exist to enable those statically typed naming in the form of Events.Thing.BeforeCreate and so on.

Event handlers, including for a services own content type, are typically added inside service constructors.

= Thing.cs =

This is the entity description file. It describes what fields are on the entity. In a nutshell, fields are stored in the database and properties are not. There are some conveniences around field naming which is described on [[Entities|the entities page]].

= ThingService.cs =

The [[services|service]], a singleton (instanced once at startup), is used for getting/ listing/ deleting/ updating/ creating an entity. For example if you want to get hold of a user's information, you would ask the UserService. Services support C# dependency injection but can also be obtained via '''Services.Get<UserService>()''', with Services in the Startup namespace.

Often, event handlers are placed inside the service's constructor in order to validate your entity or e.g. add custom field values to it whilst it is being created. It's very common for e.g. ThingService to have Events.Thing.BeforeUpdate and so on inside its own constructor - this allows flexibility in the form of other modules actually unregistering those handlers, if it has a goal of heavily overriding default behaviours.

= ThingController.cs =

Controllers are the web API endpoints and effectively represent the main user facing frontage of your site. Just like with services, the controllers have a series of [[public Api|common convenience endpoints]] which are usually accessed with webRequest or [[Loop|Loop]] on the frontend.

= Permissions.cs =

This file is used to define the installable, base permissions for your module. It should represent the most common scenario that you expect to happen. For example, password resets should never be publicly visible - and that is going to be quite universal on most websites. These base permission grants can however be overridden in the admin panel, or with other event listeners. When creating permission grants in code, they should target the core roles, particularly if the intent is to make a portable module which can be copied or installed easily on to other projects.

For more information on what the roles are and how the grants work, take a look at the [[permissions|permissions article]].

Loop

2022-07-05T18:26:36Z

2A02:C7F:22BE:A500:498:3225:1A16:A72D:

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

=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>

Public API

2022-07-05T18:24:52Z

2A02:C7F:22BE:A500:498:3225:1A16:A72D:

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. Most of the time people use [[Loop]], Content and occasionally webRequest.

The controllers themselves are extendible - for example if you wanted /v1/user/say-hello to exist, you can do so without editing the underlying 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>

* 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

Content

2022-07-05T18:21:03Z

2A02:C7F:22BE:A500:498:3225:1A16:A72D: Created page with "<Content> is a React component which is closely related to <Loop>. They both are convenience components for obtaining data from your API; unlike Loop, Content is for grabb..."

<Content> is a React component which is closely related to <[[Loop]]>. They both are convenience components for obtaining data from your API; unlike Loop, Content is for grabbing a singular item.

<syntaxhighlight lang="js">

import Content from 'UI/Content';

...

<Content type='user' id={14}>
{
(user, loading) => {
if(loading) {
return 'Getting user data..';
}

if(!user){
return 'User was not found.';
}

return <p>{user.username}</p>;
}
}
</Content>

</syntaxhighlight>

= Primary Content =

On [[Editing_Pages|pages with primary content]], <Content> can be used to directly obtain the primary content object:

<syntaxhighlight lang="js">

import Content from 'UI/Content';

...

<Content primary>
{
(blogPost, loading) => {
if(loading) {
return 'Getting post..';
}

if(!blogPost){
return 'Post was not found.';
}

return <h1>{blogPost.title}</h1>;
}
}
</Content>

</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 Content too:

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

...

<Content type='page' id={1} includes={['creatorUser']}>
{(page, loading) => {
if(loading){
// Just an example.
return 'Loading..';
}

if(!page){
return 'Page does not exist';
}

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

Public API

2022-07-05T18:14:47Z

2A02:C7F:22BE:A500:498:3225:1A16:A72D: Created page with "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 t..."

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. Most of the time people use [[Loop]], Content and occasionally webRequest.

The controllers themselves are extendible - for example if you wanted /v1/user/say-hello to exist, you can do so without editing the underlying 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 [[filter]], where the post payload is:

<syntaxhighlight lang="json">
{"query":"Token=?", "args":["the-token-value"]}
</syntaxhighlight>

* 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 - Gets a single item by its ID. This is what <[[Content]]> uses internally, via webRequest.

Getting Started

2022-07-05T17:54:06Z

2A02:C7F:22BE:A500:498:3225:1A16:A72D:

= Introduction =

Hello! Welcome to SocialStack, a fully open source modular collection of C# and javascript code used to create modern, ultra high throughput projects which has been tried and tested by big name brands. This guide is targeted at developers so with that in mind, let's get in to it!

= Installing dependencies =

So, to get started, you'll need a few things first. Whilst SocialStack does support using multiple database engines, we currently reccommend starting with MySQL. Here's what you'll need:

* An editor capable of working with dotnet 6. For example, Visual Studio Code or Visual Studio 2022.
* Node.js 8+ which is used to run the command line tools
* MySQL version 8 is reccommended
* Git, as a new project will also be created as a git repository.

= Setting up the command line tools =

Once you've got the dependencies ready, it's time to setup the [https://www.npmjs.com/package/socialstack command line tools] which we'll shortly use to create a project. In a nutshell, it is an optional npm package which can be installed globally by running this:

<syntaxhighlight lang="bash">
npm i -g socialstack
</syntaxhighlight>

Note that this command line tool set (and node.js) are not required by production sites. It's just a convenience system for installing modules and creating projects.

It's recommended to configure socialstack tools with the ability to create MySQL databases for you on your development computer. To do this, you'll need to create a MySQL account on your MySQL instance which it can use and which has the permission to create databases and users. Here's an example of how to do that:

<syntaxhighlight lang="sql">
-- Create the user account:
CREATE USER 'sstools'@'localhost' IDENTIFIED BY 'ssto0ls.dev'; -- Invent a password here!
-- Grant that user full access to the db:
GRANT ALL PRIVILEGES ON *.* TO 'sstools'@'localhost' WITH GRANT OPTION;
FLUSH PRIVILEGES;
</syntaxhighlight>

You can then add this account to your command line tools like so, making sure the password and username matches what you used:

<syntaxhighlight lang="bash">
socialstack configure -u "sstools" -p "ssto0ls.dev"
</syntaxhighlight>

This is a global thing, so once you've done it you won't need to do it again. You're ready to create a project!

= Creating a project =

With the command line tools ready to go, you can then go ahead and create a project like so:

<syntaxhighlight lang="bash">
cd myProjectDirectory
socialstack create helloworld
</syntaxhighlight>

This will ask if you want to install any additional modules straight away. Just skip this by pressing enter. If your configuration is ok, a database will be created for you as well as the project.

= Starting it up =

With your project created, start it up in a suitable editor (typically that is Visual Studio Code, or Visual Studio 2022) or via the command line by starting the Api.csproj project. Whilst it starts, it will give you a few bits of information:

* It will list which services (provided by modules) are installed and starting up.
* It will create the database tables and any initial data needed by those services. This is fully automated.
* It will let you know that a default administration account was created, and what its details are. This happens once; if you missed it you can check the site_user table in your database as it will have one row and the default password is simply '''admin'''.
* It lets you know how to get to the instance. This defaults to http://localhost:5050/ which you can navigate to in a browser.
* It compiles the UI and indicates when its done. This is usually the very last thing that appears and the UI won't display to you until it completes.

= Going exploring =

With your project started, head over to http://localhost:5050/ in a browser and you should see a barebones homepage with a welcome message. This brings us to the first key point:

> Pages in SocialStack entirely come from the editable CMS area - this includes administration panel pages too. There's no fighting against surrounding page templates as the root component(s) on the page are whatever you choose. More on components later!

So, let's head in to the administration panel and make some changes. Head over to http://localhost:5050/en-admin/ in a browser and you should see a login panel. At this point use the generated administration account to login which will currently default to:

* Username: '''admin'''
* Password: '''admin'''

Once you've logged in, in the top left corner is a menu which you can use to get to the list of pages. On this list, find the homepage and open the page editor. [[Editing Pages|Editing a page]] (and more generally how they actually work) is a broad topic on its own so please take a moment to check out [[Editing Pages|that article]] first, then head back here when you're ready.

= Creating API modules =

Next is a good point to have a go at creating your own API module. A video version of this part of the guide is [https://www.youtube.com/watch?v=4rrfyg4Wk_g available here]. We'll make something like a list of frequently asked questions. SocialStack tools has a [[generate|generate command]] which creates the basic scaffolding of a new API module for you, so let's generate that now:

<syntaxhighlight lang="bash">
socialstack generate Api/FrequentlyAskedQuestions
</syntaxhighlight>

All this does is create a directory with some generated files; i.e. copy/pasting or manually creating one of those directories has the same outcome as there are no hidden indexes or other files to update. In this case, it will be in the directory ProjectRoot/Api/FrequentlyAskedQuestions. It should also appear in the explorer inside an IDE such as Visual Studio. Inside this folder, you'll see a small collection of files with different purposes, which are explored in [[API Modules|this section of the wiki]]. Take a look there, then head back here when you're ready.

Next we'll need to add fields to the generated FAQ type as so far it is just an empty shell. To do that, edit FrequentlyAskedQuestion.cs and add 2 fields:

<syntaxhighlight lang="csharp">
/// <summary>
/// The question people ask.
/// </summary>
[Localized]
public string Question;

/// <summary>
/// The answer.
/// </summary>
[Localized]
public string AnswerJson;
</syntaxhighlight>

It would also help to be able to see and edit these FAQ's via the admin panel, so edit FrequentlyAskedQuestionService.cs and uncomment the admin panel pages line.

As you have made changes to C#, you'll need to restart the API for the changes to take effect. The easiest way is to stop/ start the running project in your IDE. When it starts back up, head back in to the admin panel at http://localhost:5050/en-admin/ and you should see a new link in the menu to your newly created FAQ's. Have a go at creating and editing some, and then when you're ready head back over here.

We now have some data in your database and an ability to see and manipulate it with the admin panel. So far so good!

= Creating frontend UI modules =

Next it would be great if you could also list out your FAQs on the actual website so let's explore that next. This part of the guide is also covered in [https://www.youtube.com/watch?v=YyFNVPwbIz4 a video about Loop], however just like before, it all starts with a generate command:

<syntaxhighlight lang="bash">
socialstack generate UI/Faq/List
</syntaxhighlight>

This will create a directory in ProjectRoot/UI/Source/Faq/List containing 2 files; a React component and some CSS to go with it.

Note: Changes to the UI are compiled immediately whenever the API is running. That includes creating files, generating modules, editing files and so on - and the updates are usually near instant too.

There's 3 main convenience ways to access data from the API via a React component - [[Loop|Loop]], Content and webRequest. [[Loop|Loop]] is for a list of things, Content is for just one and webRequest is for any other situation in e.g. useEffect or componentDidMount where you need to grab data without being in a React render function. [[Loop|Loop]] and Content simply sit on top of webRequest and use the [[Public API|public part of the projects API]] (that controllers in your API, which use the services to return the data). We want a list of FAQs here, so we'll use Loop. Here's an example:

<syntaxhighlight lang="js">

import Canvas from 'UI/Canvas';
import Loop from 'UI/Loop';

export default function List(props){
// Loops over the FAQs from the API and also uses a
// canvas to display the answer which is visual editor content.
return <Loop over='frequentlyaskedquestion'>{
faq => {
return <div>
<h1>{faq.question}</h1>
<Canvas>{faq.answerJson}</Canvas>
</div>;
}
}</Loop>;

}

Loop.propTypes = {}; // No props used on this list.

</syntaxhighlight>

Save the file, and then because we specified an empty propTypes object, the page editor will now recognise the component and list it in the add window. So if you head back over to the admin panel, you'll then be able to add this component to the page. Alternatively if you prefer writing the JSON, the page JSON looks like this:

<syntaxhighlight lang="json">
{"t":"UI/Faq/List"}
</syntaxhighlight>

Notice that the name matches what you generated, and is the same as the filepath minus the "Source" folder.

Services

2022-07-05T17:37:29Z

2A02:C7F:22BE:A500:498:3225:1A16:A72D: Created page with "Services are the way how parts of a SocialStack API communicate with each other. They are essentially the code to code interfaces between different content types or bits of fu..."

Services are the way how parts of a SocialStack API communicate with each other. They are essentially the code to code interfaces between different content types or bits of functionality inside your API. They are instanced once at startup and can can use dependency injection to access other services:

<syntaxhighlight lang="csharp">

public ThingService(UserService userService) {

Events.Thing.BeforeCreate.AddEventListener(async (Context context, Thing thing) => {
if(thing == null){
return null;
}

// Get the creator user (this is likely the same as context.User).
// Throws if context user is not permitted to access this data.
var aUser = await userService.Get(context, thing.UserId);

// Do something with aUser here!

return thing;
});

}

</syntaxhighlight>

= Getting a service =

There's two ways to get a service - either by C# dependency injection:

<syntaxhighlight lang="csharp">
public ThingService(UserService userService) {
</syntaxhighlight>

Or when dependency injection isn't available due to either a cyclical dependency or simply being outside the scope of another service, you can use Services.Get. Note that this call will return null if the services have not been instanced yet; you can guarantee success if you wait until at least the Events.Service.AfterStart event triggers.

<syntaxhighlight lang="csharp">
var userService = Services.Get<UserService>(); // In Startup namespace
</syntaxhighlight>

= Common Features =

Services contain a variety of common features for doing common tasks such as getting an object, creating one etc. Here's the main usage examples of each:

* Get - Get an entity from the service by its ID which is usually a uint.

<syntaxhighlight lang="csharp">
uint entityId = 14;
var entity = await aService.Get(context, entityId);
</syntaxhighlight>

entityId could be e.g. a user ID, aService is the UserService and entity is therefore a User object.

* Delete - Deletes an entity by its ID which is usually a uint.

<syntaxhighlight lang="csharp">
uint entityId = 14;
await aService.Delete(context, entityId);

// Or:
await aService.Delete(context, entity);
</syntaxhighlight>

entityId could be e.g. a user ID, aService is the UserService and entity is therefore a User object.

* Where - Used to list multiple entities from the service with a [[filter|filter string]]. Note that it is possible to entirely avoid all allocations with this part of the API - ListAll is just one of the available methods.

<syntaxhighlight lang="csharp">
string token = "";
var listOfResults = await aService.Where("Token=?").Bind(tokenString).ListAll(context);
</syntaxhighlight>

* Create - Creates an entity in the target service.

<syntaxhighlight lang="csharp">

var thingEntity = await aService.Create(context, new Thing(){
Token = "123123"
});

</syntaxhighlight>

* Update - Updates an entity in the target service. Update uses a callback mechanism as this helps avoid allocations and allows internal field comparisons to happen to be able to easily identify which fields have changed.

<syntaxhighlight lang="csharp">
var thingEntity = await aService.Update(context, thingEntity, (Context context, Thing toUpdate, Thing original) => {
toUpdate.Token = "something-else";
});

</syntaxhighlight>

= Service Permissions =

The permissions system is also modular in that it adds an event handler on the various core events (like create, delete and so on) for a particular content type. This means that when you access a service from some other part of the code, your current [[API Context|context]] must be permitted to access it. It also means that the event handler can be removed should you wish to do so, although naturally, removing the permission system is likely not a good idea on any project!

== Ignoring the permissions ==

You can, however, ask a particular request to ignore the permission system all together. This effectively just makes the above event handler skip itself. This happens in situations where the incoming user is not permitted to generally access a certain piece of data, but the API internally needs to check something. Password resets are one example - the user (and their context) is anonymous, and anonymous users certainly shouldn't be able to publicly view any password resets. They can however potentially access one of them if a token value is correct, so that token lookup can be done by ignoring the permission system. That is done like so:

<syntaxhighlight lang="csharp">

// Won't throw with a permissions failure
var aUser = await userService.Get(context, thing.UserId, DataOptions.IgnorePermissions);

</syntaxhighlight>

DataOptions is generally available on many service methods - Create, Get, Where and so on - so you can skip over the permission check whenever necessary.

API Modules

2022-07-05T17:16:43Z

2A02:C7F:22BE:A500:498:3225:1A16:A72D: Created page with "A newly regularly generated API module has 5 files. Assuming you did '''socialstack generate Api/Things''', here's what each of them is for: = Events.cs = When something hap..."

A newly regularly generated API module has 5 files. Assuming you did '''socialstack generate Api/Things''', here's what each of them is for:

= Events.cs =

When something happens in your API, an event is triggered. By default all entities have a common set of events for things like creation/ updates/ deletion etc, but it can be extended by defining a custom event type. This is detailed more on [[Events|the page about events]]. One of the core goals of events in SocialStack is for them to be extremely fast and also easy to use with IDE autofilling, so these auto generated files exist to enable those statically typed naming in the form of Events.Thing.BeforeCreate and so on.

Event handlers, including for a services own content type, are typically added inside service constructors.

= Thing.cs =

This is the entity description file. It describes what fields are on the entity. In a nutshell, fields are stored in the database and properties are not. There are some conveniences around field naming which is described on [[Entities|the entities page]].

= ThingService.cs =

The [[services|service]], a singleton (instanced once at startup), is used for getting/ listing/ deleting/ updating/ creating an entity. For example if you want to get hold of a user's information, you would ask the UserService. Services support C# dependency injection but can also be obtained via '''Services.Get<UserService>()''', with Services in the Startup namespace.

Often, event handlers are placed inside the service's constructor in order to validate your entity or e.g. add custom field values to it whilst it is being created. It's very common for e.g. ThingService to have Events.Thing.BeforeUpdate and so on inside its own constructor - this allows flexibility in the form of other modules actually unregistering those handlers, if it has a goal of heavily overriding default behaviours.

= ThingController.cs =

Controllers are the web API endpoints and effectively represent the main user facing frontage of your site. Just like with services, the controllers have a series of common convenience endpoints which are usually accessed with webRequest or [[Loop|Loop]] on the frontend.

= Permissions.cs =

This file is used to define the installable, base permissions for your module. It should represent the most common scenario that you expect to happen. For example, password resets should never be publicly visible - and that is going to be quite universal on most websites. These base permission grants can however be overridden in the admin panel, or with other event listeners. When creating permission grants in code, they should target the core roles, particularly if the intent is to make a portable module which can be copied or installed easily on to other projects.

For more information on what the roles are and how the grants work, take a look at the [[permissions|permissions article]].

Getting Started

2022-07-05T16:59:57Z

2A02:C7F:22BE:A500:498:3225:1A16:A72D:

Modules

2022-07-05T13:00:04Z

2A02:C7F:22BE:A500:498:3225:1A16:A72D: Created page with "Modules in SocialStack are the main way to create small, portable, easy to test units of code. The best way to create a new one is via the generate command, but y..."

Modules in SocialStack are the main way to create small, portable, easy to test units of code. The best way to create a new one is via the [[generate|generate command]], but you can also install public ones. Importantly a module should be self-contained as much as possible with the smallest dependency footprint.

= Making C# code modular =

As C# is a statically typed language, it is inherently more rigid than languages like Javascript on the frontend. However, '''partial classes''' are very useful for this end goal of making extensible units of code. For this reason, every class outputted by the generate command is partial.

Why are partial classes useful? Let's take the User type for example. Modules want to extend this one all the time - a 2 factor authentication plugin may want to store some data in the user objects, modules for adding names and addresses and so on. Because the installed User class is partial, you can add fields to it without editing the original file. By adding fields to the User type, any User reference you end up with - either via the API, admin panel, events etc - will then have that field on it. Because the database storage mechanism is also generic, it will get automatically stored too. Therefore, adding a field to the User type is as simple as adding a file like this:

<syntaxhighlight lang="csharp">
namespace Api.Users;

public partial class User{
public string MyCustomField;
}
</syntaxhighlight>

Secondly, we also have a very fast and flexible events system inside the API. When a user object is created, an event is triggered (specifically that is Events.User.BeforeCreate and AfterCreate), which then any module can subscribe to. Just like with the content type itself, common events are fully automatic but you can also create your own.

Event listeners should be added once at startup. This means you'll either put them in service constructors, or in special EventListener classes which are constructed as a singleton for you.

<syntaxhighlight lang="csharp">
[EventListener]
public class MyEventListener {

public MyEventListener(){

Events.User.BeforeCreate.AddEventListener(async (Context context, User user) => {
if(user == null){
return null;
}

// can await something here if needed!
// Because we're in a beforeCreate, we can edit the object including populating custom fields or validating them.
// If we have a validation failure, throw a PublicException.
// throw new PublicException("Incorrect date of birth", "dob/invalid");
return user;
});
}
}
</syntaxhighlight>

Editing Pages

2022-07-05T12:39:57Z

2A02:C7F:22BE:A500:498:3225:1A16:A72D:

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

== 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>

= 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

2022-07-05T12:39:37Z

2A02:C7F:22BE:A500:498:3225:1A16:A72D:

Pages in SocialStack are a [[Content Types|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 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.

== 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>

= 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}

Generate

2022-07-05T12:34:25Z

2A02:C7F:22BE:A500:498:3225:1A16:A72D: Created page with "SocialStack generate is probably the most convenient command to know and use. Based on the name of the module you want to make, it will generate the files for eith..."

SocialStack generate is probably the most convenient command to know and use. Based on the name of the [[Modules|module]] you want to make, it will generate the files for either a React component (a function hook based one by default) or a C# Api one, optionally as a content type.

The command is either the full word "generate" or "g" for short.

== React component ==

<syntaxhighlight lang="bash">
socialstack g UI/AboutUs
</syntaxhighlight>

<syntaxhighlight lang="bash">
socialstack g Admin/MaintenanceArea
</syntaxhighlight>

<syntaxhighlight lang="bash">
socialstack g Email/MarketingGrid
</syntaxhighlight>

The files are placed in ProjectRoot/UI/Source, ProjectRoot/Admin/Source or ProjectRoot/Email/Source respectively.

By default it will create the component and a scss styling file too. Both files contain examples of commonly used features from there.

== C# Content type called "Cars" ==

<syntaxhighlight lang="bash">
socialstack g Api/Cars
</syntaxhighlight>

The files are placed in ProjectRoot/Api. When creating a content type like this, the main file you edit next is the e.g. CarService.cs where you can then comment out the line which generates admin panel pages for you, and then e.g. Car.cs which describes the fields to store (and edit in the admin panel) for the content type. The content type file contains commented out examples of common fields too, like a name.

== C# basic service ==

<syntaxhighlight lang="bash">
socialstack g Api/MarketingEmailTimer
</syntaxhighlight>

The files are placed in ProjectRoot/Api. These things simply start when the services do and are a good place to put generic contentless behaviour which can optionally have configuration via GetConfig.

Editing Pages

2022-07-05T12:24:36Z

2A02:C7F:22BE:A500:498:3225:1A16:A72D: Created page with "Pages in SocialStack are a content type with a JSON structure that describes the components on the page. We call this JSON structure Canvas..."

Pages in SocialStack are a [[Content Types|content type]] with a JSON structure that describes the [[Components|components]] on the page. We call this JSON structure [[Canvas JSON|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 JSON|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 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 JSON|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.

== 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>

= 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}

Getting Started

2022-07-05T11:54:40Z

2A02:C7F:22BE:A500:498:3225:1A16:A72D:

Getting Started

2022-07-05T11:47:51Z

2A02:C7F:22BE:A500:498:3225:1A16:A72D:

= Introduction =

Hello! Welcome to SocialStack, a fully open source modular collection of C# and javascript code used to create modern, ultra high throughput projects which has been tried and tested by big name brands.

= Installing dependencies =

So, to get started, you'll need a few things first. Whilst SocialStack does support using multiple database engines, we currently reccommend starting with MySQL. Here's what you'll need:

* An editor capable of working with dotnet 6. For example, Visual Studio Code or Visual Studio 2022.
* Node.js 8+ which is used to run the command line tools
* MySQL version 8 is reccommended
* Git, as a new project will also be created as a git repository.

= Setting up the command line tools =

Once you've got the dependencies ready, it's time to setup the [https://www.npmjs.com/package/socialstack command line tools] which we'll shortly use to create a project. In a nutshell, it is an optional npm package which can be installed globally by running this:

<syntaxhighlight lang="bash">
npm i -g socialstack
</syntaxhighlight>

Note that this command line tool set (and node.js) are not required by production sites. It's just a convenience system for installing modules and creating projects.

It's recommended to configure socialstack tools with the ability to create MySQL databases for you on your development computer. To do this, you'll need to create a MySQL account on your MySQL instance which it can use and which has the permission to create databases and users. Here's an example of how to do that:

<syntaxhighlight lang="sql">
-- Create the user account:
CREATE USER 'sstools'@'localhost' IDENTIFIED BY 'ssto0ls.dev'; -- Invent a password here!
-- Grant that user full access to the db:
GRANT ALL PRIVILEGES ON *.* TO 'sstools'@'localhost' WITH GRANT OPTION;
FLUSH PRIVILEGES;
</syntaxhighlight>

You can then add this account to your command line tools like so, making sure the password and username matches what you used:

<syntaxhighlight lang="bash">
socialstack configure -u "sstools" -p "ssto0ls.dev"
</syntaxhighlight>

This is a global thing, so once you've done it you won't need to do it again. You're ready to create a project!

= Creating a project =

With the command line tools ready to go, you can then go ahead and create a project like so:

<syntaxhighlight lang="bash">
cd myProjectDirectory
socialstack create helloworld
</syntaxhighlight>

This will ask if you want to install any additional modules straight away. Just skip this by pressing enter. If your configuration is ok, a database will be created for you as well as the project.

= Starting it up =

With your project created, start it up in a suitable editor (typically that is Visual Studio Code, or Visual Studio 2022) or via the command line by starting the Api.csproj project. Whilst it starts, it will give you a few bits of information:

* It will list which services (provided by modules) are installed and starting up.
* It will create the database tables and any initial data needed by those services. This is fully automated.
* It will let you know that a default administration account was created, and what its details are. This happens once; if you missed it you can check the site_user table in your database as it will have one row and the default password is simply '''admin'''.
* It lets you know how to get to the instance. This defaults to http://localhost:5050/ which you can navigate to in a browser.
* It compiles the UI and indicates when its done. This is usually the very last thing that appears and the UI won't display to you until it completes.

= Going exploring =

With your project started, head over to http://localhost:5050/ in a browser and you should see a barebones homepage with a welcome message. This brings us to the first key point:

> Pages in SocialStack entirely come from the editable CMS area - this includes administration panel pages too. There's no fighting against surrounding page templates as the root component(s) on the page are whatever you choose. More on components later!

So, let's head in to the administration panel and make some changes. Head over to http://localhost:5050/en-admin/ in a browser and you should see a login panel. At this point use the generated administration account to login which will currently default to:

* Username: '''admin'''
* Password: '''admin'''

Once you've logged in, in the top left corner is a menu which you can use to get to the list of pages.

Getting Started

2022-07-05T11:46:08Z

2A02:C7F:22BE:A500:498:3225:1A16:A72D: /* Introduction */

= Introduction =

Hello! Welcome to SocialStack, a fully open source modular collection of C# and javascript code used to create modern, ultra high throughput projects which has been tried and tested by big name brands.

= Installing dependencies =

So, to get started, you'll need a few things first. Whilst SocialStack does support using multiple database engines, we currently reccommend starting with MySQL. Here's what you'll need:

* An editor capable of working with dotnet 6. For example, Visual Studio Code or Visual Studio 2022.
* Node.js 8+ which is used to run the command line tools
* MySQL version 8 is reccommended
* Git, as a new project will also be created as a git repository.

= Setting up the command line tools =

Once you've got the dependencies ready, it's time to setup the [https://www.npmjs.com/package/socialstack command line tools] which we'll shortly use to create a project. In a nutshell, it is an optional npm package which can be installed globally by running this:

<syntaxhighlight lang="bash">
npm i -g socialstack
</syntaxhighlight>

Note that this command line tool set (and node.js) are not required by production sites. It's just a convenience system for installing modules and creating projects.

It's recommended to configure socialstack tools with the ability to create MySQL databases for you on your development computer. To do this, you'll need to create a MySQL account on your MySQL instance which it can use and which has the permission to create databases and users. Here's an example of how to do that:

<syntaxhighlight lang="sql">
-- Create the user account:
CREATE USER 'sstools'@'localhost' IDENTIFIED BY 'ssto0ls.dev'; -- Invent a password here!
-- Grant that user full access to the db:
GRANT ALL PRIVILEGES ON *.* TO 'sstools'@'localhost' WITH GRANT OPTION;
FLUSH PRIVILEGES;
</syntaxhighlight>

You can then add this account to your command line tools like so, making sure the password and username matches what you used:

<syntaxhighlight lang="bash">
socialstack configure -u "sstools" -p "ssto0ls.dev"
</syntaxhighlight>

This is a global thing, so once you've done it you won't need to do it again. You're ready to create a project!

= Creating a project =

With the command line tools ready to go, you can then go ahead and create a project like so:

<syntaxhighlight lang="bash">
cd myProjectDirectory
socialstack create helloworld
</syntaxhighlight>

This will ask if you want to install any additional modules straight away. Just skip this by pressing enter. If your configuration is ok, a database will be created for you as well as the project.

= Starting it up =

With your project created, start it up in a suitable editor (typically that is Visual Studio Code, or Visual Studio 2022) or via the command line by starting the Api.csproj project. Whilst it starts, it will give you a few bits of information:

* It will list which services (provided by modules) are installed and starting up.
* It will create the database tables and any initial data needed by those services. This is fully automated.
* It will let you know that a default administration account was created, and what its details are. This happens once; if you missed it you can check the site_user table in your database as it will have one row and the default password is simply `admin`.
* It lets you know how to get to the instance. This defaults to http://localhost:5050/ which you can navigate to in a browser.
* It compiles the UI and indicates when its done. This is usually the very last thing that appears and the UI won't display to you until it completes.

= Going exploring =

With your project started, head over to http://localhost:5050/ in a browser and you should see a barebones homepage with a welcome message. This brings us to the first key point:

> Pages in SocialStack entirely come from the editable CMS area - this includes administration panel pages too. There's no fighting against surrounding page templates as the root component(s) on the page are whatever you choose. More on components later!

So, let's head in to the administration panel and make some changes. Head over to http://localhost:5050/en-admin/ in a browser and you should see a login panel. At this point use the generated administration account to login which will currently default to:

* Username: `admin`
* Password: `admin`

Architecture

2022-07-05T11:23:11Z

2A02:C7F:22BE:A500:498:3225:1A16:A72D:

SocialStack is primarily a fully open source dotnet core 6 API. By default it comes with a React frontend installed which can also be simply ignored or removed if you wish to use it headless instead.

The structure of all parts of a SocialStack project is designed to be highly modular - all of the core features and functionality are in small, replaceable modules which originate from [https://github.com/socialstack-core/modules this GitHub repository].

Creating projects, which primarily just installs a default package of modules, as well as installing or uninstalling modules, is handled by [https://www.npmjs.com/package/socialstack SocialStack tools] - an open source command line toolset written in javascript which is typically the best place to start when working with SocialStack.