Skip to main content
Skip table of contents

Developing Custom Forms in a Library

You can develop custom Pro-Code forms in a PAS Form Library to use these forms as Low-Code forms or sub-forms in the Designer. Either you can start from scratch, or you can export the form definitions of a Designer service (see Modeling Forms) as a Pro-Code PAS Form Library. The library already contains the necessary structure and meta-information to directly start coding. The xUML Library Development Kit (xlib) helps you with this task. It can be used to build these libraries, and run them for testing purposes.

Prerequisites

Developing custom form libraries for the Scheer PAS platform assumes a basic knowledge of HTML, CSS, JavaScript/TypeScript and the Angular framework.
If you want to install the PAS xUML Library Development Kit, please contact our Support team.

You need to have the following installed:

Expert Advice

For detailed information about multi-project workspaces, visit the Angular documentation.

Working with the xUML Library Development Kit (xlib)

After you have installed the @pas/xuml-library-devkit, you can switch to your project folder and execute the following commands to build a new multiple-projects workspace with a new library project in it.

Creating Workspace and Library

The following table displays an overview on the main features of xlib to use with developing your own form libraries.

Command

Description

Example

xlib new <library-name>

This command builds a new multiple-projects workspace with a new library project in it. The development kit automatically generates a test form and application.

xlib new my-lib

You will get the multiple-projects workspace <library-name> containing the following files:

Generated workspace files:

BASH
/c/Projects/Devkit/my-lib (dev)
$ ls -la
drwxr-xr-x 1 u100106 1049089      0 Aug  9 14:46 ./
drwxr-xr-x 1 u100106 1049089      0 Aug  9 14:44 ../
-rw-r--r-- 1 u100106 1049089    274 Aug  9 14:44 .editorconfig
drwxr-xr-x 1 u100106 1049089      0 Aug  9 14:44 .git/
-rw-r--r-- 1 u100106 1049089    620 Aug  9 14:44 .gitignore
drwxr-xr-x 1 u100106 1049089      0 Aug  9 14:44 .vscode/
-rw-r--r-- 1 u100106 1049089   1139 Aug  9 14:45 angular.json
drwxr-xr-x 1 u100106 1049089      0 Aug  9 14:46 node_modules/
-rw-r--r-- 1 u100106 1049089   1285 Aug  9 14:46 package.json
-rw-r--r-- 1 u100106 1049089 843158 Aug  9 14:46 package-lock.json
drwxr-xr-x 1 u100106 1049089      0 Aug  9 14:45 projects/
-rw-r--r-- 1 u100106 1049089   1051 Aug  9 14:44 README.md
-rw-r--r-- 1 u100106 1049089    963 Aug  9 14:45 tsconfig.json

The library project is generated at path <library-name/projects/library-name>.

Projects Folder:

BASH
/c/Projects/Devkit/my-lib/projects (dev)
$ ls -la
drwxr-xr-x 1 u100106 1049089 0 Aug  9 14:45 ./
drwxr-xr-x 1 u100106 1049089 0 Aug  9 14:46 ../
drwxr-xr-x 1 u100106 1049089 0 Aug  9 14:45 my-lib/

Creating a Form

Your workspace project is created with an automatically generated PAS form from the @pas/xuml-library-devkit under the name my-form. To create your own form,  switch to <library-name>/projects/<library-name>/src/lib> in your workspace project. You can now use the @pas/xuml-library-devkit to create a new PAS form using the following command:

Command

Description

Example

xlib generate form <form-name>

The Development Kit creates a new folder that contains all the files needed for a new PAS form.

Projects Folder:

BASH
/C/Projects/Devkit/my-lib/projects/my-lib/src/lib/my-form (dev)
$ ls -la
drwxr-xr-x 1 u100106 1049089   0 Aug  9 15:15 ./
drwxr-xr-x 1 u100106 1049089   0 Aug  9 15:15 ../
-rw-r--r-- 1 u100106 1049089   0 Aug  9 15:15 my-form.component.css
-rw-r--r-- 1 u100106 1049089 270 Aug  9 15:15 my-form.component.html
-rw-r--r-- 1 u100106 1049089 627 Aug  9 15:15 my-form.component.spec.ts
-rw-r--r-- 1 u100106 1049089 767 Aug  9 15:15 my-form.component.ts
-rw-r--r-- 1 u100106 1049089  57 Aug  9 15:15 my-form.interface.ts

xlib generate form MyForm

Use the @PasForm decorator in the my-form.component.ts file to set the name of the form in your Designer project and to define the events that can be used to trigger an execution in the BPMN process.

@PASForm Decorator:

CODE
@PasForm({
    name: 'MyForm',
    events: [
        'submit'
    ]
})

The Development Kit uses the my-form.interface.ts file to build the PAS Designer types for you, so use this file to define the types for this form.

Do not forget to export the form component class in the library interface file (public-api.ts) to make this new component accessible:

