Getting Started

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.
• .NET Core 6.0 SDK. If you're not sure if you already have this installed, you can run dotnet --list-sdks to find out.

Setting up the command line tools

Once you've got the dependencies ready, it's time to setup the 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:

npm i -g socialstack

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:

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

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

socialstack configure -u "sstools" -p "ssto0ls.dev"

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:

cd myProjectDirectory
socialstack create helloworld

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 a page (and more generally how they actually work) is a broad topic on its own so please take a moment to check out 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 available here. We'll make something like a list of frequently asked questions. SocialStack tools has a generate command which creates the basic scaffolding of a new API module for you, so let's generate that now:

socialstack generate Api/FrequentlyAskedQuestions

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

/// <summary>
/// The question people ask.
/// </summary>
[Localized]
public string Question;

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

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 a video about Loop, however just like before, it all starts with a generate command:

socialstack generate UI/Faq/List

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, Content and webRequest. 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 and Content simply sit on top of webRequest and use the 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:

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.

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:

{"t":"UI/Faq/List"}

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