KIE

This is part of a series of blog posts, and this one covers “How to integrate a custom Editor, an existing Editors, and custom Views on a Web App”. You can navigate through the series by clicking on the following topics: How to create a custom Editor in a React application; How to create a ChromeRead more →

This is part of a series of blog posts, and this one covers “How to integrate a custom Editor, an existing Editors, and custom Views on a Web App”.

You can navigate through the series by clicking on the following topics:

• How to create a custom Editor in a React application;
• How to create a Chrome Extension for a custom Editor;
• How to create a VS Code Extension for a custom Editor;
• How to create a custom View;
• How to create a VS Code Extension for a custom View;
• How to create a more complex custom View;
• How to integrate a custom Editor, an existing Editors, and custom Views on a Web App;

In this section, we will create a Web App where we put together our custom Base64Png Editor, the Kogito DMN Editor, the Kogito BPMN Editor, our ‘To-do’ List View, and our Ping Pong View.

Starting

Each example of this section will have 3 important files:

• envelope/<respective Envelope>.html;
• src/envelope/<respective Envelope initialization>.ts;
• src/Pages/<respective Editor or View dir>;

The only exception to this file organization is the Kogito BPMN Editor, which uses an Envelope already deployed in GitHub Pages.

Envelope HTML

The HTML Envelope file is a boilerplate. Here we have an example of the Base64Png Editor:

The only difference between the HTML Envelope files across the examples covered in this section is the src property from the script tag. In the above example, the src is base64-editor.js, which is the Envelope initialization path. The file organization on the dist folder is done by your bundler, which will not be covered here. You can check all the code of the Web App here.

Envelope Initialization

The initialization of the Envelope is pretty similar between the examples as well. Here follows the initialization method of the Base64Png Editor:

Kogito Tooling makes the Editor init method available on the @kogito-tooling/editor/dist/envelope package. We’re going to inform the Envelope container (as it is on the HTML Envelope file). The bus which is the method utilized to communicate from the Envelope to the Channel. A factory to create the Editor. Last but not least, the Editor context, providing some useful information to the Envelope.

The only difference between this initialization file and the DMN Envelope initialization is the factory.

We call the DMN Factory a GwtEditorWrapperFactory because the Editor was written in Java and compiled to Javascript using GWT.

The Views initialization is a bit simpler. Here is the ‘To-do’ List View initialization:

Differently from the Base64Png Editor, here we use the ‘To-do’ List View initialization method. Again, the container is the same on the Envelope HTML file, and we pass the bus method to tell the Envelope how to communicate with the Channel. This View doesn’t have a custom factory, so it’s unnecessary to pass any other parameter.

Our Ping Pong View has a custom factory, so the difference between it and the ‘To-do’ List View is a new property called pingPongFactory.

And of course, the init method is now from the Ping Pong View.

Embedding an Editor

In this section, we will show how to embed our custom Editors and the Kogito BPMN/DMN Editors on our Web App.

Base64Png Editor

We’re going to create a Base64PngPage React component responsible for rendering our component and a custom gallery, where you’ll be able to choose a file to be opened.

Starting, we need to create a file state, which will store the current file. It’s essential to take notice that we’re using the File definition from Kogito Tooling. We start the state with an empty file and the correct file extension.

Now, we create a memoized value with an EditorEnvelopeLocator object. This object specifies who is going to send messages to this Envelope (targetOrigin). Also, it maps a file extension (base64png) to an Envelope location (the Base64Png Envelope). In this case, we’re using a local Envelope, and its location is determined by your bundler. Still, further in the BPMN Editor example, we’re going to see how to embed already deployed Envelopes.

Finishing, we utilize the Kogito Tooling EmbeddedEditor component to render our custom Editor. Simple like that, we have our Editor up running!

The Base64PngGallery is a custom component made for this example, and it’s located on the Channel. Its function is to set a base64png file on the file state. So we can see an interaction between the Channel and the Envelope. You can check a running example here!

Kogito DMN Editor

