SocialStack - User contributions [en-gb]

Filters

2022-08-11T20:12:38Z

72.201.192.210: /* Filter functions */

Filters are a query-like mechanism for filtering out results from a list endpoint. At their core, they are textual and support a set of arguments.

= Filter examples =

A textual filter with arguments is like so:

<syntaxhighlight lang="sql">
(UserId=? or UserId=?) and CreatedUtc>?
</syntaxhighlight>

It is not case sensitive. Filters in the permission system do not support these ? arguments (as it wouldn't know where to bind the value from).

Typically you'll see this textual form of filter inside a Where() call in the C# API:

<syntaxhighlight lang="csharp">
uint userId = 14;

var listOfThingsByThisUser = await Where("UserId=?").Bind(userId).ListAll(context);
</syntaxhighlight>

.Bind() is used to bind the actual value of an argument. Values are bound in this way such that the filter string is a constant and can benefit from being precompiled. Indeed, the whole filter system is built to be entirely non-allocating, as the Bind calls internally set your provided value onto an compiled object field, with that object originating from a pool for the given cached filter.

= JS filter notation =

Filters can also be constructed by the frontend, most often by [[Loop]]. In this scenario, a convenience filter notation is also available - it'll take the object notation you provide, and then convert it into the textual format with arguments. Here's some examples:

<syntaxhighlight lang="js">
{
where: {
userId: 14
}
}
</syntaxhighlight>

[[#Operators]] can be used by passing an object:

<syntaxhighlight lang="js">
{
where: {
userId: {
greaterThan: 14
}
}
}
</syntaxhighlight>

Or statements are represented with an array:

<syntaxhighlight lang="js">
{
where: [{
userId: 14
},
{
userId: 16
}]
}
</syntaxhighlight>

And statements are performed by providing multiple field values:

<syntaxhighlight lang="js">
{
where: {
userId: 14,
createdUtc: {
greaterThan: yesterday /* yesterday is a JS Date */
}
}
}
</syntaxhighlight>

If you need more expressive power, you can also directly specify the query and args:

<syntaxhighlight lang="js">
{
query: "UserId=?",
args: [14]
}
</syntaxhighlight>

= Operators =

Filters support a variety of operators for comparisons:

* Greater than
* Field>? (query notation)
* {greaterThan: x} (JS notation)

* Less than
* Field<? (query notation)
* {lessThan: x} (JS notation)

* Greater than or equal
* Field>=? (query notation)
* {greaterThanOrEqual: x} (JS notation)
* {geq: x} (JS notation)

* Less than or equal
* Field<=? (query notation)
* {lessThanOrEqual: x} (JS notation)
* {leq: x} (JS notation)

* Equals
* Field=? (query notation)
* x (JS notation)
* {equals: x} (JS notation)

* Not
* Field!=? (query notation)
* !( .... ) (query notation)
* {not: x} (JS notation)

* Starts with (textual values only)
* Field startsWith ? (query notation)
* {startsWith: x} (JS notation)

* Ends with (textual values only)
* Field endsWith ? (query notation)
* {endsWith: x} (JS notation)

* Contains (textual values only)
* Field contains ? (query notation)
* {contains: x} (JS notation)

= Arrays =

Todo: Using [?] inside a filter for array-of-things comparisons.

= Filter functions =

Most often seen in the permission system. These are functions used within a query filter. Filter functions are generic and can also be custom defined by installable modules if you need another. Variations of UserPermits ("CompanyPermits" etc) are quite common.

* IsSelf()
* HasUserPermit()
* HasRolePermits()
* IsIncluded()
* On(...)

Todo: describing the above, particularly On and IsIncluded

Includes

2022-08-11T17:10:14Z

72.201.192.210: /* Lists */

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

=Frontend Usage=

Typically includes are used from either Loop or Content:

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

...

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

</syntaxhighlight>

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

...

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

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

</syntaxhighlight>

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

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

=API Usage=

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

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

=Nested Includes=

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

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

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

=Wildcards=

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

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

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

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

=Making something includable=

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

==Single objects==

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

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

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

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

For example, this is how creatorUser is actually defined:

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

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

==Lists==

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

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

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

===Explicit Lists===

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

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

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

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

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

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

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

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

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

=On: Includes without the entity=

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

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

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

=Permissions=

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

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

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

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

...

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

Automations

2022-08-02T18:43:06Z

72.201.192.210: /* Usage tips */

Automations are a mechanism in SocialStack to create a task which runs on some defined schedule. They're also known as "background jobs" or "daemons". The schedule is defined using a [https://en.wikipedia.org/wiki/Cron cron expression].

= Usage =

First, install the Automations module:

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

That adds the Events.Automation method to your project, which can then be used like so:

<syntaxhighlight lang="csharp">
using Api.Automations; // for AutomationRunInfo

..

// If your automation doesn't need to do anything async:
Events.Automation("once_a_second", "* * * * * ? *")
.AddEventListener((Context context, AutomationRunInfo info) => {

System.Console.WriteLine("- Runs once a second -");

return new ValueTask<AutomationRunInfo>(info);

});

// With async:
Events.Automation("once_a_second", "* * * * * ? *")
.AddEventListener(async (Context context, AutomationRunInfo info) => {

System.Console.WriteLine("- Runs once a second -");

await _someOtherService.DoSomething(context);

return info;

});

</syntaxhighlight>

Note that Automation has two args - a name and a schedule. The name is such that your automation can be triggered by hand separately, for example if you need a background job to run "now" rather than waiting for the schedule to trigger it.

Because of the name, it is also possible to add additional handlers to a particular job run. For example if you know a job is called "update_certificate" then you can add an additional handler to the event like so:

<syntaxhighlight lang="csharp">

Events.Automation("update_certificate")
.AddEventListener((Context context, AutomationRunInfo info) => {

System.Console.WriteLine("- This runs immediately after the update_certificate automation. -");

return new ValueTask<AutomationRunInfo>(info);

}, 11); // Priority 11 ensures we for certain will happen after the main automations listener(s) occur.

</syntaxhighlight>

= Usage tips =

* Online cron expression editors can help you [https://www.google.com/search?q=cron+expression+editor get the expression you need]. NOTE: when selecting a cron formater, use one that supports 7 fields - 6 field cron will result in an incomplete expression

* The time is always in UTC, meaning it is not affected by local timezone changes such as daylight savings and it is easier to sync larger jobs within a global cluster.

Automations

2022-08-02T18:05:37Z

72.201.192.210: /* Usage tips */

Automations are a mechanism in SocialStack to create a task which runs on some defined schedule. They're also known as "background jobs" or "daemons". The schedule is defined using a [https://en.wikipedia.org/wiki/Cron cron expression].

= Usage =

First, install the Automations module:

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

That adds the Events.Automation method to your project, which can then be used like so:

<syntaxhighlight lang="csharp">
using Api.Automations; // for AutomationRunInfo

..

// If your automation doesn't need to do anything async:
Events.Automation("once_a_second", "* * * * * ? *")
.AddEventListener((Context context, AutomationRunInfo info) => {

System.Console.WriteLine("- Runs once a second -");

return new ValueTask<AutomationRunInfo>(info);

});

// With async:
Events.Automation("once_a_second", "* * * * * ? *")
.AddEventListener(async (Context context, AutomationRunInfo info) => {

System.Console.WriteLine("- Runs once a second -");

await _someOtherService.DoSomething(context);

return info;

});

</syntaxhighlight>

Note that Automation has two args - a name and a schedule. The name is such that your automation can be triggered by hand separately, for example if you need a background job to run "now" rather than waiting for the schedule to trigger it.

Because of the name, it is also possible to add additional handlers to a particular job run. For example if you know a job is called "update_certificate" then you can add an additional handler to the event like so:

<syntaxhighlight lang="csharp">

Events.Automation("update_certificate")
.AddEventListener((Context context, AutomationRunInfo info) => {

System.Console.WriteLine("- This runs immediately after the update_certificate automation. -");

return new ValueTask<AutomationRunInfo>(info);

}, 11); // Priority 11 ensures we for certain will happen after the main automations listener(s) occur.

</syntaxhighlight>

= Usage tips =

* Online cron expression editors can help you [https://www.google.com/search?q=cron+expression+editor get the expression you need]. NOTE: when selecting a cron formater that supports 7 fields - 6 field cron

* The time is always in UTC, meaning it is not affected by local timezone changes such as daylight savings and it is easier to sync larger jobs within a global cluster.