Javascript

Closer look at the DNA of the OpenFin Platform API

Mar 23, 2020

8 min read

This blog takes a deep dive into the newly launched Platform API by OpenFin. After only a few days of playing around with the software, I realized just how much capacity it has and how many good features there are for developers. Ultimately, this robust set of features will significantly enhance your user’s experience.

Before I begin, let's start with a bit of background information on OpenFin!

Dictionary

API: Application Programming Interface OS: Operating System CSS: Cascading Style Sheets

What is OpenFin?

Openfin is a tech company focused on modernizing desktops, and accelerating innovation in the financial sector. Simply put, OpenFin is the Operating System of Finance! With this, you get the power you need, the freedom you want, and the security you must have.

The Problem

If you are in the financial sector, you know that it is very important to be able to visualize everything on one screen when interacting with multiple applications. We usually tend to arrange windows over and over, but that takes time, and our applications do not work with each other, nor do they share all data between them by nature. Most importantly, we have to try to make sure all of these apps are secure!

The Solution

Platform API of course!

What is the OpenFin Platform API?

It's a software that will help you build desktop platforms at the speed of light. The Platform API will also facilitate the work of creating a merged user experience across the multiple applications.

“The Platform API is for central architecture teams who want to provide web apps with a unified desktop experience and common look & feel.” - OpenFin Engineer

Key Features of the OpenFin Platform API

Layout management (e.g. window drag-and-drop and tabbing)
Customization of window look & feel
Styling via CSS
URL for loading the title bar window
Customization of all Platform APIs (behaviors)
Save and restore your window view.
Window level context (different from FDC3)
“Smart” Manifests to describe platforms via a single .JSON file

The Powerful Gridlayout

One of my favorite features is their grid layout. This feature has helped me reduce the amount of time it takes to develop an app. It can get pretty complicated to create dynamic grids that work with internal and external windows, by dragging and dropping. Now, if you see it from the end user point of view, this is an awesome idea, because the grid is customizable!

Now, I know what you are thinking. And no, you don't need to ask the developer to change the layout of the application. You, as an end user, can change the layout as well. This gives every end user the opportunity to have customs views of their apps that best fit their needs, and grow their productivity.

As a developer, I believe this is a huge benefit, since I don't have to worry about writing the code for this dynamic grid, nor do I need to worry about customizing the layout for each end user or client, which allows me to focus on the actual applications that will be used inside of the Platform API.

Because a Grid layout is not enough

The Platform API gives you the ability to power up your platform not only with custom layouts, but also with tabs! As a developer, I can develop my applications used inside of the platform with the assurance that they can be grouped together on tabs. And one of the coolest things is that you can customize them! If you are an end user of the platform, there are so many benefits here. E.g You can group the tabs by colors, where each color represents windows that belong to a certain group. This is huge. I have seen monitors of people working in the financial sector with 20 open windows and sometimes, users get lost in this. It's hard to manage what's going on.

Your perfect setup...always

So while working with the Platform API, I found out that you can save the current platform setup. This is an amazing feature. When working with dynamic layout, having to re-arrange things every time the code compiles can become very tedious. Now, imagine the benefits of this for the end users!

As a developer, you can easily retrieve the existing snapshot of your saved platform by using the applySnapshot method.

platform.applySnapshot(mySnapshot, {closeExistingWindows: true});

Thanks to this, you don't have to worry about losing the perfect setup that took you time to arrange. The setup will be always the same as long as you want to apply the saved snapshot!

Advanced workflows

The Platform API allows you to get the current context of your window. Thanks to this, you can easily save it into the platform's snapshots to re-use the context when the aplySnapShot method is called.

#The Core Now, let's take a closer look at the core of OpenFin’s Platform API and dive into some code examples. What is the core? It’s the manifest! I like to refer to it as the core because it is what carries all the information which constructs your Platform API project.

The manifest is located inside of a .json file AKA the app.json

#Let’s Get Started Let's create our manifest:

{
    "platform": {
        "uuid": "thisdot_platform"
    }
}

As you can see, this is the beginning of a new project using the Platform API. All you have to do is declare the "platform" object in your app.json.

Now let’s dive into the features to customize the application experience.

Customizing the Platform API Window

Customize your window's look and feel using css, and by adding defaultWindowOptions. You manifest will look as follows:

{
    "platform": {
        "uuid": "example_platform",
        "defaultWindowOptions": {
            "stylesheetUrl": "url-to-css-stylesheet"
        }
    }
}

##Take a look at this file to see what css selectors are available in the Platform API.