Like in the example Base64PngPage, we’re going to create a DmnPage React component. Also, we’ll be creating a file state, used to store the current file.

Again, we’ll be setting up the editorEnvelopeLocator with a memoized value. Both Editors (DMN/BPMN) are available on the @kogito-tooling/kie-bc-editors-unpacked package, and here the DMN Editor was copied from node_modules/@kogito-tooling/kie-bc-editors-unpacked/dmn to the dist/gwt-editors/dmn.

To have imperative access to the EmbeddedEditor, it’s necessary to use the useEditorRef. It’ll provide an object with the reference to be used on the EmbeddedEditor component (ref) and a way to access its methods (editor). This Hook creates a reference callback, so it’s possible to use its methods as dependencies for other React hooks, such as the useDirtyState on the Sidebar component, which informs if the Editor is dirty or not.

The Sidebar component is used to handle new files, opening samples or files, etc. Check up the example here!

Kogito BPMN Editor

Here we’re going to use another approach to set up the EditorEnvelopeLocator. We already have a BPMN Envelope deployed for our Business Modeler Preview, and you’re going to use it. So we simply pass the URL of the Envelope and its resources, and voilá. It’s not necessary to copy any file using your bundler.

The editorEnvelopeLocator is the only difference between the DMN example.

And here is the running example of the BPMN Editor.

Embedding a View

In this section, we’ll show how to embed a View on your Web App.

‘To-do’ List View

On the ‘To-do’ List View section, we created an EmbeddedTodoList component, and we’re going to use this component here. We simply passed the ‘To-do’ List Envelope location and implemented a todoList_ItemRemoved method. The ActionSidebar is utilized to add new items to our todo list, showing the interaction between our Channel and Envelope.

Here is the finalized example, or you can use a running example here.

Ping Pong View

The idea of this View is to be used with other Ping Pong Views to show the interaction between them. To start, we will create two variables, pings and pongs, so the Channel can keep count of it. We need to create two states that will handle which View was the last to send the ping message, and the last to reply pong. Also, we implemented the PingPongChannelApi, which updates the states and values.

We use the EmbeddedPingPong component that we created on the Ping Pong implementation and simply started it with the Envelope location and the Channel API.

This is the final look with 3 Ping Pong Views and a Sidebar to show the information. You can use it by accessing here.

This screenshot was taken after a Ping request from React 1, React 2, and React 3 (respectively).

Wrapping up

This, for sure, was a long ride! We covered a lot of topics and almost everything that Kogito Tooling can do for you! We hope that this post could help you to implement your own custom Editor and/or View.

Thanks for reading, and stay tuned for more Kogito updates!

Stay safe,

Luiz

This is part of a series of blog posts, and this one covers “How to create a more complex custom View”. You can navigate through the series by clicking on the following topics: How to create a custom Editor in a React application; How to create a Chrome Extension for a custom Editor; How to create aRead more →

This is part of a series of blog posts, and this one covers “How to create a more complex custom View”.

You can navigate through the series by clicking on the following topics:

• How to create a custom Editor in a React application;
• How to create a Chrome Extension for a custom Editor;
• How to create a VS Code Extension for a custom Editor;
• How to create a custom View;
• How to create a VS Code Extension for a custom View;
• How to create a more complex custom View;
• How to integrate a custom Editor, an existing Editors, and custom Views on a Web App;

Starting

This section will cover a new View example called “Ping Pong View”, but now it will feature a factory. This change will make it more flexible to use other frameworks than React or no framework at all. You can check out all the code of this section here. A big part of the code is pretty similar to the ‘To-do’ List View, so this part is not going to be covered here.

A PingPongView is a component that can send “Pings” to the Channel and also receive ”Ping” and “Pong” notifications from the Channel. The main idea is that a PingPongView instance doesn’t know whether there are more than one PingPongViews on the screen, since it only communicates with the Channel.

As said before, the Ping Pong View’s main difference is the usage of a custom factory to create its Views. Our factory is a simple interface with a create method that returns a PingPongView.

