> For the complete documentation index, see [llms.txt](https://docs.sacruda.nl/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sacruda.nl/developers/your-apps-code/third-party-app-process.md).

# Third-party app process

ThirdPartyAppProcess -> AppProcess -> Process

`process.js` does a couple things. First of all it loads the `body.html` file, which contains the base HTML for your app. Naturally you can also use `document.createElement` and various other HTML APIs to create elements, but the HTML file is there, and anything in this file be put directly in the body.&#x20;

The class consists of a couple things by default:

* the `constructor`: this is just a basic initializer for the class. if you expect any process-level arguments to come from the spawner of your app, like the path to a file to read or a note to open, replace `...args` with the actual variables you expect as arguments, for example:

```diff
Out with the old:
-	constructor(pid, parentPid, app, operationId, workingDirectory, ...args) {
In with the new:
+	constructor(pid, parentPid, app, operationId, workingDirectory, path) {
```

* Next, let's observe the `render` method:

```javascript
async render() {
  const body = this.getBody();
  body.innerHTML = html;
  
  /* Do some interesting stuff here */
  this.myAmazingFunction();
}
```

First of all, it gets the body of the window using `AppProcess.getBody`. Then, it sets the innerHTML of that body to the `html` variable defined at the top of the file. You can use `body.querySelector` and other DOM operations on this body variable, because it's just a good ol' HTML element.

`myAmazingFunction` is just a placeholder method I added to show you how classes work. If your experience with JS isn't so great, don't be sad, you can always learn. Here's a good guide I found on the basics of JS classes: <https://www.w3schools.com/js/js_classes.asp> (w3schools never disappoints).

### In-phase process methods

There are several built-in methods in the process class that are executed in different phases of your process. Here's an exhaustive list of them.

{% hint style="warning" %}
The in-phase methods are **all** asynchronous: The Sacruda process handler and app renderer awaits these, and expects them to be asynchronous.
{% endhint %}

* `async start`: this method is called when the process is spawned, before the `render` method. If this method returns `false`, Sacruda will stop the spawn.
* `async render`: called by the app renderer: this method is called when it's time to render your app.
* `async onClose`: is expected to return something boolean-ish: determines if the process can be stopped. Return `false` to prevent the process from stopping (doesn't apply if the kill is forced)
* `async stop`: this method is called when the process is killed.

### Built-in process methods

These methods are available for you to call in your app process. They range from closing your app to handling multiple instances. Here they are:

```typescript
closeWindow(kill?: boolean): Promise<void>;
```

{% hint style="info" %}
This method is asynchronous: it has to be awaited.
{% endhint %}

Call this function to close your app. The `kill` boolean is only relevant for Sacruda's internal process handling; you can safely omit it.

***

```typescript
getSingleton(): AppProcess[];
```

This function returns other instances of your app. This is useful if you want to interact with the methods of one of those other instances.

***

```typescript
closeIfSecondInstance(): Promise<AppProcess | undefined>;
```

{% hint style="info" %}
This method is asynchronous: it has to be awaited.
{% endhint %}

If you only want your app to have one instance, call this method conditionally at the very top of your `render` method, like this:

```javascript
async render() {
  if (await this.closeIfSecondInstance()) return false;
  // . . .
}
```

{% hint style="warning" icon="gears" %}
Be sure to only call `closeIfSecondInstance` at the beginning of the render method. Sacruda will terminate your application if this method is called anywhere else, because otherwise it runs the risk of hanging the process stack.
{% endhint %}

***

{% hint style="warning" %}
Any functions I haven't written about here are ones that need their own page to explain it all. This includes functions like `spawnOverlay` (not to be confused with `spawnOverlayApp`), `appStore`, `hasOverlays` and others.
{% endhint %}

### Spawn options

In Sacruda versions 7.0.9 and below, you could call `runApp` to spawn your application in the current workspace, or `runAppDirect` to spawn your application outside of the workspaces system, directly on the app renderer itself. In 7.0.10, this functionality has changed. We're no longer using `runApp` and `runAppDirect`, instead we've added a static property, `AppProcess.spawnOptions`:

```typescript
export interface AppProcessSpawnOptions {
  asOverlay?: boolean;
  noWorkspace?: boolean;
  renderTarget?: HTMLDivElement;
}
```

Here you can decide if you want your application to spawn as an overlay, outside workspaces, or to an entirely custom render target. Say you want your application to always run as an overlay:

<pre class="language-typescript"><code class="lang-typescript">class proc extends ThirdPartyAppProcess {
<strong>  static spawnOptions = {
</strong><strong>    asOverlay: true
</strong><strong>  };
</strong>
  constructor(pid, parentPid, app, operationId, workingDirectory, ...args) {
    super(pid, parentPid, app, operationId, workingDirectory);
  }
}


return proc;
</code></pre>

The SpawnUserContext will find these properties and act in kind when spawning your process, as seen in this code snippet from the Sacruda codebase:

<figure><img src="https://1381638529-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fajtj78B3126gLqEeZFKg%2Fuploads%2FdZTaDda5SttNAS2Sge8y%2F%7BC02444F7-D4CD-4062-ADF2-4229FB5541A0%7D.png?alt=media&amp;token=2f47b55d-1c06-423d-a2cc-7c18e71739f4" alt=""><figcaption></figcaption></figure>
