@rws-framework/client

Version:

This package provides the core client-side framework for Realtime Web Suit (RWS), enabling modular, asynchronous web components, state management, and integration with backend services. It is located in `.dev/client`.

github.com/papablack/rws-client

rws-framework/rws-client

180 lines • 82.1 kB

HTML

<!DOCTYPE html><html class="default" lang="en"><head><meta charSet="utf-8"/><meta http-equiv="x-ua-compatible" content="IE=edge"/><title>Realtime Web Suite Client package</title><meta name="description" content="Documentation for Realtime Web Suite Client package"/><meta name="viewport" content="width=device-width, initial-scale=1"/><link rel="stylesheet" href="assets/style.css"/><link rel="stylesheet" href="assets/highlight.css"/><script defer src="assets/main.js"></script><script async src="assets/search.js" id="tsd-search-script"></script><script async src="assets/navigation.js" id="tsd-nav-script"></script><link rel="stylesheet" href="assets/hierarchy.css"/></head><body><script>document.documentElement.dataset.theme = localStorage.getItem("tsd-theme") || "os"</script><header class="tsd-page-toolbar"><div class="tsd-toolbar-contents container"><div class="table-cell" id="tsd-search" data-base="."><div class="field"><label for="tsd-search-field" class="tsd-widget tsd-toolbar-icon search no-caption"><svg width="16" height="16" viewBox="0 0 16 16" fill="none"><use href="#icon-search"></use></svg></label><input type="text" id="tsd-search-field" aria-label="Search"/></div><div class="field"><div id="tsd-toolbar-links"></div></div><ul class="results"><li class="state loading">Preparing search index...</li><li class="state failure">The search index is not available</li></ul><a href="index.html" class="title">Realtime Web Suite Client package</a></div><div class="table-cell" id="tsd-widgets"><a href="#" class="tsd-widget tsd-toolbar-icon menu no-caption" data-toggle="menu" aria-label="Menu"><svg width="16" height="16" viewBox="0 0 16 16" fill="none"><use href="#icon-menu"></use></svg></a></div></div></header><div class="container container-main"><div class="col-content"><div class="tsd-page-title"><h2>Realtime Web Suite Client package</h2></div><div class="tsd-panel tsd-typography"><a id="md:realtime-web-suit-client-setup-and-configuration-guide" class="tsd-anchor"></a><h1><a href="#md:realtime-web-suit-client-setup-and-configuration-guide">Realtime Web Suit client setup and configuration guide</a></h1>Realtime Web Suit is a web-component powered, MS FAST powered fullstack-oriented framework that you can use to create domain-agnostic modular asynchoronous components with intershared authorized states. <a id="md:table-of-contents" class="tsd-anchor"></a><h2><a href="#md:table-of-contents">Table of Contents</a></h2><ol> <li><a href="#md:overview">Overview</a></li> <li><a href="#md:getting-started">Getting Started</a></li> <li><a href="#md:key-components-rwsclient--routingservice">Key Components: RWSClient & RoutingService</a></li> <li><a href="#md:component-initialization">Component Initialization</a></li> <li><a href="#md:dependency-injection">DI</a></li> <li><a href="#md:frontend-routes">Frontend routes</a></li> <li><a href="#md:backend-imports">Backend Imports</a></li> <li><a href="#md:utilizing-apiservice">Utilizing APIService</a></li> <li><a href="#md:notifier">Notifier</a></li> <li><a href="#md:service-worker">Service Worker</a></li> <li><a href="#md:example-webchat-component">Example: WebChat Component</a></li> <li><a href="#md:other-configs">Other configs</a></li> <li><a href="#md:plugin-system">Plugins</a></li> <li><a href="#md:links">Links</a></li> </ol> <a id="md:overview" class="tsd-anchor"></a><h2><a href="#md:overview">Overview</a></h2>The RWS Frontend Framework is designed to create dynamic and responsive web applications. It integrates seamlessly with the backend and provides a robust set of tools for developing comprehensive web solutions. <a id="md:getting-started" class="tsd-anchor"></a><h2><a href="#md:getting-started">Getting Started</a></h2>To get started with the RWS Frontend Framework, ensure you have the necessary environment set up, including Node.js and any other dependencies specific to the framework. from your project dir do: <pre><code class="language-bash">yarn </code><button>Copy</button></pre> Initiate cfg files and webpack build: <pre><code class="language-bash">rws-client init </code><button>Copy</button></pre> to install once and then to build after preparing components: <pre><code class="language-bash">yarn build </code><button>Copy</button></pre> or to watch for dev <pre><code class="language-bash">yarn watch </code><button>Copy</button></pre> or to just start server <pre><code class="language-bash">yarn server </code><button>Copy</button></pre> then start engine in the site javascript (can be inline): <pre><code class="language-javascript">window.RWS.client.start(CFG); // it is async function </code><button>Copy</button></pre> or for initial setup then start on certain event (example) <pre><code class="language-javascript">window.RWS.client.setup(CFG).then(() => { // it is async function $.on('loaded', function(data){ const optionalNewCfg = { backendRoutes: data.backendRoutes }; window.RWSClient.start(optionalNewCfg).then(); }) }); </code><button>Copy</button></pre> <a id="md:default-config-for-rws" class="tsd-anchor"></a><h3><a href="#md:default-config-for-rws">default config for RWS:</a></h3><pre><code class="language-javascript">const _DEFAULT_CONFIG_VARS = { //Build configs dev: false, hot: false, report: false, publicDir: './public', publicIndex: 'index.html', outputFileName: 'client.rws.js', outputDir: process.cwd() + '/build', //Frontend RWS client configs backendUrl: null, wsUrl: null, partedDirUrlPrefix: '/lib/rws', partedPrefix: 'rws', pubUrlFilePrefix: '/', //Universal configs transports: ['websocket'], parted: false, } </code><button>Copy</button></pre> The options description: <table> <thead> <tr> <th>Option</th> <th>Description</th> <th>Default</th> </tr> </thead> <tbody><tr> <td>backendUrl</td> <td>Url for backend integration (API calls)</td> <td>null</td> </tr> <tr> <td>wsUrl</td> <td>Url for backend integration (Websocket calls)</td> <td>null</td> </tr> <tr> <td>backendRoutes</td> <td>Backend routes object imported from backend node for integration with API calls</td> <td>null</td> </tr> <tr> <td>apiPrefix</td> <td>Prefix for API calls</td> <td>/</td> </tr> <tr> <td>routes</td> <td>Routes for frontend routing</td> <td>{}</td> </tr> <tr> <td>transports</td> <td>Websockets transports method</td> <td>['websockets']</td> </tr> <tr> <td>user</td> <td>User object for backend auth / frontend data source</td> <td>null</td> </tr> <tr> <td>ignoreRWSComponents</td> <td>Do not declare base RWS components (uploader, progress)</td> <td>false</td> </tr> <tr> <td>pubUrlFilePrefix</td> <td>the url for accessing files from browser URL</td> <td>/</td> </tr> <tr> <td>pubUrl</td> <td>the url for accessing public dir from browser URL</td> <td>/</td> </tr> <tr> <td>outputDir</td> <td>build dir</td> <td>./build</td> </tr> <tr> <td>outputFileName</td> <td>output file name</td> <td>rws.client.js</td> </tr> <tr> <td>publicDir</td> <td>public dir for HTML serving</td> <td>./public</td> </tr> <tr> <td>tsConfigPath</td> <td>tsconfig.json path</td> <td>./tsconfig.njson</td> </tr> <tr> <td>entry</td> <td>default TS entry for transpilation</td> <td>./src/index.ts</td> </tr> <tr> <td>parted</td> <td>"Parted" mode if enabled. "Monolith" if disabled. Parted mode outputs every component as separate js file and asynchronously adds them to browser. Monolith is single file js build.</td> <td>false</td> </tr> <tr> <td>partedPrefix</td> <td>parted file prefix ([prefix].[cmp name].js)</td> <td>rws</td> </tr> <tr> <td>partedDirUrlPrefix</td> <td>URL for generated js parted files directory</td> <td>/</td> </tr> <tr> <td>copyAssets</td> <td>An option for defining structure that will be copied after build</td> <td>{}</td> </tr> </tbody></table> copyAssets example <pre><code class="language-json">"copyAssets": { "./public/js/": [ // target directory "./build/", // copy this directory to target "./src/styles/compiled/main.css" //copy this file to target ] } </code><button>Copy</button></pre> <a id="md:the-front-config-ts-interface" class="tsd-anchor"></a><h3><a href="#md:the-front-config-ts-interface">The FRONT config TS interface:</a></h3><pre><code class="language-typescript">interface IRWSConfig { defaultLayout?: typeof RWSViewComponent backendUrl?: string wsUrl?: string backendRoutes?: any[] apiPrefix?: string routes?: IFrontRoutes transports?: string[] user?: any ignoreRWSComponents?: boolean pubUrl?: string pubUrlFilePrefix?: string partedDirUrlPrefix?: string dontPushToSW?: boolean parted?: boolean partedFileDir?: string partedPrefix?: string routing_enabled?: boolean _noLoad?: boolean } </code><button>Copy</button></pre> <a id="md:the-front-webpack-config" class="tsd-anchor"></a><h3><a href="#md:the-front-webpack-config">The FRONT webpack config:</a></h3><pre><code class="language-javascript">const path = require('path'); const RWSWebpackWrapper = require('@rws-framework/client/rws.webpack.config'); const executionDir = process.cwd(); module.exports = RWSWebpackWrapper({ tsConfigPath: executionDir + '/tsconfig.json', entry: `${executionDir}/src/index.ts`, publicDir: path.resolve(executionDir, 'public'), outputDir: path.resolve(executionDir, 'build'), outputFileName: 'jtrainer.client.js' }); </code><button>Copy</button></pre> <a id="md:key-components" class="tsd-anchor"></a><h2><a href="#md:key-components">Key Components</a></h2><a id="md:rwsclient" class="tsd-anchor"></a><h3><a href="#md:rwsclient">RWSClient</a></h3><a id="md:" class="tsd-anchor"></a><h2><a href="#md:"></a></h2><code>RWS.client</code> is the heart of the framework, managing configuration and initialization. It sets up routes, backend connections, and other essential framework services. <a id="md:routingservice" class="tsd-anchor"></a><h3><a href="#md:routingservice">RoutingService</a></h3><code>RoutingService</code> handles the navigation and routing within your application. It ensures that URL changes reflect the correct component rendering. Depreciation Notice RoutingService will be moved to @rws-framework/browser-router near future <a id="md:wsservice" class="tsd-anchor"></a><h3><a href="#md:wsservice">WSService</a></h3><code>WSService</code> handles Websockets messenging to the backend. Depreciation Notice WSService will be moved to @rws-framework/nest-interconnectors in near future <a id="md:apiservice" class="tsd-anchor"></a><h3><a href="#md:apiservice">APIService</a></h3><code>APIService</code> handles API requests to the backend. Implementing the Framework Main File: The main file (<code>index.ts</code>) is where you initialize the RWSClient. Here, you configure your routes, backend routes, and component initializations. Following is example of full usage of the framework <pre><code class="language-typescript">async function initializeApp() { const theClient = RWSContainer().get(RWSClient); theClient.addRoutes(frontendRoutes); theClient.setBackendRoutes(backendRoutes()); theClient.enableRouting(); theClient.onInit(async () => { // For single file output: initComponents(theClient.appConfig.get('parted')); // start components for monolith mode theClient.defineComponents(); // start RWS conponents //custom outside components registering provideFASTDesignSystem() .register(fastButton()) .register(fastTab()) .register(fastSlider()) .register(fastSelect()) .register(fastDivider()) .register(fastMenu()) .register(fastMenuItem()) ; // Service worker code // const swFilePath: string = `${theClient.appConfig.get('pubUrl')}/service_worker.js`; // await theClient.swService.registerServiceWorker(); //if(theClient.getUser()){ // theClient.pushUserToServiceWorker({...theClient.getUser(), instructor: false}); //} }); theClient.setNotifier((message: string, logType: NotifyLogType, uiType: NotifyUiType = 'notification', onConfirm: (params: any) => void, notifierOptions: any = {}) => { switch(uiType){ case 'notification': let notifType = 'success'; if(logType === 'error'){ notifType = 'error'; } if(logType === 'warning'){ notifType = 'warning'; } return alertify.notify(message, notifType, 5, onConfirm); case 'alert': const alertObj = alertify.alert('Junction AI Notification', message, onConfirm); Object.keys(notifierOptions).forEach(key => { const optionValue = notifierOptions[key]; if(key === 'width'){ alertObj.elements.dialog.style = `max-width: ${optionValue};`; return; } alertObj.set(key, optionValue); }); alertObj.show(); return alertObj; case 'silent': if(logType == 'warning'){ console.warn(message); }else if(logType == 'error'){ console.error(message); }else{ console.log(message); } return; } }); theClient.assignClientToBrowser(); } initializeApp().catch(console.error); </code><button>Copy</button></pre> <a id="md:component-initialization" class="tsd-anchor"></a><h2><a href="#md:component-initialization">Component Initialization</a></h2>In <code>application/_initComponents.ts</code>, you initialize the custom components used in your application. If components added in here will include other components they dont need to be listed here. A component imported in this mode needs to be imported once. This should be conditioned not to execute imported code when using parted mode. <a id="md:default-component-structure" class="tsd-anchor"></a><h3><a href="#md:default-component-structure">Default component structure</a></h3><pre><code>component-dir/ component.ts template.html styles/ layout.scss </code><button>Copy</button></pre> WARNING All html templates refer to variable "T" as to FASTElement templating html scope. It contains all the functions FAST templates uses in html. F.e: T.html, T.when, T.repeat <pre><code class="language-html"><div class="convo-area-wrap"> <header> <div class="header-inner"></div> ${T.when(x => x.noChoose === 'false', (item, index) => T.html`<div> <chat-convo-models :chosenModel="${x => x.chosenModel}"></chat-convo-models> </div>`)} <div> <h2>${ x => x.chatContext ? x.chatContext.label : 'loading...' }</h2> <h3><strong>${ x => x.messageList.length }</strong> messages in total</h3> </div> <fast-divider></fast-divider> </header> <section> <div class="scroll-area"> <div class="scroll-content"> ${T.repeat(x => x.messageList, (item, index) => T.html` <chat-convo-message :contentReturn="${item => item}" :item="${item => item}"/> `)} ${T.when(x => !x.messageList.length, (item, index) => T.html` <p class="no-chat">No messages</p> `)} </div> </div> </section> </div> </code><button>Copy</button></pre> <a id="md:application_initcomponentsts" class="tsd-anchor"></a><h3><a href="#md:application_initcomponentsts">application/_initComponents.ts</a></h3>Only if parted mode is false. <pre><code class="language-typescript">import { ChatNav } from '../components/chat-nav/component'; import { DefaultLayout } from '../components/default-layout/component'; import { RWSIcon } from '../components/rws-icon/component'; import { LineSplitter } from '../components/line-splitter/component'; import { WebChat } from '../components/webchat/component'; export default (partedMode: boolean = false) => { if(!partedMode){ WebChat; LineSplitter; DefaultLayout; ChatNav; RWSIcon; } }; </code><button>Copy</button></pre> **Component needs to extend RWSViewComponent and use </div></div><div class="col-sidebar"><div class="page-menu"><div class="tsd-navigation settings"><details class="tsd-index-accordion"><summary class="tsd-accordion-summary"><h3><svg width="20" height="20" viewBox="0 0 24 24" fill="none"><use href="#icon-chevronDown"></use></svg>Settings</h3></summary><div class="tsd-accordion-details"><div class="tsd-filter-visibility"><h4 class="uppercase">Member Visibility</h4><form><ul id="tsd-filter-options"><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-protected" name="protected"/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg>Protected</label></li><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-private" name="private"/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg>Private</label></li><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-inherited" name="inherited" checked/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg>Inherited</label></li><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-external" name="external"/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg>External</label></li></ul></form></div><div class="tsd-theme-toggle"><h4 class="uppercase">Theme</h4><select id="tsd-theme"><option value="os">OS</option><option value="light">Light</option><option value="dark">Dark</option></select></div></div></details></div><details open class="tsd-index-accordion tsd-page-navigation"><summary class="tsd-accordion-summary"><h3><svg width="20" height="20" viewBox="0 0 24 24" fill="none"><use href="#icon-chevronDown"></use></svg>On This Page</h3></summary><div class="tsd-accordion-details"><ul><li><ul><li><a href="#md:realtime-web-suit-client-setup-and-configuration-guide">Realtime Web Suit client setup and configuration guide</a></li><li><ul><li><a href="#md:table-of-contents">Table of Contents</a></li><li><a href="#md:overview">Overview</a></li><li><a href="#md:getting-started">Getting Started</a></li><li><ul><li><a href="#md:default-config-for-rws">default config for RWS:</a></li><li><a href="#md:the-front-config-ts-interface">The FRONT config TS interface:</a></li><li><a href="#md:the-front-webpack-config">The FRONT webpack config:</a></li></ul></li><li><a href="#md:key-components">Key Components</a></li><li><ul><li><a href="#md:rwsclient">RWSClient</a></li></ul></li><li><a href="#md:"></a></li><li><ul><li><a href="#md:routingservice">RoutingService</a></li><li><a href="#md:wsservice">WSService</a></li><li><a href="#md:apiservice">APIService</a></li></ul></li><li><a href="#md:component-initialization">Component Initialization</a></li><li><ul><li><a href="#md:default-component-structure">Default component structure</a></li><li><a href="#md:application_initcomponentsts">application/_initComponents.ts</a></li></ul></li></ul></li></ul></li></ul></div></details></div><div class="site-menu"><div class="tree"><div class="tree-config"><button class="tree-config__button tree-config__button--expand js-tree-expand" title="Expand All"><svg xmlns="http://www.w3.org/2000/svg" x="0px" y="0px" viewBox="0 0 490.72 490.72" fill="currentColor"><path d="M480.027,288.027H10.693c-5.867,0-10.667,4.8-10.667,10.667c0,5.867,4.8,10.667,10.667,10.667h213.333v144.96l-45.76-45.76c-4.267-4.053-10.987-3.947-15.04,0.213c-3.947,4.16-3.947,10.667,0,14.827l64,64c4.16,4.16,10.88,4.16,15.04,0l64-64c4.053-4.267,3.947-10.987-0.213-15.04c-4.16-3.947-10.667-3.947-14.827,0l-45.867,45.76V309.36h234.667c5.867,0,10.667-4.8,10.667-10.667C490.693,292.827,485.893,288.027,480.027,288.027z"></path><path d="M10.693,224.027h469.333c5.867,0,10.667-4.8,10.667-10.667c0-5.867-4.8-10.667-10.667-10.667H245.36V36.4l45.76,45.76c4.267,4.053,10.987,3.947,15.04-0.213c3.947-4.16,3.947-10.667,0-14.827l-64-64c-4.16-4.16-10.88-4.16-15.04,0l-64,64c-4.053,4.267-3.947,10.987,0.213,15.04c4.16,3.947,10.667,3.947,14.827,0l45.867-45.76v166.293H10.693c-5.867,0-10.667,4.8-10.667,10.667C0.027,219.227,4.827,224.027,10.693,224.027z"></path></svg></button><button class="tree-config__button tree-config__button--collapse js-tree-collapse" title="Collapse All"><svg viewBox="0 0 16 16" xmlns="http://www.w3.org/2000/svg" fill="currentColor"><path fill-rule="evenodd" d="M1 8a.5.5 0 0 1 .5-.5h13a.5.5 0 0 1 0 1h-13A.5.5 0 0 1 1 8zm7-8a.5.5 0 0 1 .5.5v3.793l1.146-1.147a.5.5 0 0 1 .708.708l-2 2a.5.5 0 0 1-.708 0l-2-2a.5.5 0 1 1 .708-.708L7.5 4.293V.5A.5.5 0 0 1 8 0zm-.5 11.707-1.146 1.147a.5.5 0 0 1-.708-.708l2-2a.5.5 0 0 1 .708 0l2 2a.5.5 0 0 1-.708.708L8.5 11.707V15.5a.5.5 0 0 1-1 0v-3.793z"></path></svg></button><button class="tree-config__button tree-config__button--target js-tree-target" title="Scroll to current file"><svg viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg" fill="currentColor"><circle cx="12" cy="12" r="3"></circle><path d="M13 4.069V2h-2v2.069A8.008 8.008 0 0 0 4.069 11H2v2h2.069A8.007 8.007 0 0 0 11 19.931V22h2v-2.069A8.007 8.007 0 0 0 19.931 13H22v-2h-2.069A8.008 8.008 0 0 0 13 4.069zM12 18c-3.309 0-6-2.691-6-6s2.691-6 6-6 6 2.691 6 6-2.691 6-6 6z"></path></svg></button></div><div class="tree-content"><ul class="js-category-list category" data-id="root"><li><div class="category__folder" data-id="root-src"></div>src<ul class="js-category-list category" data-id="root-src"><li><di