A PingPongView has a reactComponent optional method, which should return a React component.

The PingPongEnvelopeView is identical to the TodoListEnvelopeView except for the factory passed as argument on the init method and on the PingPongEnvelopeApiImpl instancialization.

Our Ping Pong View API implementation (PingPongEnvelopeApiImpl) uses the PingPongFactory on its init method as well.

Last but not least, the View implementation uses the reactComponent method to render the View content. In case the reactComponent wasn’t implemented (not using the React framework), the content to be rendered can be simply attached to the div using the id.

React Implementation

We’ve prepared a React implementation of the Ping Pong View, and this is how it looks like.

The red border can be implemented utilizing any tool you want!

In this implementation, we create a factory that implements the PingPongFactory, which simply returns an object with the reactComponent method. Remember, if we’ve implemented this factory using another framework, or no framework at all, we’d have manually added the PingPongView implementation on the specific div or utilizing any other option available.

A PingPongReactImpl is a React component that implements the PingPongApi. You can check its code here.

Wrapping up

Hopefully, after this example, you know what you need to do to create a View utilizing another framework! In the next and last section, we’re going to wrap up all the Kogito Tooling Examples in how to create a Web App, which will contain all our available Editors (Base64Png, BPMN and DMN) and our custom Views (“To-do” List and “Ping Pong”).

Thanks for reading, and see you there!

This is part of a series of blog posts, and this one covers “How to create a custom View”. You can navigate through the series by clicking on the following topics: How to create a custom Editor in a React application; How to create a Chrome Extension for a custom Editor; How to create a VS CodeRead more →

This is part of a series of blog posts, and this one covers “How to create a custom View”.

You can navigate through the series by clicking on the following topics:

• How to create a custom Editor in a React application;
• How to create a Chrome Extension for a custom Editor;
• How to create a VS Code Extension for a custom Editor;
• How to create a custom View;
• How to create a VS Code Extension for a custom View;
• How to create a more complex custom View;
• How to integrate a custom Editor, an existing Editors, and custom Views on a Web App;

This section will cover how to create a VS Code Extension for our ‘To-do’ List View created in the previous example. Before we start, it’s recommended to access the VS Code Extension API reference to be aware of the VS Code Extension capabilities.

Here’s is a quick peek of how the extension will look like:

Obs: This example requires the VS Code version 1.46 or later.

Starting

Firstly, we’re going to create a new submodule called vscode and inside it we’ll create a new file responsible for opening a Webview on the VS Code, which will basically be a new tab with our ‘To-do’ List View. We’ll name this file as TodoListWebview.ts.

We’ll build the class where we receive all the useful properties to set up the communication between the Webview (inside the Envelope) and the Extension. Also, we set up the location of the Envelope to be rendered. The open method will be used by the activate function on the extension.ts file, and it is responsible for opening the Webview on the new tab.

In the open method, we create a Webview utilizing the vscode library.

After that, we create the base HTML code to be used by the Envelope and add the Envelope code to the script tag.

To communicate with the Extension, we create an EnvelopeServer typed with the Channel and Envelope API. Here we pass down the method used to send messages, the origin, and the initial method (like the pollInit on the EmbeddedTodoList).

Wrapping up, we set up the EnvelopeServer as the receiver of the messages coming from the Extension, and we register a clean up callback to be used when the Webview is closed. Of course, we can’t forget to start the EnvelopeServer and return the client to the Extension to communicate with the Envelope.

Extension Code

Like the example where we create a VS Code Extension for a custom Editor, we’ll need the some files:

• package.json
• src/envelope/index.ts
• src/extension.ts

package.json

The package.json is the manifest file of the VS Code Extension and has fundamental setups. You can find the package.json file here.

It’s important to specify the published and name properties because both combined create the extension name.

As mentioned before, we require a VS Code version 1.46 or later, and we specify it using the engine property.

Also, it’s important to tell the extension entry point file.

