dash-button-web

v0.0.18-beta.0

Published

a month ago

Dash button Component

0High
0Medium
0Low

Dash button web-comonont

Developing a dash button web component based on the Stencil.js framework ensures consistent support across all modern frontend frameworks with minimal configurations. Therefore, by incorporating Keycloak-based authentication with SSO features, minimal configuration is needed to secure any frontend application.

Installtion

To install the dash-button web component, copy and paste it into your frontend application.

Note: Please refer to the npm package page to find the latest version, and replace X.X.X in the import script accordingly:

<script type="module" src="https://unpkg.com/[email protected]/dist/esm/web-compnont.js"></script>

Note: Starting from v0.0.16, you need to add the FontAwesome stylesheet file to your application. If your application is already using this package, you can ignore this.

<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.7.2/css/all.min.css" />

You can find the NPM package named dash-button-web.

If it is a framework, you wll need to configure more options. Therefore, follow the Stencil.js documentation.

Prerequisites

To integrate DashButton into your application, you need to have a running Keycloak server.

Installation Guide

Here, we show how to integrate DashButton into your frontend application.

Step 1 - Setup Keycloak Server Application

First, you need to start your own Keycloak instance or use the DS2 version. We recommend using the DS2-based Keycloak instance.

Option 1 – Use DS2 Keycloak details

You can use predefined Keycloak credentials to configure DashButton. The required details are summarized below.

Keyclaok URL: https://keycloak.ds2.icelab.cloud
Realm: ds2
Client ID: dashbtn

Option 2 – Configure your own Keycloak client

If you use your own version, you need to configure the realm, client, and test users.
Make sure the client is set up with a client ID and that client authentication is disabled.

Step 2 - Configure frontend application

Here, we are demonstrating how to configure the application on an Angular-based application and a basic HTML-based application. If you need to install React or Vue.js, follow the Stencil.js documentation.

1. Set Up and Install an Angular Application

First, you need to enable the custom component support feature in the Angular project. To do that, the following code block needs to be added to the src/app/app.module.ts file.

@NgModule({
  …
  schemas: [
    CUSTOM_ELEMENTS_SCHEMA
  ],
})

Once the above addition is completed, it is required to import the below module as follows.

import { CUSTOM_ELEMENTS_SCHEMA} from '@angular/core';

Next, you need to put the script file path in the src/index.html file header section as follows.

<head>
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <link rel="icon" type="image/x-icon" href="favicon.ico">
  
 <script type='module' src='https://unpkg.com/[email protected]/dist/esm/web-compnont.js'></script>
 <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.7.2/css/all.min.css" />

...

After that, you can pass configuration options as follows using the web component.

Configuration options

| Attribute | Description | Type | Default | | ----------------- | ----------- | --------- | ------------------------- | | client-id | Keycloak client ID | string | | | `keycloak-uri` | `Keycloak server URI` | `string` | `"http://localhost:8080"` | | `realm` |`Keycloak realm`| `string` | | | redirect-uri | Application redirect URI | string | | | `show-post-login-text` | `Successfully logged in shows a custom button message` | `boolean` | `false` | | `auth-method` | `Authentication method` | `string` | `check-sso`, `(login-required)` | | `app-id` | `Application unique ID` | `string` | | | portal-url | Portal URL | string | | | `portal-api-url` | `Portal API URL` | `string` | | | show-unauthorized-modal | Show unauthorized modal | boolean | false | | other-link-type | Add new links for the menu | string | local or global | | application-display-name | Menu application display name | string | Applications | | disable-application-tab | disable application tab | boolean | false | | menu-view-type | the style of the menu | string | grid/list |

Theme Configuration options

| Attribute | Description | Type | Default | | ----------------- | ----------- | --------- | ------------------------- | | primary-color | Set primary colour | string | | | `accent-color` | `Set secondary or accent color` | `string` | |

AuthMethod Using the auth-method attribute updates the application's authentication workflow. login-required: User is forced to the login screen if they are not logged in. check-sso: User is not forced to the login screen; instead, when the user clicks the login button, they are redirected to the login screen.

Now, you are almost done. In the final stage, you can place the web-component button tag at the top of the navigation bar using the following code block.

Note: Replace DashButton configuration with actual values.

To get the module link for the Dashbutton, use the portal-api-url attribute and provide the Portal backend API endpoint URL. For the DS2 platform, you can use https://portal-api.ds2.icelab.cloud as the Portal API URL..

<dash-button keycloak-uri="http://localhost:8080" realm="demo" client-id="testapp" portal-api-url="replace_url" auth-method="login-required" show-post-login-text="false"></dash-button>

After that test your application can be test with user credentials and then you can get an output similar to this.

Note: You need to create a new user. Please access the portal and create an account associated with your organization.

2. Set up and install an HTML-based application

You need to follow similar procedures as above.

First, you need to import the script tag into the header section of your main HTML file as follows.

<head>
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <link rel="icon" type="image/x-icon" href="favicon.ico">
  
  <script type='module' src='https://unpkg.com/[email protected]/dist/esm/web-compnont.js'></script>
  <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.7.2/css/all.min.css" />
  ...

After that, all you need to do is place the dash button in your preferred location on the web page. To do so, use the following web component button tag and place it in your application with preferred configuration options.

<dash-button keycloak-uri="http://localhost:8080" realm="demo" client-id="testapp"></dash-button>

That's it, enjoy!

Changelog:

v0.0.18

Bug fixed and improved documentation.

v0.0.17

Added a new environment variable option for the Config Portal API endpoint.

v0.0.16

Added customization option to change the main menu view type.
Added a new option to retrieve the main menu list and display it from the portal API.
Replaced all icons with FontAwesome. (Any third-party application now needs to import FontAwesome.)

v0.0.15

Added configuration option to customize the application name in the menu.
Introduced feature to disable the application tab.
Display user profile photo in the dashboard button.
Removed hardcoded menu links from the dashboard button; now retrieves the menu link list dynamically from the backend service.