scion-workbench/docs/site/getting-started.md at master · SchweizerischeBundesbahnen/scion-workbench

SCION Workbench	Projects Overview	Changelog	Contributing	Sponsoring

SCION Workbench > Getting Started

This guide will walk you through creating an Angular application using the SCION Workbench by developing a simple todo application.

The application includes the following features:

Todos are listed in a workbench part docked to the left side.
Clicking a todo opens it in a workbench view in the main area.
Each todo opens in a different view.
Hold the Ctrl key when clicking on a todo to open it multiple times.
Todos can be arranged side-by-side using drag & drop.

After you complete this guide, the application will look like this: https://workbench-getting-started.scion.vercel.app.
The source code of the application can be found here.

Caution

@scion/workbench does not support zoneless. Support is planned for 2026.

Create New Angular Application

Run the following command to create a new Angular application.

ng new workbench-getting-started --routing=false --style=scss --ssr=false --zoneless=false --skip-tests

Install SCION Workbench from NPM

Run the following command to install the SCION Workbench and required dependencies.

npm install @scion/workbench @scion/workbench-client @scion/toolkit @scion/components @scion/microfrontend-platform @angular/cdk

Register SCION Workbench Providers

Add provideWorkbench() to the list of providers in your app.config.ts. Added lines are marked with [+].

    import {ApplicationConfig, provideZoneChangeDetection} from '@angular/core';
[+] import {provideWorkbench} from '@scion/workbench';
[+] import {provideRouter, withComponentInputBinding} from '@angular/router';
[+] import {provideAnimations} from '@angular/platform-browser/animations';
    
    export const appConfig: ApplicationConfig = {
      providers: [
[+]     provideWorkbench(),
[+]     provideRouter([], withComponentInputBinding()),
[+]     provideAnimations(), // temporary: required until SCION Workbench drops the deprecated Angular animations dependency.
[+]     provideZoneChangeDetection(), // temporary: enable zone.js-based change detection until `@scion/workbench` is zoneless.
         // To add zone.js:
         // 1) For a new app, create it with the `--zoneless=false` flag.
         // 2) For an existing app: run `npm i zone.js` and add the polyfill to `angular.json`: "projects" -> "<your-app>" -> "architect" -> "build" -> "options" -> "polyfills": ["zone.js"]
      ],
    };

We configure the router with componentInputBinding to read parameters directly from component inputs. SCION Workbench does not require this feature, but it simplifies this tutorial.

Insert SCION Workbench Component

Open app.component.html and change it as follows:

<wb-workbench/>

Import the SCION Workbench component in app.component.ts.

    import {Component} from '@angular/core';
[+] import {WorkbenchComponent} from '@scion/workbench';

    @Component({
      selector: 'app-root',
      imports: [
[+]     WorkbenchComponent
      ],
      templateUrl: './app.component.html',
      styleUrl: './app.component.scss'
    })
    export class AppComponent {
      title = 'workbench-getting-started';
    }

The workbench itself does not position nor lay out the <wb-workbench> component. Depending on your requirements, you may want the workbench to fill the entire page viewport or only parts of it, for example, if you have an application header.

For a quick start, position the workbench absolutely and align it with the page viewport. Open app.component.scss and change it as follows:

  wb-workbench {
    position: absolute;
    inset: 0;
  }

Add SCION Workbench Styles

The workbench requires some styles to be imported into styles.scss, as follows:

@use '@scion/workbench';

Next, download the workbench icon font from GitHub. After downloading, unzip the font files and place the extracted files in the /public/fonts folder.

Install Material Icons and Roboto Font

In this getting started guide, we will use Material icons. To import Material icons, add the following line to styles.scss.

@import url('https://fonts.googleapis.com/css2?family=Material+Symbols+Rounded');

For a nice typography, you can also install the Roboto font by adding the following lines to styles.scss:

@import url('https://fonts.googleapis.com/css2?family=Roboto:wght@100..900&display=swap');

html {
  font-family: Roboto, sans-serif;
  font-size: 14px;
}

The SCION Workbench does not require Material Icons or the Roboto Font; they are included in this tutorial as examples.

Create Start Page

In this step, we will create a component that displays the number of pending todos when opening the application.

We will use the TodoService to get some sample todos. You can download the todo.service.ts file from here.

Create a new component using the Angular CLI.
```
ng generate component overview --skip-tests
```

Open overview.component.ts component and change it as follows.

    import {Component, inject} from '@angular/core';
    import {TodoService} from '../todo.service';    

    @Component({
      selector: 'app-overview',
      templateUrl: './overview.component.html',
      styleUrl: './overview.component.scss',
    })