Now we’re going to inform the extension contribution points, which are responsible for adding commands to be used with the command palette (CTRL + SHIFT + P) or add new options into the file menus.

We’ve added three new commands/menu options:

• todo-list-view.add-item: To add a new item into our list, it can be used with the command pallet and the file options.
• todo-list-view: To visualize our list (exclusively from the command palette).
• mark-all-as-completed: To mark all items of the list as completed (exclusively from the command palette).

To finalize, we specify when the Extension will be active with the activationEvent property.

src/envelope/index.ts

This file is responsible for the initialization of the Envelope. We set the container to the envelope-app of the TodoListWebview created, and we pass the acquireVsCodeApi to the bus property. This method is responsible for sending messages from a Webview to an Extension.

src/extension.ts

Like it was set on the package.json main property, this file will be the Extension entry point. Here we define two important methods: activate and deactivate.

The activate method will be called when the condition on the package.json activationEvents property is met.

The deactivate method will be called when the activationEvents condition isn’t met anymore.

In this Extension, the activation method is responsible for registering all commands specified on the contribution points and for starting the TodoListWebview with the Envelope path.

It isn’t necessary to clean up when the activationEvent isn’t met anymore, so the deactivate method is empty. You can check the entire file here.

Running

To run this Extension, you can use the vsce package to generate a vsix file and manually install it (read more about here), or you can run it in debug mode.

To run in debug mode, we need to create two files in the .vscode directory. The launch.json, which is the primary file used for debugging, and task.json, create a task used by the launch.json. The launch.json is executed when you open the VS Code Extension folder on utilizing the VS Code Editor and start the debug mode (use the F5 shortcut). You can check our setup on the repository used by this example.

Wrapping up

Now you know how to create a VS Code Extension with your custom View! In the next section, we’ll show you how to create a more complex View, so if you want, you’ll be able to use another framework instead of React.

Thanks for reading, and see you in the next section.

This is part of a series of blog posts, and this one covers “How to create a custom View”. You can navigate through the series by clicking on the following topics: How to create a custom Editor in a React application; How to create a Chrome Extension for a custom Editor; How to create a VS CodeRead more →

This is part of a series of blog posts, and this one covers “How to create a custom View”.

You can navigate through the series by clicking on the following topics:

• How to create a custom Editor in a React application;
• How to create a Chrome Extension for a custom Editor;
• How to create a VS Code Extension for a custom Editor;
• How to create a custom View;
• How to create a VS Code Extension for a custom View;
• How to create a more complex custom View;
• How to integrate a custom Editor, an existing Editors, and custom Views on a Web App;

In this section, we’re going to cover how to create a custom View. If you have questions about what is a View (read more about it here), but to summarize it, a View is an Envelope. Or, to be more specific, an iframe element with your code inside and a strongly-typed communication interface with the Channel.

Like our previous sections, we’re going to utilize some React concepts to create and utilize Views (especially React hooks), so in case you’re not familiar with it, it’s suggested that you read the React documentation.

Starting

A custom View has three essential “submodules”, which are separated in directories:

• api: the API definition, which is used to communicate with the Channel.
• embedded: the Embedded Envelope component implementation, which is used by the Channel. (this is specific to React)
• envelope: this custom View’s Envelope implementation.

In this first example, we’ll create a ‘To-do’ List View, which will enable the Channel to use this View at any place. This View will feature adding, removing and marking items as complete.

API

The ‘To-do’ List View api submodule has the following files:

TodoListViewApi.ts

This is the API of your View as a component. It exposes methods that allow you to control your View component.

TodoListViewChannelApi.ts

This is the API of a Channel where this View’s Envelope can run on, and it’s consumed by the Envelope.

TodoListViewEnvelopeApi.ts

And at least, this is the API of your component’s Envelope, which is consumed by the Channel.

Embedded

This is a convenience submodule specific for React. Here is the implementation of the EmbeddedTodoList. It’s a component used by the Channel, which makes the communication between the Channel and the Envelope. Hence, it connects the interfaces from the api directory. To create this component, we’ll utilize the EmbeddedEnvelope component provided by Kogito Tooling.

