# Embedding SCP as a View

todo

Showcase Platform does not only offer a super easy-to-use UI for end users – administrators are also able to configure views which can be embedded in other web application via an iframe.

# How it works

Embedded views require a configuration to be set for each specific view. The view itself communicates with the API service and can be controlled by using GET-Parameters. Views are basically executing a flow which the administrator has configured upfront. The flow defines steps which are executed in the order they has been configured. Steps are just simple PHP functions or use predefined steps which offers more complex business logic.

# Controlling the UI

The embedded view has different options a step can work with – e.g. asking the user for some input in order to fulfill the specified actions. These action will be sent back to the UI automatically, you basically just define what you want to do and the embedded view takes care of it.

# Shared State

All steps share the same data-context which can be used to pass data between steps.

Predefined Steps

Our predefined steps may require some data in the state to be set – checkout the reference for all predefined-steps.

# Authentication

Embedded views can be used anonymously – you need to take care of a valid authentication within the configuration by using the addAuthenticatedStep command during configuration.

# Build your first view

As it is a class-based configuration, you do not need to follow any kind of naming convention – the configuration file just need to be placed within the config directory inside your CLIENT_CONFIG.

Let's build a hello world view:

<?php

// CLIENT_CONFIG/config/embedded-views/hello-world.php

use Modules\Embed\Entities\Config\EmbedViewConfiguration;
use Modules\Embed\Entities\StepContext;

EmbedViewConfiguration::new('hello-world')
    ->addAnonymousStep(static function (StepContext $stepContext) {
        $stepContext->message('Hello World', 'Nice to see you!');
    });

Okay, that was easy – get some details here:

EmbedViewConfiguration::new('hello-world')

This just creates a new configuration for the hello-world view – this name is important as it identifies the view and is used in the URL for embedding to select the correct view configuration.

addAnonymousStep(...)

We add a new anonymous step here which does not require a user to be authenticated. Please ensure to not expose any confidential data to the public as this is potentially possible with a badly configured embedded view.

$stepContext->message('Hello World', 'Nice to see you!');

If you pass a php function to the addAnonymousStep method, you will receive the current execution context of the step as the first argument. This basically contains all the stored data during the whole flow and also offers methods to control the UI. Here we want to display a simple Hello World message.

There are details on the embedded views configuration in our reference.

# Browse the UI

As we now have configured our first view, we want to see the outcome. You need to compose the URL of the UI with some required GET paramters:

https://iframe-view.services.showcase-app.io?client=YOUR_CLIENT_NAME&view=hello-world

client=YOUR_CLIENT

You need to define the CLIENT_NAME here manually as the view is URL is typically used within an iframe and the user does not browse to it manually.

view=hello-world

You've seen that we configured our embedded view by using the name hello-world – this name is required as a GET parameter do target the corresponding configuration.

What you might see is:

Embedded View showing hello world message

# Setting the state

For more complex uses-cases you need to save data and share this between steps. We set up a simple example to show how easy this can be achieved:

<?php

// CLIENT_CONFIG/config/embedded-views/hello-world.php

use Modules\Embed\Entities\Config\EmbedViewConfiguration;
use Modules\Embed\Entities\StepContext;

EmbedViewConfiguration::new('hello-world')
    ->addAnonymousStep(static function (StepContext $stepContext) {
        $stepContext->set('name', 'Astronaut');
    })
    ->addAnonymousStep(static function (StepContext $stepContext) {
        $stepContext->message(
            'Welcome ' . $stepContext->consume('name'),
            'Nice to see you out here...'
        );
    });

You might have seen, that we'd added a new step at the beginning:

$stepContext->set('name', 'Albert Astronaut');

This one just adds something to the shared state which from here on all upcoming steps can use. It sets the name to Albert Astronaut.

Within the next step – our message showing step – we consume the data from the state which means that it will be pulled out of the state. From this point on, other steps cannot get this value again, as we already have used it.

# Manipulating the flow

In most cases you would like to compose a flow with our predefined steps and combined the flow with your logic to manipulate the flow to your needs. This is easy using StepActions.

And hooray you already used a StepAction. The $stepContext->message(...) is a helper method with returns a new StepAction – so no worries here.

You can manipulate the flow in different ways:

Stay on the same step
Skip the next step

In most cases you want to do some boolean check (check if the state has something set) and modify the flow based on the result.

Check out our reference for all details on embedded views.

← Modules Handling Client Keys and Secrets →