[+] export default class OverviewComponent {      
[+]   protected todoService = inject(TodoService);
    }

We inject the TodoService to read the number of pending todos in the template.

We also change the component to be exported by default, making it easier to register the route for the component.

Open overview.component.html and change it as follows:

You have {{todoService.todos.length}} pending todos.

Open overview.component.scss and add the following styles.
```
:host {
  display: grid;
  place-content: start center;
  padding: 2em;
}
```
We add some CSS to center the content.

    import {ApplicationConfig, provideZoneChangeDetection} from '@angular/core';
    import {provideWorkbench} from '@scion/workbench';
    import {provideRouter, withComponentInputBinding} from '@angular/router';
    import {provideAnimations} from '@angular/platform-browser/animations';

    export const appConfig: ApplicationConfig = {
      providers: [
        provideWorkbench(),
        provideRouter([
[+]       {path: 'overview', loadComponent: () => import('./overview/overview.component')},
        ], withComponentInputBinding()),
        provideAnimations(),
        provideZoneChangeDetection(),
      ],
   };

Add the overview component to the workbench layout.

Open app.config.ts and configure the workbench layout.

    import {ApplicationConfig, provideZoneChangeDetection} from '@angular/core';
    import {provideWorkbench} from '@scion/workbench';
    import {provideRouter, withComponentInputBinding} from '@angular/router';
    import {provideAnimations} from '@angular/platform-browser/animations';
[+] import {MAIN_AREA, WorkbenchLayoutFactory} from '@scion/workbench';

    export const appConfig: ApplicationConfig = {
      providers: [
        provideWorkbench({
[+]       layout: (factory: WorkbenchLayoutFactory) => factory
[+]         .addPart(MAIN_AREA)
[+]         .navigatePart(MAIN_AREA, ['overview']),
        }),
        provideRouter([
          {path: 'overview', loadComponent: () => import('./overview/overview.component')},
        ], withComponentInputBinding()),
        provideAnimations(),
        provideZoneChangeDetection(),
      ],
   };

We create a layout with a main area and display the overview component. The component is only displayed when no views are open in the main area.

Run ng serve and open a browser to http://localhost:4200. You should see: You have 20 pending todos.

Create Todos Component

Create a new component using the Angular CLI.
```
ng generate component todos --skip-tests
```

Open todos.component.ts and change it as follows.

[+] import {Component, inject} from '@angular/core';
[+] import {WorkbenchRouterLinkDirective} from '@scion/workbench';
[+] import {TodoService} from '../todo.service';

    @Component({
      selector: 'app-todos',
      templateUrl: './todos.component.html',
      imports: [
[+]     WorkbenchRouterLinkDirective,
      ],
    })
[+] export default class TodosComponent {

[+]   protected todoService = inject(TodoService);
    }

We inject the TodoService to iterate over the todos in the template.

We change the component to be exported by default, making it easier to register the route for the component.

Open todos.component.html and change it as follows:
```
<ol>
  @for (todo of todoService.todos; track todo.id) {
    <li>
      <a [wbRouterLink]="['/todos', todo.id]">{{todo.task}}</a>
    </li>
  }
</ol>
```
For each todo, we create a link. When the user clicks on a link, a new view with the todo will open. In a next step we will create the todo component and register it under the route /todos/:id.

Note that we are using the wbRouterLink and not the routerLink directive. The wbRouterLink directive is the Workbench equivalent of the Angular Router link to navigate views.

    import {ApplicationConfig, provideZoneChangeDetection} from '@angular/core';
    import {provideWorkbench} from '@scion/workbench';
    import {provideRouter, withComponentInputBinding} from '@angular/router';
    import {provideAnimations} from '@angular/platform-browser/animations';

    export const appConfig: ApplicationConfig = {
      providers: [
        provideWorkbench(),
        provideRouter([
          {path: 'overview', loadComponent: () => import('./overview/overview.component')},
[+]       {path: 'todos', loadComponent: () => import('./todos/todos.component')}, 
        ], withComponentInputBinding()),
        provideAnimations(),
        provideZoneChangeDetection(),
      ],
   };

Add the todo list to the workbench layout.

