Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update the Scripting docs to reflect the correct way to use IScriptingManager and IScriptingEngine #11829

Merged
merged 2 commits into from
Jun 9, 2022
Merged

Update the Scripting docs to reflect the correct way to use IScriptingManager and IScriptingEngine #11829

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f759cc8
Update the Scripting docs to reflect the correct way to use IScriptin…
MikeAlhayek Jun 8, 2022
56c6ca5
Add GitHub reference to IScriptingManager instead of closing the sign…
MikeAlhayek Jun 8, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 26 additions & 19 deletions src/docs/reference/modules/Scripting/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,18 +14,31 @@ The main interface is `IScriptingManager`.
public interface IScriptingManager
{
IScriptingEngine GetScriptingEngine(string prefix);
object Evaluate(string directive);
IList<IGlobalMethodProvider> GlobalMethodProviders { get; }
MikeAlhayek marked this conversation as resolved.
Show resolved Hide resolved

object Evaluate(string directive, IFileProvider fileProvider, string basePath, IEnumerable<IGlobalMethodProvider> scopedMethodProviders);

IReadOnlyList<IGlobalMethodProvider> GlobalMethodProviders { get; }
}
```

To evaluate an expression using a scripting engine, you must know which ones are available in the system.
For instance, a JavaScript one is available by default and its prefix is `js`.
To return the current date and time as a string we could do something like this:
To return the current date and time as an object we could do something like this:

```csharp
var scriptingManager = serviceProvider.GetService<IScriptingManager>();
var date = scriptingManager.Evaluate("js: new Date().toISOString()");

// Find the javascript engine by its prefix
var engine = scriptingManager.GetScriptingEngine("js");

// Find all global methods in the system. Here you could add more methods to the scope as needed
var globalMethods = _scriptingManager.GlobalMethodProviders.SelectMany(x => x.GetMethods());

// Create scope for the engine
var scope = engine.CreateScope(globalMethods, serviceProvider, null, null);

// Evaluate the given script
var date = engine.Evaluate("js: new Date().toISOString()");
```

The `js:` prefix is used to describe in which language the code is written. Any module can provide
Expand All @@ -36,14 +49,8 @@ a new scripting engine by implementing the `IScriptingEngine` interface.
Any module can provide custom methods for scripts independently of the chosen language.
For instance the `Contents` module provides a `uuid()` helper method that computes a unique content item identifier.

To create a global method, implement `IGlobalMethodProvider` then add it to the current `IScriptingManager` instance like this:
To create a global method, implement the `IGlobalMethodProvider`. Then, add it to the current `IScriptingManager` instance by registering it as a singleton in your Module's `Startup`

```csharp
var scriptingManager = serviceProvider.GetService<IScriptingManager>();
var globalMethodProvider = new MyGlobalMethodProvider();
scriptingManager.GlobalMethodProviders.Add(globalMethodProvider);
```
Or register your GlobalMethodProvider as a singleton in your Module's `Startup`
```csharp
services.AddSingleton<IGlobalMethodProvider, MyGlobalMethodProvider>();
```
Expand Down Expand Up @@ -80,11 +87,11 @@ Here is a list of javascript methods provided by Orchard Modules.

| Function | Description
| -------- | ----------- |
|`newContentItem(contentTypeName: String): IContent`| Creates a new instance of a ContentType (does not persist)|
|`createContentItem(contentTypeName: String, publish: Boolean, properties: Object): IContent`| Creates and persists a new ContentItem. Conditionally publishes it. |
|`updateContentItem(contentItem: IContent, properties: Object)`| Updates an existing content item with the properties |
|`deleteContentItem(contentItem: IContent)`| Deletes an existing content item |
|`getUrlPrefix(path: String): String `| Prefixes the path with the Tenant prefix (if specified) |
| `newContentItem(contentTypeName: String): IContent`| Creates a new instance of a ContentType (does not persist)|
| `createContentItem(contentTypeName: String, publish: Boolean, properties: Object): IContent`| Creates and persists a new ContentItem. Conditionally publishes it. |
| `updateContentItem(contentItem: IContent, properties: Object)`| Updates an existing content item with the properties |
| `deleteContentItem(contentItem: IContent)`| Deletes an existing content item |
| `getUrlPrefix(path: String): String `| Prefixes the path with the Tenant prefix (if specified) |

#### Layers (`OrchardCore.Layers`)

Expand All @@ -107,7 +114,7 @@ Here is a list of javascript methods provided by Orchard Modules.

| Function | Description
| -------- | ----------- |
| `httpContext(): HttpContext` | Returns the `HttpContext` which encapsulates all HTTP-specific information about an individual HTTP request. |
| `httpContext(): HttpContext` | Returns the `HttpContext` which encapsulates all HTTP-specific information about an individual HTTP request. |
| `queryString(name: String): String | Array` | Returns the entire query string (including the leading `?`) when invoked with no arguments, or the value(s) of the parameter name passed in as an argument. |
| `responseWrite(text: String): void` | Writes the argument string directly to the HTTP response stream. |
| `absoluteUrl(relativePath: String): String` | Returns the absolute URL for the relative path argument. |
Expand All @@ -133,9 +140,9 @@ The following JavaScript functions are available by default to any workflow acti
| `workflowId(): String` | Returns the unique workflow ID. |
| `input(name: String): Any` | Returns the input parameter with the specified name. Input to the workflow is provided when the workflow is executed by the workflow manager. |
| `output(name: String, value: Any): void` | Sets an output parameter with the specified name. Workflow output can be collected by the invoker of the workflow. |
| `property(name: String): Any` | Returns the property value with the specified name. Properties are a dictionary that workflow activities can read and write information from and to. |
| `property(name: String): Any` | Returns the property value with the specified name. Properties are a dictionary that workflow activities can read and write information from and to. |
| `lastResult(): Any` | Returns the value that the previous activity provided, if any. |
| `correlationId(): String` | Returns the correlation value of the workflow instance. |
| `signalUrl(signal: String): String` | Returns workflow trigger URL with a protected SAS token into which the specified signal name is encoded. Use this to generate URLs that can be shared with trusted parties to trigger the current workflow if it is blocked on the Signal activity that is configured with the same signal name. |
|`setOutcome(outcome: String): void` | Adds the provided outcome to the list of outcomes of the current activity |
| `setOutcome(outcome: String): void` | Adds the provided outcome to the list of outcomes of the current activity |
| `createWorkflowToken(workflowTypeId: String, activityId: String, expiresInDays: Integer): String` | Generates a workflow SAS token for the specidied workflowTypeid, activityId. You can also set the expiration date in number of days. |