You can also replace the default windows that come with the Platform API. To do this, specify the url property as a window option in your manifest. You can import your custom HTML as follows:

...
"defaultWindowOptions": {
    "url": "url-to-html-file"
}
...

##When working with your custom window, all you have to do is consider the following:

This HTML file must specify a div component with the ID layout-container where you want the layout to be rendered. This will ensure that the window has a target to render the layout in. A url can also be specified in windowOptions in a snapshot, or when launching a snapshot via other methods.

Window Commands

OpenFin enables your Platform API application to work and feel like a native desktop application. That's why Openfin engineers further enhanced this experience by adding commands (with appropriate hotkeys) to help improve user experience.

These commands can be added to the platform object inside of your Platform API manifest.

...
"commands": [
  {
    "command": "stack.nextTab",
    "keys": "Ctrl+T"
  }
]
...

Window Snapshot

Another important property of the manifest is the snapshot. This property defines the structure of your window inside of the Platform. The snapshot needs to contain the window property where we will define the objects that go inside of it like views, and you can even define the structure of the grid by the layout property each window has. One cool feature about windows is that they can be created and destroyed by the end user, or developer, at any time.


{
  ...
    "snapshot": {
       "windows": [
            {
                "defaultWidth": 800,
                "defaultHeight": 600,
                "layout": {
                    // the structure of your grid
                }
            }
        ]
    }
  ...
}

Window Layout

This property defines the structure of your window. The layout works on a grid system. When working with the layouts, you have to add the content property inside of the layouts property. This content property contains an inner property called type. The values inside of the type value are the following:

row
column
stack
component

In the following code snippet, you can see how I'm using the the content property with the value stack as my type value. Another thing to notice is that there's content inside of other content. The Platform API allows us to have nested content to have the ability to give our window the structure we want.

...
"layout": {
  "content": [
    {
      "type": "stack",
      "content": [
        {
          "type": "component"
        }
      ]
    }
  ]
}
...

View ComponentState

Finally, another property that is worth mentioning is the componentState. This property gives us the option to provide more information about our view. Let's take a look at the following example.

...
"componentState": {
     "name": "example_labs_view",
     "url": "https://www.thisdot.co/"
 }
 ...

This view will render the website of https://www.thisdot.co inside of the view.

Take a look to this complete example:

{
  "snapshot": {
    "windows": [
      {
        "defaultWidth": 600,
        "defaultHeight": 600,
        "layout": {
          "content": [
            {
              "type": "stack",
              "content": [
                {
                  "type": "component",
                  "componentName": "view",
                  "componentState": {
                    "name": "component_A1",
                    "processAffinity": "ps_1",
                    "url": "https://www.example.com"
                  }
                },
                {
                  "type": "component",
                  "componentName": "view",
                  "componentState": {
                    "name": "component_A2",
                    "url": "https://cdn.openfin.co/embed-web/chart.html"
                  }
                }
              ]
            }
          ]
        }
      }
    ]
  }
}

If you want to learn more about the manifest and the Platform API, take a look at the official resources:

Conclusion

Working with Platform API has so many wonderful benefits. It gives me the opportunity to create more flexible software with consistent design, better user experience, and greater security. The Platform API has helped me deliver products faster, with better quality, without compromising the security of my software. OpenFin is changing the way we interact with financial software. Don’t miss your chance to use it!

This Dot is a consultancy dedicated to guiding companies through their modernization and digital transformation journeys. Specializing in replatforming, modernizing, and launching new initiatives, we stand out by taking true ownership of your engineering projects.

We love helping teams with projects that have missed their deadlines or helping keep your strategic digital initiatives on course. Check out our case studies and our clients that trust us with their engineering.

Pato Vargas

Google Developer Expert on Angular and Web Technologies, Google Women Techmaker Ambassador, Auth0 Ambassador, Media Developer Expert at Cloudinary, Platzi Master Coach, and SpringBoard mentor.

@devpato @devpato

PWA Push Notifications with Firebase (Cloud Messaging)-pt1