CODE
/*
 * Public API Surface of my-lib
 */
 
export * from './lib/my-lib.service';
export * from './lib/my-lib.component';
export * from './lib/my-lib.module';
export * from './lib/my-form/my-form.component';

Building the Library

Make sure you generate the build folder before you build the library for the first time.

Command

Description

ng build

Generates the build folder.

You need to run this command once, before you can build the library for the first time.

xlib build

Creates an xlib folder and builds the <library-name>-library.xlib package in the root folder.

Refer to Administrating Libraries for detailed information on how to upload libraries. The usage of libraries is explained in detail on Adding Libraries and in chapter Developing and Using Libraries.

Testing and Developing Your Form Component

For testing purposes, your multiple-projects workspace comes with an automatically generated test application along with one Angular component.

Expert Advice

For detailed information about multi-project workspaces, visit the Angular documentation.

Test Application Features

All mentioned files reside in folder <name of the library>/projects/<name of the application>/src/app.

File

Description

form-test-wrapper.component.html

Contains the <pas-child-form> element. This element is part of the @pas/app-core module and is also used by the Designer to show subform elements. With this element, you can test your Designer integration as close as possible.

The <pas-child-form> element is preadjusted to use events in order to read the form's data. To test that, add text to the input field, open your browser console and click the submit button (see Starting the Test Application below).

form-test-wrapper.component.html:

XML
<pas-child-form [form]="form" (formEvent)="onFormEvent($event)" [formGroup]="reactiveForm" [data]="formData"></pas-child-form>

form-test-wrapper.component.ts




Contains an import of your form component from your library's public-api.ts file and a form variable which allows you to use your component MyFormComponent in the <pas-child-form> element.

form-test-wrapper.component.ts:

JS
import { Component, Input, OnInit, Type } from '@angular/core';
import {AbstractFormComponent, FormEvent} from "@pas/app-core";
import { FormGroup } from '@angular/forms';
import {MyFormComponent} from "../../../../my-lib/src/public-api";

@Component({
  selector: 'app-form-test-wrapper',
  templateUrl: './form-test-wrapper.component.html',
  styleUrls: ['./form-test-wrapper.component.scss']
})
export class FormTestWrapperComponent implements OnInit {
  public form: Type<AbstractFormComponent> = MyFormComponent;
  constructor() { }

  ngOnInit(): void {
  }

  @Input() public reactiveForm: FormGroup = new FormGroup({});
  public formData: any = {};

  async onFormEvent(event: FormEvent) {
    console.log(this.reactiveForm.value);
  }
}

app.module.ts

Contains an import of @pas/app-core module which makes the <pas-child-form> element accessible.

app.module.ts:

JS
import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';

import { AppRoutingModule } from './app-routing.module';
import { AppComponent } from './app.component';
import { FormTestWrapperComponent } from './form-test-wrapper/form-test-wrapper.component';
import {AppCoreModule} from "@pas/app-core";

@NgModule({
  declarations: [
    AppComponent,
    FormTestWrapperComponent
  ],
  imports: [
    BrowserModule,
    AppRoutingModule,
    AppCoreModule,
  ],
  providers: [],
  bootstrap: [AppComponent]
})
export class AppModule { }

app.component.html

Contains the selector of your form-test.wrapper.component to make your component appear.

app.component.html

XML
<app-form-test-wrapper></app-form-test-wrapper>

You can find how your HTML element is called in the .ts file of your generated form-test-wrapper component. It is the selector entry in the @Component decorator.

@Component({
selector: 'app-form-test-wrapper',
templateUrl: './form-test-wrapper.component.html',
styleUrls: ['./form-test-wrapper.component.scss']
})

Starting the Test Application

To start your test application, use:

JS
ng serve my-form-test --configuration development

This outputs

** Angular Live Development Server is listening on localhost:4200, open your browser on http://localhost:4200/ **

Open the mentioned URL http://localhost:4200/ in your browser and you will see the following screen:

generated_custom_form.png

Enter some text in the input field in your form. Open the developer console of your browser and click Submit. The entered text will be displayed in the console:

input_field_pro_code.png

Now you can continue extending your form with individual elements and test them in the Designer. 

Using External Libraries

If you want to use external libraries in your Pro-Code forms, you need to add the external library to your own library project.

Path

Step

Description

Example Code

my-lib/projects/my-lib

(1)

Go to my-lib/projects/my-lib and execute the install command for the external library.

JS
npm install ng2-pdfjs-viewer --save

(2)

Adjust the ng-package.json in the library folder to make the external library available for your applications.

JS
"allowedNonPeerDependencies":[
   "@pas/xuml-library-devkit",
   "ng2-pdf-viewer"]

Related Pages:

Related Documentation:

Download the archived (empty) test project if you want to use it as a starting point for a new Pro-Code project.

  • The project has been created by an xlib new command.

  • Just perform an npm install to install the dependencies.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.