# Embedded Views

todo

Checkout our Guide first to get familiar with embedded views.

# Step Context

Within a step you will always receive a reference to the StepContext – this is you starting point for all actions and data-manipulation.

# Working with data

# `set(string $key, $value): StepContext`

Sets a value to the current state.

JSON serialization

The state is being serialized and sent to the UI – make sure to only use serializable data and to not accidentally expose sensitive data to the world.

# `get(string $key, $default = null)`

Returns a value from the state.

Dot-Notation supported

You can use the dot notation to set or get data from the state.

# `consume(string $key, $default = null)`

Returns a value from the state and deletes the reference/key – basically pulls out the data.

# `has(string $key): bool`

Checks if the state has a value set at the given key.

# Step Actions

You can modify the flow of your steps with the following actions:

# `$stepContext->skip()`

Skips the next step.

# `$stepContext->stay()`

Stays on the current step.

# `$stepContext->showJobProgress($jobId, $waitingMessage, $successMessage, $failureMessage)`

Will show a specific view which polls the state of the given job or job chain and uses the given messages to inform the user.

# `$stepContext->message($headline, $message)`

Shows a message to the user.

# Predefined Steps

SCP offers a bunch of predefined steps from which you can benefit. You can easily use a predefined step by adding a reference to the predefined step class and add its arguments to the method call of addAnonymousStep or addAuthenticatedStep.

Here is a simple example:

<?php

// CLIENT_CONFIG/config/embedded-views/some-view.php

use Modules\Embed\Entities\Config\EmbedViewConfiguration;

EmbedViewConfiguration::new('hello-world')
    ->addAnonymousStep(
        \Modules\Embed\Steps\SomeStep::class,
        'xxx',
        'zzz'
    );

# Authenticate with a Veeva Vault® Session

This steps uses an active Veeva Vault® session to authenticate a SCP user.

Class: Modules\Embed\Steps\Auth\VaultSessionStep

Argument	Type	Description
#1	`String`	The configuration key used to get details about the Veeva Vault® connection from

# Find a material with a Veeva Vault® document

This step tries to select a SCP material based on the incoming veeva vault document id. It uses external references to connect a document id to a SCP material id.

Class: Modules\Embed\Steps\Material\FindMaterialWithVaultDocumentStep

Argument	Type	Description
#1	`String`	The configuration key used to get details about the Veeva Vault® connection from
#2	`Closure`	A mapping function to get the string key for the external reference which should be searched. It receives the vault document as its first argument.

EmbedViewConfiguration::new('yay')
    ->addAuthenticatedStep(
        FindMaterialWithVaultDocumentStep::class,
        'config.veeva_vault.connection',
        static function (array $vaultDocument) {
            return 'some-string-key';
        }
    );

# Create a Material based on a Veeva Vault® document

This step tries to create a new SCP material with data from the Veeva Vault® document. It also tries to search for a SCP material in order to check if the user has copied a material within Veeva Vault® and also copies the internal SCP material if possible.

The user will be asked to choose from a list of Material Types in order to let this step create the material for him.

Class: Modules\Embed\Steps\Material\CreateMaterialWithVaultDocumentStep

Argument	Type	Description
#1	`String`	The configuration key used to get details about the Veeva Vault® connection from
#2	`Closure`	A closure which has to return an array of suitable material types. It receives the vault document as the first argument and an optional fully qualified name of the materials type if we had found a candidate for copying.
#3	`Closure`	A closure which has to return an array of field values the new material will be created from.
#4	`Closure`	A mapping function to get the string key for the external reference which should be used to link the fresh material to.

TIP

All closures receive the Veeva Vault® document as an array as their first argument.

Asking for a Material Type

EmbedViewConfiguration::new('yay')
    ->addAuthenticatedStep(
        CreateMaterialWithVaultDocumentStep::class,
        'config.veeva_vault.something',
        static function (array $vaultDocument, ?string $fqn) {
            return \App\Models\Config\MaterialType::allSuitableTypes([
                'some_field' => $vaultDocument['some_data'],
            ], $fqn);
        },
        static function (array $vaultDocument) {
            return [
                'name' => $vaultDocument['name__v'],
                'status' => 'briefing'
            ];
        },
        static function (array $vaultDocument) {
            return 'vault';
        }
    );

# Edit Material

WARNING

This step requires the state to have a material set at material.

This step presents the content app to the user in order to let him edit the content of the briefing. We do not offer the possibility to change any meta-data from within an embedded view at the moment.

Class: Modules\Embed\Steps\Material\EditMaterialStep

Argument	Type	Description
#1	`Closure`	A closure which is being executed before we change the content of the material. It receives the material as its first argument.
#2	`String`	A label which is presented to the user as the action

Editing Materials inside an embedded view

EmbedViewConfiguration::new('yay')
    ->addAuthenticatedStep(
        EditMaterialStep::class,
        static function (\App\Models\Material $material) {
            if ($material->status_id !== 'briefing') {
                $material->updateWithFlatFieldArray(['status' => 'briefing']);
            }
        },
        'Save to Vault'
    );

# Link a Material to Veeva Vault® document(s)

This steps allows a user to search through the library of SCP in order to select a Material. Once selected, this step will link the material to the given Veeva Vault® document.

Class: Modules\Embed\Steps\Material\LinkMaterialToVaultDocumentStep

Argument	Type	Description
#1	`String`	The configuration key used to get details about the Veeva Vault® connection from
#2	`Closure`	A closure which receives an EloquentBuilder and might modify the default query in order to get materials which acts as a selection target for the user
#3	`Closure`	A mapping function to get the string key for a Veeva Vault® document – helping us to create necessary links.