Push Notification In Your PWA Have you ever wondered how to add the famous/annoying push notifications to your app? Well, in this tutorial I'm going to show you how to do it using Firebase Cloud Messaging. *Note:* This tutorial requires some basic knowledge on PWAs and Service Workers. You can take a look to my Intro to PWA and Service Workers here and About PWA and notifications here. Before we begin, I need to clarify that the Notification API, and the Push API, are not the same. People get them confused all the time. Push API: The Push API gives web applications the ability to receive messages pushed to them from a server, whether or not the web app is in the foreground, or even currently loaded, on a user agent. This lets developers deliver asynchronous notifications and updates to users that opt in, resulting in better engagement with timely new content. Let's doooo it!! The final code is in the FINAL branch inside of the repo. 1) Clone this repo: https://github.com/devpato/pwa-FCM-notifications-tutorial As you can see, I already have the basic structure of the app created for you, since we are only going to worry about how to send the messages via push notifications using the Firebsae Cloud Messaging service. 2) Navigate to the index.html file. Notice I imported Firebase for you: ` 3) Navigate to Firebase.com, and create an account if you don't have one. 4) Once you are in the Firebase console, navigate to project settings (in case you don't have a project yet - just create it there) 5) Inside of project setting, under the General tab scroll all the way down to find your Firebase SDK snippet (if it's not there yet - this means that you've created a new project, and need to add there an app. Either way, this can be done in the same place where you then will have your SDK snippet - under the General tab). Copy paste it in a safe place. The snippet should look like this: 6) Go to your index.js file, and copy paste the following after the global variables I declared for you. Replace it with your project's customized code - the snippet from step 4. ` 7) Right after - initialize the firebase instance. ` 8) Then, we are going to create a constant called messaging, and will set it to firebase messaging service. ` 9) Time to request permission from firebase cloud messaging. Once we get the thumbs up, they will give us a token as a promise. ` 10) Then, we are going to use the messaging.onMessage() method. This is used for receiving data, and notification payloads, by all users that are currently viewing the page (the page is in the foreground). To do so, we add the following code: ` 11) Notice a firebase-messaging-sw.js file. This file name is going to be searched by the Firebase SDK. The file needs to be in the ROOT of your project. The Firebase SDK will do some magic in the background to register the file as a service worker. 12) Inside of your firebase-messaging-sw.js, initialize the Firebase app by passing in the messagingSenderId. The sender id can be found inside of your project settings as the following image shows. ` 13) Retrieve an instance of Firebase Messaging so that it can handle background messages. ` 14) Background message handler (this one will be invoked when the page is in the backround) ` Test The Notification 15) Run the app using any http server 16) Inside of your Cloud Messaging settings (a tab in the Firebase Console > Project Settings), copy the server key. 17) If you have a Postman http client, do the following: POST URL:* https://fcm.googleapis.com/fcm/send * HEADERS: Content-Type - application/json Authorization - key=server_key BODY: ` Then, click the Send button. At this point, if our app is in the foreground (it is currently opened tab in your browser), then you'll see the message we've sent in the console - handled by messaging.onMessage. But if it is in the background, then it will be handled by messaging.setBackgroundMessageHandler in the service worker, and you'll see something like this: Test your app on a real device by deploying to Firebase or any other hosting provider. If you want to host your app on the Firebase - take a look at my other tutorial. In the next tutorials, I will show you how to successfully subscribe to notifications and push them using the Firebase console....

Feb 3, 2020

5 mins

JavaScriptPWAFirebase

End-to-end type-safety with JSON Schema