RefForwardingComponent

To start, we’ll use a RefForwardingComponent which provides a way to access the component imperatively and accessing its exposed methods. Also, it enables the usage of React hooks.

Here the forwardedRef implements the TodoListApi. The props implement the TodoListChannelApi with two new attributes, which are used to tell the EmbeddedEnvelope component where the Envelope is located.

PoolInit

To start the communication between Channel and Envelope, we need to create a method used on the initialization. This method is called poollInit, and it receives an EnvelopeServer instance typed with the Channel and Envelope API’s. The EnvelopeServer is responsible for sending messages from the Channel to the Envelope (strictly in this direction), and receiving messages from the Envelope too. The pollInit method tells the EnvelopeServer what to do to “connect” with the Envelope. It can contain any parameters and this method can be called many times, since the Envelope can take a while to load. Beware of side-effects!

refDelegate

The methods implemented on the TodoListApi interface are going to be exposed through this component reference. In this example, the EnvelopeServer has the implementation of the methods. To abstract the EnvelopeServer instantiation, we delegate the exposure of the component reference to the EmbeddedEnvelopeFactory, which already has an EnvelopeServer instance, making the EmbeddedTodoList a lot simpler.

EmbeddedEnvelope

To create an EmbeddedEnvelope component, we utilize an available factory from Kogito Tooling, which will create the component, initializing the EnvelopeServer with the pollInit and then exposing the methods on the TodoListApi interface through the refDelegate method.

Envelope

All the code that runs inside the Envelope is here. The ‘To-do’ List Envelope is separated in:

• TodoListEnvelope.tsx
• TodoListEnvelopeApiImpl.tsx
• TodoListEnvelopeContext.tsx
• TodoListEnvelopeView.tsx

TodoListEnvelope

This file has the function responsible for initializing the Envelope. To start, it will create an Envelope with the ‘To-do’ List types.

Now, we create a method that knows how to render a TodoListEnvelopeView and returns a function with its API. In this example, we’re using a React View, but it’s possible to use any other framework here or just plain Javascript, giving flexibility to your implementation.

To finalize, we start the Envelope passing the View, the context, and a factory, which instantiates an Envelope API. In this example, our factory is not generic, and can only instantiate the same Envelope Api, but further, in another example, we’re going to see a more advanced factory implementation. A context is an empty object because of this example’s simplicity, but you can check it out an implementation on the Kogito Tooling for a more advanced implementation.

TodoListEnvelopeApiImpl

This file has the implementation of the Envelope API, and it receives an EnvelopeApiFactoryArgs. It has access to the View API, the EnvelopeContext, and the EnvelopeBusController. The EnvelopeBusController is the class responsible for the communication from the Envelope to the Channel (strictly this flow of messages).

The Envelope API implementation relies on the View API except for the todoList__init method. It will associate the actual Envelope with the Channel and set the user on our View (TodoListEnvelopeView).

TodoListEnvelopeView

This file has what is going to be rendered on the View. Also, it has the View API, which is consumed by the TodoListEnvelopeApiImpl file.

Like our other components in this post, we will be using the React RefForwardingComponent, and now we typed it with the TodoListEnvelopeViewApi. Additionally, we created an user state to have a more friendly interface, and an items state, which has the list of all items on our ‘To-do’ List.

Utilizing the userImperativeHandle we expose the TodoListEnvelopeViewApi methods.

To manipulate our ‘To-do’ List View, we created some useful callbacks with the userCallback hook.

• removeItem will create a copy of the items array, so it doesn’t modify the current state’s value. Using the copied array, it’ll search for the specified item, and then remove it by setting a state with the updated array (before the removal).
• updateItemCompletedStatus will also create a copy of the current items array. It will search for the specified item and then update the state with the updated array.
• allCompleted is a memoized value updated every time the items state is changed. It checks if all items have the completed property equals to true.