Open app.config.ts and configure the workbench layout.

    import {ApplicationConfig, provideZoneChangeDetection} from '@angular/core';
    import {provideWorkbench} from '@scion/workbench';
    import {provideRouter, withComponentInputBinding} from '@angular/router';
    import {provideAnimations} from '@angular/platform-browser/animations';
    import {MAIN_AREA, WorkbenchLayoutFactory} from '@scion/workbench';

    export const appConfig: ApplicationConfig = {
      providers: [
        provideWorkbench({
          layout: (factory: WorkbenchLayoutFactory) => factory
            .addPart(MAIN_AREA)
            .navigatePart(MAIN_AREA, ['overview'])
[+]         .addPart('todos', {dockTo: 'left-top'}, {label: 'Todos', icon: 'checklist'})
[+]         .navigatePart('todos', ['todos'])
[+]         .activatePart('todos'),
        }),
        provideRouter([
          {path: 'overview', loadComponent: () => import('./overview/overview.component')},
          {path: 'todos', loadComponent: () => import('./todos/todos.component')}, 
        ], withComponentInputBinding()),
        provideAnimations(),
        provideZoneChangeDetection(),
      ],
   };

We add a new part todos to the layout and dock it to the left. We configure the part to have a label and an icon. By default, the workbench uses icons from the Material icon font. We then navigate the part to display the todos component and open it.

For detailed explanations on defining the workbench layout, refer to Defining the workbench layout.

Open a browser to http://localhost:4200. You should see the todo list left to the main area.

Create Todo Component

In this step, we will create a component to open a todo in a view in the main area.

Create a new component using the Angular CLI.
```
ng generate component todo --skip-tests
```

Open todo.component.ts and change it as follows.

[+] import {Component, computed, effect, inject, input} from '@angular/core';
[+] import {WorkbenchView} from '@scion/workbench';
[+] import {TodoService} from '../todo.service';
[+] import {DatePipe} from '@angular/common';

    @Component({
      selector: 'app-todo',
      templateUrl: './todo.component.html',
      styleUrl: './todo.component.scss',
      imports: [
[+]     DatePipe,
      ],
    })
[+] export default class TodoComponent {
    
[+]   public id = input.required<string>();

[+]   private todoService = inject(TodoService);

[+]   protected todo = computed(() => this.todoService.getTodo(this.id()));

[+]   constructor(view: WorkbenchView) {
[+]     effect(() => view.title = this.todo().task);
[+]   } 
    }

In this step, we define an input property to read the id of the todo. Using the computed function, we fetch the todo based on the provided id. In the constructor, we inject WorkbenchView and use an effect to set the view's title.

We also change the component to be exported by default, making it easier to register the route for the component.

In the next step, we will render the todo in the template.

Open todo.component.html and change it as follows.

<span>Task:</span>{{todo().task}}
<span>Due Date:</span>{{todo().dueDate | date:'short'}}
<span>Description:</span>{{todo().description}}

Open todo.component.scss and add the following styles.

:host {
  padding: 1em;
  display: grid;
  grid-template-columns: auto 1fr;
  gap: .5em 2em;
  place-content: start;
}

We add some CSS to get a tabular presentation of the todo.

Finally, we need to register a route for the component.

    import {ApplicationConfig, provideZoneChangeDetection} from '@angular/core';
    import {provideWorkbench} from '@scion/workbench';
    import {provideRouter, withComponentInputBinding} from '@angular/router';
    import {provideAnimations} from '@angular/platform-browser/animations';
    import {MAIN_AREA, WorkbenchLayoutFactory} from '@scion/workbench';

    export const appConfig: ApplicationConfig = {
      providers: [
        provideWorkbench({
          layout: (factory: WorkbenchLayoutFactory) => factory
            .addPart(MAIN_AREA)
            .addPart('left', {relativeTo: MAIN_AREA, align: 'left', ratio: .25})
            .addView('todos', {partId: 'left'})
            .navigateView('todos', ['todos'])
        }),
      provideRouter([
        {path: 'overview', loadComponent: () => import('./overview/overview.component')},
        {path: 'todos', loadComponent: () => import('./todos/todos.component')},
[+]     {path: 'todos/:id', loadComponent: () => import('./todo/todo.component')},  
      ], withComponentInputBinding()),
      provideAnimations(),
      provideZoneChangeDetection(),
     ],
    };

Below the code from the previous step how we open the todo view using the wbRouterLink directive.

<ol>
  @for (todo of todoService.todos; track todo.id) {
    <li>
      <a [wbRouterLink]="['/todos', todo.id]">{{todo.task}}</a>
    </li>
  }
</ol>

Open a browser to http://localhost:4200. You should see the todo list left to the main area. When you click on a todo, a new view opens displaying the todo. Different todos open a different view. To open a todo multiple times, also press the Ctrl key.

Further Steps

This short guide has introduced you to the basics of SCION Workbench. For more advanced topics, please refer to our How-To guides.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

SCION Workbench > Getting Started

FilesExpand file tree

getting-started.md

Latest commit

History

getting-started.md

File metadata and controls

SCION Workbench > Getting Started