End-to-end type-safety with JSON Schema I recently wrote an introduction to JSON Schema post. If you’re unfamiliar with it, check out the post, but TLDR: It’s a schema specification that can be used to define the input and output data for your JSON API. In my post, I highlight many fantastic benefits you can reap from defining schemas for your JSON API. One of the more interesting things you can achieve with your schemas is end-to-end type safety from your backend API to your client application(s). In this post, we will explore how this can be accomplished slightly deeper. Overview The basic idea of what we want to achieve is: * a JSON API server that validates input and output data using JSON Schema * The JSON Schema definitions that our API uses transformed into TypeScript types With those pieces in place, we can achieve type safety on our API server and the consuming client application. The server side is pretty straightforward if you’re using a server like Fastify with already enabled JSON Schema support. This post will focus on the concepts more than the actual implementation details though. Here’s a simple diagram illustrating the high-level concept: We can share the schema and type declaration between the client and server. In that case, we can make a request to an endpoint where we know its type and schema, and assuming the server validates the data against the schema before sending it back to the client, our client can be confident about the type of the response data. Marrying JSON Schema and TypeScript There are a couple of different ways to accomplish this: * Generating types from schema definitions using code generation tools * Creating TypeBox definitions that can infer TypeScript types and be compiled to JSON Schema I recommend considering both and figuring out which would better fit your application and workflows. Like anything else, each has its own set of trade-offs. In my experience, I’ve found TypeBox to be the most compelling if you want to go deep with this pattern. Code generation A couple of different packages are available for generating TS types from JSON Schema definitions. * https://github.com/bcherny/json-schema-to-typescript * https://github.com/vega/ts-json-schema-generator They are CLI tools that you can provide a glob path to where your schema files are located and will generate TS declaration files to a specified output path. You can set up an npm hook or a similar type of script that will generate types for your development environment. TypeBox TypeBox is a JSON Schema type builder. With this approach, instead of json files, we define schemas in code using the TypeBox API. The TypeBox definitions infer to TypeScript types directly, which eliminates the code generation step described above. Here’s a simple example from the documentation of a JSON Schema definition declared with TypeBox: ` This can then be inferred as a TypeScript type: ` Aside from schemas and types, TypeBox can do a lot more to help us on our type-safety journey. We will explore it a bit more in upcoming sections. Sharing schemas between client and server applications Sharing our JSON Schema between our server and client app is the main requirement for end-to-end type-safety. There are a couple of different ways to accomplish this, but the simplest would be to set up our codebase as a monorepo that contains both the server and client app. Some popular options for TypeScript monorepos are: PNPM, Turborepo, and NX. If a monorepo is not an option, you can publish your schema and types as a package that can be installed in both projects. However, this setup would require a lot more maintenance work. Ultimately, as long as you can import your schemas and types from the client and server app, you are in good shape. Server-to-client validation and type-safety For the sake of simplicity, let's focus on data flowing from the server to the client for now. Generally speaking, the concepts also apply in reverse, as long as your JSON API server validates your inputs and outputs. We’ll look at the most basic version of having strongly typed data on the client from a request to our server. Type-safe client requests In our server application, if we validate the /users endpoint with a shared schema - on the client side, when we make the request to the endpoint, we know that the response data is validated using the user schema. As long as we are confident of this fact, we can use the generated type from that schema as the return type on our client fetch call. Here’s some pseudocode: ` Our server endpoint would look something like this: ` You could get creative and build out a map that defines all of your endpoints, their metadata, and schemas, and use the map to define your server endpoints and create an API client. Transforming data over the wire Everything looks stellar, but we can still take our efforts a bit further. To this point, we are still limited to serialized JSON data. If we have a created_at field (number or ISO string) tied to our user, and we want it to be a Date object when we get a hold of it on the client side - additional work and consideration are required. There are some different strategies out there for deserializing JSON data. The great thing about having shared schemas between our client and server is that we can encode our type information in the schema without sending additional metadata from our server to the client. Using format to declare type data In my initial JSON Schema blog post, I touched on the format field of the specification. In our schema, if the actual type of our date is a string in ISO8601 format, we can declare our format to be "date-time". We can use this information on the client to transform the field into a proper Date object. ` Transforming serialized JSON Data This can be a little bit tricky; again, there are many ways to accomplish it. To demonstrate the concept, we’ll use TypeBox to define our schemas as discussed above. TypeBox provides a Transform type that you can use to declare, encode, and decode methods for your schema definition. ` It even provides helpers to statically generate the decoded and encoded types for your schema ` If you declare your decode and encode functions for your schemas, you can then use the TypeBox API to handle decoding the serialized values returned from your JSON API. Here’s what the concept looks like in practice fetching a user from our API: ` Nice. You could use a validation library like Zod to achieve a similar result but here we aren’t actually doing any validation on our client side. That happened on the server. We just know the types based on the schema since both ends share them. On the client, we are just transforming our serialized JSON into what we want it to be in our client application. Summary There are a lot of pieces in play to accomplish end-to-end type safety. With the help of JSON Schema and TypeBox though, it feels like light work for a semi-roll-your-own type of solution. Another great thing about it is that it’s flexible and based on pretty core concepts like a JSON API paired with a TypeScript-based client application. The number of benefits that you can reap from defining JSON Schemas for your APIs is really great. If you’re like me and wanna keep it simple by avoiding GraphQL or other similar tools, this is a great approach....

Apr 17, 2024

6 mins

JSONTypeScript

Closer look at the DNA of the OpenFin Platform API

What is OpenFin?

The Problem

The Solution

What is the OpenFin Platform API?

Key Features of the OpenFin Platform API

The Powerful Gridlayout

Because a Grid layout is not enough

Your perfect setup...always

Advanced workflows

Customizing the Platform API Window

Window Commands

Window Snapshot

Window Layout

View ComponentState

Conclusion

Pato Vargas

You might also like

PWA Push Notifications with Firebase (Cloud Messaging)-pt1

End-to-end type-safety with JSON Schema

You might also like

PWA Push Notifications with Firebase (Cloud Messaging)-pt1

End-to-end type-safety with JSON Schema