Modules - Revision history

Luke at 12:20, 1 December 2022

2022-12-01T12:20:22Z

← Older revision		Revision as of 12:20, 1 December 2022
Line 59:		Line 59:

	"Defaults" is the package which gets installed when a new project is generated.		"Defaults" is the package which gets installed when a new project is generated.

			= Adding dependencies =

			Any published module can contain a package.json file which lists other modules to install when this module is being installed. It's based on the node.js package.json file and is structured like so:

			<syntaxhighlight lang="json">
			{
			"dependencies": [
			"UI/Alert",
			"nuget:a-nuget-package"
			]
			}
			</syntaxhighlight>

			You can either use the name of another module, an npm package or a nuget package. Installing npm packages this way is currently experimental.

	= Editing changes =		= Editing changes =

Luke: /* Publishing a module */

2022-12-01T12:11:12Z

Publishing a module

← Older revision		Revision as of 12:11, 1 December 2022
Line 45:		Line 45:

	Note that it's important to add the module entry first - that's because the commit handler specifically checks if committed changes are within known module paths and if so, then generates the new installable zip. If you create the module entry afterwards, just make a commit to any of the files in your modules path and it will then update for you.		Note that it's important to add the module entry first - that's because the commit handler specifically checks if committed changes are within known module paths and if so, then generates the new installable zip. If you create the module entry afterwards, just make a commit to any of the files in your modules path and it will then update for you.

			No modules are silly modules! If you'd like to share your code between projects you're always invited to publish it.

	= Installing a published module =		= Installing a published module =

Luke: /* Two modules with the same name */

2022-12-01T11:57:05Z

Two modules with the same name

← Older revision		Revision as of 11:57, 1 December 2022
Line 92:		Line 92:
	Because it ignores the word ThirdParty, it certainly can arise where two modules have the same apparent name. In the API directory this won't compile because C# requires unique class names. In UI directories though, the code will always favour the firstparty module. For example, let's say you make a copy of the Alert module but keep the original still in the project:		Because it ignores the word ThirdParty, it certainly can arise where two modules have the same apparent name. In the API directory this won't compile because C# requires unique class names. In UI directories though, the code will always favour the firstparty module. For example, let's say you make a copy of the Alert module but keep the original still in the project:

	UI/Source/Alert		'''UI/Source/Alert''' and '''UI/Source/ThirdParty/Alert'''
	UI/Source/ThirdParty/Alert

	If you then attempt to import it:		If you then attempt to import it:

Luke: /* Editing changes */

2022-12-01T11:55:51Z

Editing changes

← Older revision		Revision as of 11:55, 1 December 2022
Line 63:		Line 63:

	Typically when making changes to a module that originated from the public repository, it's best to make the changes generic such that they can be contributed (by simply committing them to the github repo, or make a pull request there). For example if you're editing a UI module it's best to expose a React prop instead of adding your new project specific value in the source. If you're editing an API module, e.g. add a feature flag as a [[Configuration\|config option]].		Typically when making changes to a module that originated from the public repository, it's best to make the changes generic such that they can be contributed (by simply committing them to the github repo, or make a pull request there). For example if you're editing a UI module it's best to expose a React prop instead of adding your new project specific value in the source. If you're editing an API module, e.g. add a feature flag as a [[Configuration\|config option]].

			If you're making substantial changes - e.g. use of the thirdparty module was more just as a structure guideline rather than using it for its functionality - then it's best to either name it something new, or make it firstparty in your project by simply moving the directory.

			= Importing and referencing modules =

			Socialstack's module compiler tries to do as much of the plumbing for you here as possible. As a result, a module simply needs to exist to be compiled in the C# project, and it simply needs to exist in the UI tree to be importable on the frontend. A module located at:

			UI/Source/ThirdParty/Alert

			Can be imported like so:

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

			This is because it '''actively ignores the word "ThirdParty"''' as well as the root "Source" directory. The same is true for the Admin directory too:

			Admin/Source/ThirdParty/Templates

			<syntaxhighlight lang="js">
			import Templates from 'Admin/Templates';
			</syntaxhighlight>

			The only difference is the admin modules are only available specifically on the pages of the admin panel to help minimise bloat.

			== Two modules with the same name ==

			Because it ignores the word ThirdParty, it certainly can arise where two modules have the same apparent name. In the API directory this won't compile because C# requires unique class names. In UI directories though, the code will always favour the firstparty module. For example, let's say you make a copy of the Alert module but keep the original still in the project:

			UI/Source/Alert
			UI/Source/ThirdParty/Alert

			If you then attempt to import it:

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

			The first party one will "win" every time. This is resolved on a file by file basis such that files in the ThirdParty copy but not in the first party one will still be usable.

Luke at 11:46, 1 December 2022

2022-12-01T11:46:47Z

← Older revision		Revision as of 11:46, 1 December 2022
Line 39:		Line 39:
	}		}
	</syntaxhighlight>		</syntaxhighlight>

			= Publishing a module =

			Modules can be shared to the world via [https://github.com/socialstack-core/modules the github repository]. You'll need to [https://cloud.socialstack.dev/en-admin/module/ create a new module entry on socialstack cloud first] which should be the desired installable name and the path within the "Core" repository. Adding a new entry is currently non-public because of this socialstack cloud dependency but will be fully public in the future. You can however edit the socialstack command line tools to point at something other than socialstack cloud to have a completely custom repository/ a superset of installable modules.

			Note that it's important to add the module entry first - that's because the commit handler specifically checks if committed changes are within known module paths and if so, then generates the new installable zip. If you create the module entry afterwards, just make a commit to any of the files in your modules path and it will then update for you.

			= Installing a published module =

			The socialstack command line tools have an install command that let you install a module from [https://github.com/socialstack-core/modules the github repository]. Typically use the path to the module that you want, like so:

			<syntaxhighlight lang="bash">
			socialstack install Api/Pages
			socialstack install UI/Alert
			socialstack install Defaults
			</syntaxhighlight>

			"Defaults" is the package which gets installed when a new project is generated.

			= Editing changes =

			When installing a module its files are copied into your project in a directory called ThirdParty. You can edit the files in there, but it's generally recommended to avoid doing so unless necessary. This is because when you want to upgrade your project, the changes will be something you may end up needing to merge.

			Typically when making changes to a module that originated from the public repository, it's best to make the changes generic such that they can be contributed (by simply committing them to the github repo, or make a pull request there). For example if you're editing a UI module it's best to expose a React prop instead of adding your new project specific value in the source. If you're editing an API module, e.g. add a feature flag as a [[Configuration\|config option]].

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

2022-07-05T13:00:04Z

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

New page

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>