From 3e23c771151ac498adf466536cd3813d5f6c193e Mon Sep 17 00:00:00 2001 From: "patrick.oneil" Date: Tue, 26 Nov 2024 11:13:27 +0000 Subject: [PATCH 01/15] Copying exsiting docs --- .../002_integration-angular.mdx | 134 ++++++++++++++++++ .../003_integration-react.mdx | 131 +++++++++++++++++ .../022_framework-integration/index.mdx | 7 +- 3 files changed, 270 insertions(+), 2 deletions(-) diff --git a/docs/001_develop/03_client-capabilities/022_framework-integration/002_integration-angular.mdx b/docs/001_develop/03_client-capabilities/022_framework-integration/002_integration-angular.mdx index e69de29bb2..a334ec71c0 100644 --- a/docs/001_develop/03_client-capabilities/022_framework-integration/002_integration-angular.mdx +++ b/docs/001_develop/03_client-capabilities/022_framework-integration/002_integration-angular.mdx @@ -0,0 +1,134 @@ +--- +title: 'Angular - getting started' +sidebar_label: 'Getting started' +sidebar_position: 1 +id: getting-started +keywords: [web, integrations, angular] +tags: +- web +- integrations +- angular +--- + +It is easy to set up a new project where your front end uses the Angular framework. + +On this page, we shall show you how to set up an empty project that you can use as a blank canvas for adding Angular and Genesis components. + +These simple steps create an app you log run and log into, and an empty home page. You are then ready to go into the code and add some components. + +We shall also look briefly at: + +- the folder structure of the project +- the principles of routing and styling an application + +:::tip +You can find out more by looking into our [**example application**](/web/integrations/Angular/angular-example-application/), where you can look at the code and check the results against the running application. +::: + +## Setting up the Angular project + +:::info prerequisites +Before you start, ensure that you have [Node.js](https://nodejs.org/) and [Genx](https://learn.genesis.global/docs/getting-started/prerequisites/genx) installed on your system. +::: + +1. Create a new Angular project. The example below creates a project called **myApp** using Genx with `--framework Angular`: + +```shell +npx -y @genesislcap/genx@latest init myApp -s blank-app-seed --framework Angular -x +``` + +2. Navigate to your new project's **client** directory: + +```shell +cd ./client +``` + +## Install the dependencies and run the app + +1. Run the following command from your project folder: + +```shell +npm run bootstrap +``` + +2. Start the app in development mode: + +```shell +npm run dev +``` + +The development server launches your project and makes it available on localhost: + +![Angular blank-app-seed](/integrations/angular/angular-blank-app-seed.png) + +:::note +The project is currently based on Angular 18. +::: + +## Project folder structure and main elements + +### src/main.ts +This is the main entry point for the application. It bootstraps the app by rendering the **app.module.ts** module into the DOM. The file also registers [PBCs](../../../../server/packaged-business-capabilities/pbc-intro/) using `registerPBCs` + +--- + +### src/pbc +This folder contains components that are responsible for enabling the insertion of slots within the application. + +These slots act as placeholders where content, provided by the registered Project Building Components ([PBCs](../../../../server/packaged-business-capabilities/pbc-intro/)), is rendered dynamically. The [PBCs](../../../../server/packaged-business-capabilities/pbc-intro/) are registered in the application through **main.ts**, ensuring that specific components can be inserted into the designated slots at runtime. + +--- + +### src/app/share +The **share** folder holds shared resources and components that are used across the entire application. + +Key files are: + +- **genesis-components.ts**. This registers Genesis framework components, including forms, layouts, and charts. +- **foundation-login.ts**. This configures the foundation-login micro front-end component that handles authorisation and integrates it with the routing system. + +--- + +### src/app/pages +This folder contains the main pages of the application. Each page represents a different route or view, such as the **auth-login.component.ts**, which handles authentication-related flows. + +--- + +### src/app/components +This folder contains reusable UI components that are utilized throughout the app. Components in this folder are not tied to specific pages but are used as building blocks across multiple sections of the application. + +## Routing + +In Angular, routing is essential for creating single-page applications with navigation capabilities. + +The routing configuration in **app/service/route.service.ts** manages and provides routes throughout the application. This file defines a `RouteService` service that combines routes from the main application and additional routes from PBC (Pluggable Business Components). + +The `pbcRoutes` are generated dynamically by mapping over the routes provided by the PBC, extracting essential properties, and wrapping them in a `PBCContainer` component. These routes are then combined with the main application's routes into a single `allRoutes` array. + +The `RoutesProvider` uses Angular's dependency injection to make these routes available to the rest of the application by providing them through the `RoutesService`. + +Additionally, the `RoutesService` is provided to access the routes within Angular components. This ensures seamless integration and accessibility of both main application routes and PBC routes throughout the application. + +## Styling the application + +### Global styles +You can add global styles by modifying the main stylesheet located at **src/styles/styles.css**. This file contains styles that apply to the entire application. + +--- + +### Styling components or pages +For more granular control, you can add styles specific to a page or component. + +For example, if you want to have unique styling for the page that is displayed when a requested page cannot be found, create a stylesheet called **src/pages/NotFoundPage/NotFoundPage.css** with styles that only apply to that page. + +--- + +### Design tokens + +Design tokens are declared in the **src/styles/design-tokens.json** file. They offer an effective way to manage and apply styles in your application in a consistent and maintainable manner. + +The design tokens enable you to define and manage values such as colours, fonts, and spacing across the whole application. You can modify these tokens to propagate changes wherever they are used in the application. + +:::note +See more details in our page on [Design systems](../../../design-systems/introduction/) +::: diff --git a/docs/001_develop/03_client-capabilities/022_framework-integration/003_integration-react.mdx b/docs/001_develop/03_client-capabilities/022_framework-integration/003_integration-react.mdx index e69de29bb2..230abaa36c 100644 --- a/docs/001_develop/03_client-capabilities/022_framework-integration/003_integration-react.mdx +++ b/docs/001_develop/03_client-capabilities/022_framework-integration/003_integration-react.mdx @@ -0,0 +1,131 @@ +--- +title: 'React - getting started' +sidebar_label: 'Getting started' +id: getting-started +keywords: [web, integrations, react] +tags: +- web +- integrations +- react +--- + +It is easy to set up a new project where your front end uses the React framework. + +On this page, we shall show you how to set up an empty project that you can use as a blank canvas for adding React and Genesis components. + +These simple steps create an app you log run and log into, and an empty home page. You are then ready to go into the code and add some components. + +We shall also look briefly at: + +- the folder structure of the project +- the principles of routing and styling an application + +:::tip +You can find out more by looking into our [**example application**](/web/integrations/React/react-example-application/), where you can look at the code and check the results against the running application. +::: + +## Setting up the React project + +:::info prerequisites +Before you start, ensure that you have [Node.js](https://nodejs.org/) and [Genx](https://learn.genesis.global/docs/getting-started/prerequisites/genx) installed on your system. +::: + +1. reate a new React project. The example below creates a project called **myApp** using Genx with `--framework React`: + +```shell +npx -y @genesislcap/genx@latest init myApp -s blank-app-seed --framework React -x +``` + +2. Navigate to your new project's **client** directory: + +```shell +cd ./client +``` + +## Install the dependencies and start the app + +1. Run the following command from your project folder: + +```shell +npm run bootstrap +``` + +2. Start the app in development mode: + +```shell +npm run dev +``` + +The development server launches your project and makes it available on localhost: + +![React blank-app-seed](/integrations/react/react-blank-app-seed.png) + +:::note +The project is currently based on React 19, which is in the Release Candidate (RC) stage. This version provides improved support for integration with Web Components, making it easier to share data and manage state between React components and Web Components. +::: + +## Project folder structure and main elements + +### src/main.tsx +This is the main entry point for the application. It bootstraps the app by rendering the **App.tsx** component into the DOM. The file also registers [PBCs](../../../../server/packaged-business-capabilities/pbc-intro/) using `registerPBCs`. + +--- + +### src/pbc +This folder contains components that are responsible for enabling the insertion of slots within the application. These slots act as placeholders where content, provided by the registered Project Building Components ([PBCs](../../../../server/packaged-business-capabilities/pbc-intro/)), is dynamically rendered. The [PBCs](../../../../server/packaged-business-capabilities/pbc-intro/) are registered in the application through **main.tsx**, ensuring that specific components can be inserted into the designated slots at runtime. + +--- + +### src/share +The **share** folder holds shared resources and components that are used across the entire application. It includes components like **genesis-components.ts**, which registers Genesis framework components, and **foundation-login.ts**, which sets up the login function for the app. + +Key files are: + +- **genesis-components.ts**. This registers Genesis framework components, including forms, layouts, and charts. +- **foundation-login.ts**. This configures the foundation-login micro front-end component that handles authorisation and integrates it with the routing system. + +--- + +### src/pages +This folder contains the main pages of the application. Each page represents a different route or view, such as the **AuthPage**, which handles authentication-related flows. + +--- + +### src/components +This folder contains UI components that are used throughout the app. Components in this folder are not tied to specific pages, but are used as building blocks across multiple sections of the application. + +## Routing + +In React, routing is essential for creating single-page applications with navigation capabilities. + +The routing configuration in **store/RoutesContext.tsx** manages and provides routes throughout the application. This file defines a `RoutesProvider` component that combines routes from the main application and additional routes from PBC (Pluggable Business Components). + +The `pbcRoutes` are generated dynamically by mapping over the routes provided by the PBC, extracting essential properties, and wrapping them in a `PBCContainer` component. These routes are then combined with the main application's routes into a single `allRoutes` array. + +The `RoutesProvider` uses the React Context API to make these routes available to the rest of the application by wrapping its children with the `RoutesContext.Provider`. + +Additionally, the `useRoutesContext` hook is provided to access the routes context within functional components. This ensures seamless integration and accessibility of both main application routes and PBC routes throughout the application. + +## Styling the application + +### Global styles +You can add global styles by modifying the main stylesheet located at **src/styles/styles.css**. This file contains styles that apply to the entire application. + +--- + +### Styling specific components or pages +For more granular control, you can add styles to a specific page or component. + +For example, if you want to have styling for the page that is displayed when a requested page cannot be found, create a stylesheet called **src/pages/NotFoundPage/NotFoundPage.css** with styles that only apply to that page. + +--- + +### Design tokens + +Design tokens are declared in the **src/styles/design-tokens.json** file. They offer an effective way to manage and apply styles in your application in a consistent and maintainable manner. + +The design tokens enable you to define and manage values such as colours, fonts, and spacing across the whole application. You can modify these tokens to propagate changes wherever they are used in the application. + +:::note +See more details in our page on [Design systems](../../../design-systems/introduction/) +::: diff --git a/docs/001_develop/03_client-capabilities/022_framework-integration/index.mdx b/docs/001_develop/03_client-capabilities/022_framework-integration/index.mdx index 2cfa8e5a55..ba727e6875 100644 --- a/docs/001_develop/03_client-capabilities/022_framework-integration/index.mdx +++ b/docs/001_develop/03_client-capabilities/022_framework-integration/index.mdx @@ -27,6 +27,8 @@ As Foundation UI is based on web components the first step is registering the co First thing you need to add the Foundation UI npm packages you require. Update your package.json to include the following (note this is not an exhaustive list of all the Foundation UI packages). +**package.json** + ```json { ... @@ -46,9 +48,10 @@ First thing you need to add the Foundation UI npm packages you require. Update y } ``` -Next, you need to create a file that imports and registers the Foundation UI framework. +Next, you need to create a file that imports and registers the Foundation UI framework and the Foundation UI header.. + +**genesis-components.ts** -It also configures the Foundation UI header. ```ts import { configure as configureHeader }from '@genesislcap/foundation-header/config'; import { foundationLayoutComponents } from '@genesislcap/foundation-layout'; From 52cfaa9034a47460e1536ca39429b747a2837f64 Mon Sep 17 00:00:00 2001 From: "patrick.oneil" Date: Tue, 26 Nov 2024 11:16:07 +0000 Subject: [PATCH 02/15] Updating side bar config --- .../002_integration-angular.mdx | 9 +++++---- .../022_framework-integration/003_integration-react.mdx | 7 ++++--- 2 files changed, 9 insertions(+), 7 deletions(-) diff --git a/docs/001_develop/03_client-capabilities/022_framework-integration/002_integration-angular.mdx b/docs/001_develop/03_client-capabilities/022_framework-integration/002_integration-angular.mdx index a334ec71c0..bb29b41c65 100644 --- a/docs/001_develop/03_client-capabilities/022_framework-integration/002_integration-angular.mdx +++ b/docs/001_develop/03_client-capabilities/022_framework-integration/002_integration-angular.mdx @@ -1,15 +1,16 @@ --- -title: 'Angular - getting started' -sidebar_label: 'Getting started' -sidebar_position: 1 -id: getting-started +title: 'Framework integration - Angular' +sidebar_label: 'Angular' +id: client-framework-integration-angular keywords: [web, integrations, angular] tags: - web - integrations - angular +sidebar_position: 22 --- + It is easy to set up a new project where your front end uses the Angular framework. On this page, we shall show you how to set up an empty project that you can use as a blank canvas for adding Angular and Genesis components. diff --git a/docs/001_develop/03_client-capabilities/022_framework-integration/003_integration-react.mdx b/docs/001_develop/03_client-capabilities/022_framework-integration/003_integration-react.mdx index 230abaa36c..26b1f28725 100644 --- a/docs/001_develop/03_client-capabilities/022_framework-integration/003_integration-react.mdx +++ b/docs/001_develop/03_client-capabilities/022_framework-integration/003_integration-react.mdx @@ -1,12 +1,13 @@ --- -title: 'React - getting started' -sidebar_label: 'Getting started' -id: getting-started +title: 'Framework integration - React' +sidebar_label: 'Angular' +id: client-framework-integration-react keywords: [web, integrations, react] tags: - web - integrations - react +sidebar_position: 22 --- It is easy to set up a new project where your front end uses the React framework. From f437262f1c4d7f5aa2595b414b76c32877c784b4 Mon Sep 17 00:00:00 2001 From: "patrick.oneil" Date: Tue, 26 Nov 2024 12:08:57 +0000 Subject: [PATCH 03/15] Adding angular attributes, properties and event sections --- .../002_integration-angular.mdx | 162 +++++++++++++++++- 1 file changed, 153 insertions(+), 9 deletions(-) diff --git a/docs/001_develop/03_client-capabilities/022_framework-integration/002_integration-angular.mdx b/docs/001_develop/03_client-capabilities/022_framework-integration/002_integration-angular.mdx index bb29b41c65..6bd4ec8335 100644 --- a/docs/001_develop/03_client-capabilities/022_framework-integration/002_integration-angular.mdx +++ b/docs/001_develop/03_client-capabilities/022_framework-integration/002_integration-angular.mdx @@ -60,8 +60,6 @@ npm run dev The development server launches your project and makes it available on localhost: -![Angular blank-app-seed](/integrations/angular/angular-blank-app-seed.png) - :::note The project is currently based on Angular 18. ::: @@ -110,17 +108,163 @@ The `RoutesProvider` uses Angular's dependency injection to make these routes av Additionally, the `RoutesService` is provided to access the routes within Angular components. This ensures seamless integration and accessibility of both main application routes and PBC routes throughout the application. -## Styling the application +## Setting attributes + +Attributes are part of the HTML markup of an element and are reflected in the dom. + +Attributes can be either hard coded or set using Angular's property event bindings. Note, any automatically maps hyphenated attribute names to camelCase property names so a property called `max-rows` becomes `maxRows`. + +### Text + +To set a text attribute on a component, you can either hard code it in the template or use Angular square bracket template bindings. + +```ts +import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core'; + +@Component({ + selector: 'my-root', + template: ` + + + + `, + standalone: true, + schemas: [CUSTOM_ELEMENTS_SCHEMA], +}) +export class AppComponent { + resourceName = 'EVENT_INSERT_USER'; +} +``` -### Global styles -You can add global styles by modifying the main stylesheet located at **src/styles/styles.css**. This file contains styles that apply to the entire application. +### Boolean + +To set a boolean attribute on a component you can either hard code it in the template or use Angular template bindings `[]`. + +```ts +import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core'; + +@Component({ + selector: 'my-root', + template: ` + + Disabled button + + + + Disabled button + + `, + standalone: true, + schemas: [CUSTOM_ELEMENTS_SCHEMA], +}) +export class AppComponent { + isDisabled = true; +} +``` ---- +### Number + +To set a text attribute on a component, you can either hard code it in the template or use Angular template bindings `[]`. + +```ts +import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core'; + +@Component({ + selector: 'my-root', + template: ` + + + + + + + + `, + standalone: true, + schemas: [CUSTOM_ELEMENTS_SCHEMA], +}) +export class AppComponent { + maxRows = 100; +} +``` -### Styling components or pages -For more granular control, you can add styles specific to a page or component. +## Setting properties + +Properties are part of the Javascript object representation of the DOM element. They are used for dynamic interaction and setting complex non-primitive data types such as objects and arrays. + +You can set these using Angular template bindings `[]`. + +```ts +import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core'; + +@Component({ + selector: 'my-root', + template: ` + + `, + standalone: true, + schemas: [CUSTOM_ELEMENTS_SCHEMA], +}) +export class AppComponent { + jsonSchema = { + type: 'object', + properties: { + QUANTITY: { + type: 'number', + description: 'kotlin.Double', + }, + SIDE: { + type: 'string', + description: 'kotlin.String', + }, + }, + }; +} +``` + +## Handling events + +You can handle events from Foundation UI components using Angular's event binding `()`. + +```ts +import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core'; + +@Component({ + selector: 'my-root', + template: ` + + `, + standalone: true, + schemas: [CUSTOM_ELEMENTS_SCHEMA], +}) +export class AppComponent { + handleEvent(e): void { + console.log('form submitted', e); + } +} +``` -For example, if you want to have unique styling for the page that is displayed when a requested page cannot be found, create a stylesheet called **src/pages/NotFoundPage/NotFoundPage.css** with styles that only apply to that page. +## Styling the application + +### Global styles +You can add global styles by modifying the main stylesheet located at **src/styles/styles.css**. This file contains styles that apply to the entire application. --- From 3ddc345beb5029e927b60d4143e0691f3308c208 Mon Sep 17 00:00:00 2001 From: "patrick.oneil" Date: Tue, 26 Nov 2024 12:55:12 +0000 Subject: [PATCH 04/15] Adding angular attributes, properties and event sections --- .../022_framework-integration/003_integration-react.mdx | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/001_develop/03_client-capabilities/022_framework-integration/003_integration-react.mdx b/docs/001_develop/03_client-capabilities/022_framework-integration/003_integration-react.mdx index 26b1f28725..c006005e99 100644 --- a/docs/001_develop/03_client-capabilities/022_framework-integration/003_integration-react.mdx +++ b/docs/001_develop/03_client-capabilities/022_framework-integration/003_integration-react.mdx @@ -1,6 +1,6 @@ --- title: 'Framework integration - React' -sidebar_label: 'Angular' +sidebar_label: 'React' id: client-framework-integration-react keywords: [web, integrations, react] tags: @@ -59,8 +59,6 @@ npm run dev The development server launches your project and makes it available on localhost: -![React blank-app-seed](/integrations/react/react-blank-app-seed.png) - :::note The project is currently based on React 19, which is in the Release Candidate (RC) stage. This version provides improved support for integration with Web Components, making it easier to share data and manage state between React components and Web Components. ::: From ead914c5f88355a96d755b0ac45f0b2385552cda Mon Sep 17 00:00:00 2001 From: "patrick.oneil" Date: Tue, 26 Nov 2024 13:45:27 +0000 Subject: [PATCH 05/15] Adding react attributes, properties and event sections --- .../003_integration-react.mdx | 122 ++++++++++++++++++ 1 file changed, 122 insertions(+) diff --git a/docs/001_develop/03_client-capabilities/022_framework-integration/003_integration-react.mdx b/docs/001_develop/03_client-capabilities/022_framework-integration/003_integration-react.mdx index c006005e99..e04ad7e63b 100644 --- a/docs/001_develop/03_client-capabilities/022_framework-integration/003_integration-react.mdx +++ b/docs/001_develop/03_client-capabilities/022_framework-integration/003_integration-react.mdx @@ -105,6 +105,128 @@ The `RoutesProvider` uses the React Context API to make these routes available t Additionally, the `useRoutesContext` hook is provided to access the routes context within functional components. This ensures seamless integration and accessibility of both main application routes and PBC routes throughout the application. +## Setting attributes + +Attributes are part of the HTML markup of an element and are reflected in the dom. + +Attributes can be either hard coded or set using React's property event bindings. + +### Text + +To set a text attribute on a component, you can either hard code it in the template or set using the `{}` React bindings. React converts them when rendering in the DOM. + +```ts +export default function Example({}) { + + const resourceName = 'EVENT_INSERT_USER'; + return ( + + + + ); +} +``` + +### Boolean + +To set a boolean attribute on a component you can either hard code it in the template or use React template bindings `{}`. + +```ts +export default function Example({}) { + const isDisabled = true; + return ( + + Disabled button + + + + Disabled button + + ); +} +``` + +### Number + +To set a text attribute on a component, you can either hard code it in the template or use React template bindings `{}`. + +```ts +export default function Example({}) { + + const maxRows = 100; + return ( + + + + + + + + ); +} +``` + +## Setting properties + +Properties are part of the Javascript object representation of the DOM element. They are used for dynamic interaction and setting complex non-primitive data types such as objects and arrays. + +You can set these using React template bindings `{}`. + +```ts +export default function Example({}) { + + const jsonSchema = { + type: 'object', + properties: { + QUANTITY: { + type: 'number', + description: 'kotlin.Double', + }, + SIDE: { + type: 'string', + description: 'kotlin.String', + }, + }, + }; + return ( + + ); +} +``` + +## Handling events + +You can handle events from Foundation UI components using React's event binding `()`. Note, React prefixes events with `on` + +```ts +export default function Example() { + const handleSubmit = (event) => { + console.log(event.target); + } +} +return ( + +) +``` + ## Styling the application ### Global styles From b7efc506ee310608e6703f39b226384eec62bff3 Mon Sep 17 00:00:00 2001 From: "patrick.oneil" Date: Fri, 29 Nov 2024 10:53:25 +0000 Subject: [PATCH 06/15] Updating links --- .../022_framework-integration/002_integration-angular.mdx | 8 ++++---- .../022_framework-integration/003_integration-react.mdx | 8 ++++---- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/001_develop/03_client-capabilities/022_framework-integration/002_integration-angular.mdx b/docs/001_develop/03_client-capabilities/022_framework-integration/002_integration-angular.mdx index 6bd4ec8335..af6d2c4210 100644 --- a/docs/001_develop/03_client-capabilities/022_framework-integration/002_integration-angular.mdx +++ b/docs/001_develop/03_client-capabilities/022_framework-integration/002_integration-angular.mdx @@ -23,13 +23,13 @@ We shall also look briefly at: - the principles of routing and styling an application :::tip -You can find out more by looking into our [**example application**](/web/integrations/Angular/angular-example-application/), where you can look at the code and check the results against the running application. +You can find out more by looking into our [**example application**](https://github.com/genesiscommunitysuccess/howto-ui-integrations-angular/tree/main), where you can look at the code and check the results against the running application. ::: ## Setting up the Angular project :::info prerequisites -Before you start, ensure that you have [Node.js](https://nodejs.org/) and [Genx](https://learn.genesis.global/docs/getting-started/prerequisites/genx) installed on your system. +Before you start, ensure that you have [Node.js](https://nodejs.org/) and [Genx](../../../development-environment/genx/) installed on your system. ::: 1. Create a new Angular project. The example below creates a project called **myApp** using Genx with `--framework Angular`: @@ -67,14 +67,14 @@ The project is currently based on Angular 18. ## Project folder structure and main elements ### src/main.ts -This is the main entry point for the application. It bootstraps the app by rendering the **app.module.ts** module into the DOM. The file also registers [PBCs](../../../../server/packaged-business-capabilities/pbc-intro/) using `registerPBCs` +This is the main entry point for the application. It bootstraps the app by rendering the **app.module.ts** module into the DOM. The file also registers [PBCs](../../../business-components/) using `registerPBCs` --- ### src/pbc This folder contains components that are responsible for enabling the insertion of slots within the application. -These slots act as placeholders where content, provided by the registered Project Building Components ([PBCs](../../../../server/packaged-business-capabilities/pbc-intro/)), is rendered dynamically. The [PBCs](../../../../server/packaged-business-capabilities/pbc-intro/) are registered in the application through **main.ts**, ensuring that specific components can be inserted into the designated slots at runtime. +These slots act as placeholders where content, provided by the registered Project Building Components ([PBCs](../../../business-components/)), is rendered dynamically. The [PBCs](../../../business-components/) are registered in the application through **main.ts**, ensuring that specific components can be inserted into the designated slots at runtime. --- diff --git a/docs/001_develop/03_client-capabilities/022_framework-integration/003_integration-react.mdx b/docs/001_develop/03_client-capabilities/022_framework-integration/003_integration-react.mdx index e04ad7e63b..3271f31ad7 100644 --- a/docs/001_develop/03_client-capabilities/022_framework-integration/003_integration-react.mdx +++ b/docs/001_develop/03_client-capabilities/022_framework-integration/003_integration-react.mdx @@ -22,13 +22,13 @@ We shall also look briefly at: - the principles of routing and styling an application :::tip -You can find out more by looking into our [**example application**](/web/integrations/React/react-example-application/), where you can look at the code and check the results against the running application. +You can find out more by looking into our [**example application**](https://github.com/genesiscommunitysuccess/howto-ui-integrations-react/tree/main), where you can look at the code and check the results against the running application. ::: ## Setting up the React project :::info prerequisites -Before you start, ensure that you have [Node.js](https://nodejs.org/) and [Genx](https://learn.genesis.global/docs/getting-started/prerequisites/genx) installed on your system. +Before you start, ensure that you have [Node.js](https://nodejs.org/) and [Genx](../../../development-environment/genx/) installed on your system. ::: 1. reate a new React project. The example below creates a project called **myApp** using Genx with `--framework React`: @@ -66,12 +66,12 @@ The project is currently based on React 19, which is in the Release Candidate (R ## Project folder structure and main elements ### src/main.tsx -This is the main entry point for the application. It bootstraps the app by rendering the **App.tsx** component into the DOM. The file also registers [PBCs](../../../../server/packaged-business-capabilities/pbc-intro/) using `registerPBCs`. +This is the main entry point for the application. It bootstraps the app by rendering the **App.tsx** component into the DOM. The file also registers [PBCs](../../../business-components/) using `registerPBCs`. --- ### src/pbc -This folder contains components that are responsible for enabling the insertion of slots within the application. These slots act as placeholders where content, provided by the registered Project Building Components ([PBCs](../../../../server/packaged-business-capabilities/pbc-intro/)), is dynamically rendered. The [PBCs](../../../../server/packaged-business-capabilities/pbc-intro/) are registered in the application through **main.tsx**, ensuring that specific components can be inserted into the designated slots at runtime. +This folder contains components that are responsible for enabling the insertion of slots within the application. These slots act as placeholders where content, provided by the registered Project Building Components ([PBCs](../../../business-components/)), is dynamically rendered. The [PBCs](../../../business-components/) are registered in the application through **main.tsx**, ensuring that specific components can be inserted into the designated slots at runtime. --- From 1aa66f8c771b94f5d7c7aca7df197ac39e82a954 Mon Sep 17 00:00:00 2001 From: patrickoneill-genesis <151527745+patrickoneill-genesis@users.noreply.github.com> Date: Fri, 29 Nov 2024 10:59:13 +0000 Subject: [PATCH 07/15] Update docs/001_develop/03_client-capabilities/022_framework-integration/index.mdx Co-authored-by: Matt Walker <43502076+matteematt@users.noreply.github.com> --- .../03_client-capabilities/022_framework-integration/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/001_develop/03_client-capabilities/022_framework-integration/index.mdx b/docs/001_develop/03_client-capabilities/022_framework-integration/index.mdx index ba727e6875..edef1b512d 100644 --- a/docs/001_develop/03_client-capabilities/022_framework-integration/index.mdx +++ b/docs/001_develop/03_client-capabilities/022_framework-integration/index.mdx @@ -17,7 +17,7 @@ Foundation UI is web components based library. This means it can work alongside This section of our documentation will guide you in how to get Foundation UI working with your existing or preferred stack. -As Foundation UI is based on web components, the components need to be registered in the dom and can then be interacted by setting attributes, properties and listening to events in the same way as any HTML element. +As Foundation UI is based on web components, the components need to be registered in the DOM and can then be interacted by setting attributes, properties and listening to events in the same way as any HTML element. We recommend using our Genesis Create tool to create an Angular or React starter web application to see how the framework is integrated. If you have an existing application you can use the generated create application as a guide to integrating Foundation UI. From 5ce28e454441df701386ed5410c7d50e6adea0a8 Mon Sep 17 00:00:00 2001 From: patrickoneill-genesis <151527745+patrickoneill-genesis@users.noreply.github.com> Date: Fri, 29 Nov 2024 10:59:37 +0000 Subject: [PATCH 08/15] Update docs/001_develop/03_client-capabilities/022_framework-integration/index.mdx Co-authored-by: Matt Walker <43502076+matteematt@users.noreply.github.com> --- .../03_client-capabilities/022_framework-integration/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/001_develop/03_client-capabilities/022_framework-integration/index.mdx b/docs/001_develop/03_client-capabilities/022_framework-integration/index.mdx index edef1b512d..f0087e76bf 100644 --- a/docs/001_develop/03_client-capabilities/022_framework-integration/index.mdx +++ b/docs/001_develop/03_client-capabilities/022_framework-integration/index.mdx @@ -48,7 +48,7 @@ First thing you need to add the Foundation UI npm packages you require. Update y } ``` -Next, you need to create a file that imports and registers the Foundation UI framework and the Foundation UI header.. +Next, you need to create a file that imports and registers the Foundation UI framework, and the Foundation UI header if you want to use it. **genesis-components.ts** From de4a6b98d36e8315e32193b165410976fe5e729c Mon Sep 17 00:00:00 2001 From: patrickoneill-genesis <151527745+patrickoneill-genesis@users.noreply.github.com> Date: Fri, 29 Nov 2024 10:59:50 +0000 Subject: [PATCH 09/15] Update docs/001_develop/03_client-capabilities/022_framework-integration/002_integration-angular.mdx Co-authored-by: Matt Walker <43502076+matteematt@users.noreply.github.com> --- .../022_framework-integration/002_integration-angular.mdx | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/001_develop/03_client-capabilities/022_framework-integration/002_integration-angular.mdx b/docs/001_develop/03_client-capabilities/022_framework-integration/002_integration-angular.mdx index af6d2c4210..37d4883949 100644 --- a/docs/001_develop/03_client-capabilities/022_framework-integration/002_integration-angular.mdx +++ b/docs/001_develop/03_client-capabilities/022_framework-integration/002_integration-angular.mdx @@ -32,7 +32,8 @@ You can find out more by looking into our [**example application**](https://gith Before you start, ensure that you have [Node.js](https://nodejs.org/) and [Genx](../../../development-environment/genx/) installed on your system. ::: -1. Create a new Angular project. The example below creates a project called **myApp** using Genx with `--framework Angular`: +1. Create a new Angular project. You could use Genesis Create if you prefer. The example below creates a project called **myApp** using Genx with `--framework Angular`: + ```shell npx -y @genesislcap/genx@latest init myApp -s blank-app-seed --framework Angular -x From bd9d22f921aeb2b7e9a47fa16310ae8829427f82 Mon Sep 17 00:00:00 2001 From: patrickoneill-genesis <151527745+patrickoneill-genesis@users.noreply.github.com> Date: Fri, 29 Nov 2024 11:00:09 +0000 Subject: [PATCH 10/15] Update docs/001_develop/03_client-capabilities/022_framework-integration/003_integration-react.mdx Co-authored-by: Matt Walker <43502076+matteematt@users.noreply.github.com> --- .../022_framework-integration/003_integration-react.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/001_develop/03_client-capabilities/022_framework-integration/003_integration-react.mdx b/docs/001_develop/03_client-capabilities/022_framework-integration/003_integration-react.mdx index 3271f31ad7..6d53c53851 100644 --- a/docs/001_develop/03_client-capabilities/022_framework-integration/003_integration-react.mdx +++ b/docs/001_develop/03_client-capabilities/022_framework-integration/003_integration-react.mdx @@ -222,7 +222,7 @@ export default function Example() { return ( ) ``` From 2ec1f10550f8a087fbfed0ae3b9b7087cbf62567 Mon Sep 17 00:00:00 2001 From: "patrick.oneil" Date: Fri, 29 Nov 2024 14:00:05 +0000 Subject: [PATCH 11/15] Adding slot sections --- .../002_integration-angular.mdx | 43 ++++++++++++++++++- .../003_integration-react.mdx | 31 +++++++++++++ .../022_framework-integration/index.mdx | 4 +- 3 files changed, 74 insertions(+), 4 deletions(-) diff --git a/docs/001_develop/03_client-capabilities/022_framework-integration/002_integration-angular.mdx b/docs/001_develop/03_client-capabilities/022_framework-integration/002_integration-angular.mdx index 37d4883949..561baa3fb0 100644 --- a/docs/001_develop/03_client-capabilities/022_framework-integration/002_integration-angular.mdx +++ b/docs/001_develop/03_client-capabilities/022_framework-integration/002_integration-angular.mdx @@ -113,7 +113,7 @@ Additionally, the `RoutesService` is provided to access the routes within Angula Attributes are part of the HTML markup of an element and are reflected in the dom. -Attributes can be either hard coded or set using Angular's property event bindings. Note, any automatically maps hyphenated attribute names to camelCase property names so a property called `max-rows` becomes `maxRows`. +Attributes can be either hard coded or set using the Angular property bindings. Note, Angular automatically maps hyphenated attribute names to camelCase property names so a property called `max-rows` becomes `maxRows`. ### Text @@ -269,6 +269,47 @@ You can add global styles by modifying the main stylesheet located at **src/styl --- +## Slots + +Many components in FoundationUI have slots which act as placeholders to allow you to fill components with your own markup. + +This is equivalent to [content projection](https://angular.dev/guide/components/content-projection) in Angular. + +This example shows how you can use the slots in the Modal component + +```typescript +import { AfterViewInit, Component, CUSTOM_ELEMENTS_SCHEMA, ElementRef, ViewChild } from '@angular/core'; +import { FormsModule } from '@angular/forms'; + +@Component({ +selector: 'modal-example', +template: ` + Show modal + +

Top slot

+ Main content in the modal +
+ Slotted content in the bottom +
+
+ `, + standalone: true, + schemas: [CUSTOM_ELEMENTS_SCHEMA], + imports: [FormsModule], +}) +export class ModalExampleComponent implements AfterViewInit { + @ViewChild('modal') modalRef!: ElementRef; + + showModal() { + if (this.modalRef.nativeElement) { + this.modalRef.nativeElement.show() + } + } + +} +``` + ### Design tokens Design tokens are declared in the **src/styles/design-tokens.json** file. They offer an effective way to manage and apply styles in your application in a consistent and maintainable manner. diff --git a/docs/001_develop/03_client-capabilities/022_framework-integration/003_integration-react.mdx b/docs/001_develop/03_client-capabilities/022_framework-integration/003_integration-react.mdx index 6d53c53851..78d8ec31d4 100644 --- a/docs/001_develop/03_client-capabilities/022_framework-integration/003_integration-react.mdx +++ b/docs/001_develop/03_client-capabilities/022_framework-integration/003_integration-react.mdx @@ -241,6 +241,37 @@ For example, if you want to have styling for the page that is displayed when a r --- +## Slots + +Many components in FoundationUI have slots which act as placeholders to allow you to fill components with your own markup. + +This example shows how you can use the slots in the Modal component. + +```typescript +export function MyComponent() { + const modalRef = useRef(null); + + const handleClick = (ref) => { + if (modalRef.current) { + modalRef.current.show(); + } + }; + + return ( + handleClick()}>Open Modal + +

Top slot

+ Main content in the modal +
+ Slotted content in the bottom +
+
+ ); +} +``` + ### Design tokens Design tokens are declared in the **src/styles/design-tokens.json** file. They offer an effective way to manage and apply styles in your application in a consistent and maintainable manner. diff --git a/docs/001_develop/03_client-capabilities/022_framework-integration/index.mdx b/docs/001_develop/03_client-capabilities/022_framework-integration/index.mdx index f0087e76bf..051fe2518f 100644 --- a/docs/001_develop/03_client-capabilities/022_framework-integration/index.mdx +++ b/docs/001_develop/03_client-capabilities/022_framework-integration/index.mdx @@ -17,13 +17,11 @@ Foundation UI is web components based library. This means it can work alongside This section of our documentation will guide you in how to get Foundation UI working with your existing or preferred stack. -As Foundation UI is based on web components, the components need to be registered in the DOM and can then be interacted by setting attributes, properties and listening to events in the same way as any HTML element. - We recommend using our Genesis Create tool to create an Angular or React starter web application to see how the framework is integrated. If you have an existing application you can use the generated create application as a guide to integrating Foundation UI. ## Registering components -As Foundation UI is based on web components the first step is registering the components in the dom. To do this you to import the required modules and components and register the design system (which applies the styles). +As Foundation UI is based on web components, the first step is registering the components in the dom. To do this you to import the required modules and components and register the design system (which applies the styles). First thing you need to add the Foundation UI npm packages you require. Update your package.json to include the following (note this is not an exhaustive list of all the Foundation UI packages). From 16dc88e09e110946b65267dfa9c0a2d25ea5740e Mon Sep 17 00:00:00 2001 From: "patrick.oneil" Date: Fri, 29 Nov 2024 15:31:05 +0000 Subject: [PATCH 12/15] Adding dependency injection tokens --- .../002_integration-angular.mdx | 67 +++++++++++++++++- .../003_integration-react.mdx | 70 +++++++++++++++++++ 2 files changed, 135 insertions(+), 2 deletions(-) diff --git a/docs/001_develop/03_client-capabilities/022_framework-integration/002_integration-angular.mdx b/docs/001_develop/03_client-capabilities/022_framework-integration/002_integration-angular.mdx index 561baa3fb0..742a0f9655 100644 --- a/docs/001_develop/03_client-capabilities/022_framework-integration/002_integration-angular.mdx +++ b/docs/001_develop/03_client-capabilities/022_framework-integration/002_integration-angular.mdx @@ -279,7 +279,6 @@ This example shows how you can use the slots in the Modal component ```typescript import { AfterViewInit, Component, CUSTOM_ELEMENTS_SCHEMA, ElementRef, ViewChild } from '@angular/core'; -import { FormsModule } from '@angular/forms'; @Component({ selector: 'modal-example', @@ -296,7 +295,6 @@ template: ` `, standalone: true, schemas: [CUSTOM_ELEMENTS_SCHEMA], - imports: [FormsModule], }) export class ModalExampleComponent implements AfterViewInit { @ViewChild('modal') modalRef!: ElementRef; @@ -310,6 +308,71 @@ export class ModalExampleComponent implements AfterViewInit { } ``` +## Dependency Injection + +Foundation UI has a suite of services that can be added to your application via dependency injection. + +If you want to use the Connect service, the best approach is to create an injection token and register it in your app module. + +**connect-service.ts** + +```ts +import { Connect, getConnect } from '@genesislcap/foundation-comms'; +import { InjectionToken } from '@angular/core'; + +export const connectService = getConnect(); +export const CONNECT_TOKEN = new InjectionToken('Logger'); +``` + +**app.module.ts** +```ts +@NgModule({ + ... + providers: [ + { provide: CONNECT_TOKEN, useValue: connectService }, + ... + ], + ... +}) +``` + +**your-angular-component.ts** + +After adding the connect service to your module providers using an injection token, you can add it to any class using Angular DI. + +This component will use the Connect `snapshot` method to retrieve data from a dataserver query `ALL_TRADES` and render it in a list. + +```typescript +import { OnInit, Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core'; +import { NgForOf } from '@angular/common'; +import { Connect } from '@genesislcap/foundation-comms'; +import { CONNECT_TOKEN } from 'path/to/connect.service'; + +@Component({ +selector: 'di-example', + template: ` +
    +
  • Direction: {{item.TRADE_ID}} Quantity: {{item.QUANTITY}} Ticker: {{item.TICKER}}
  • +
`, + standalone: true, + schemas: [CUSTOM_ELEMENTS_SCHEMA], + imports: [ NgForOf ], + +}) +export class DIExampleComponent implements OnInit { + constructor(@Inject(CONNECT_TOKEN) private connect: Connect) {} + + async ngOnInit() { + const response = await this.connect.snapshot('ALL_TRADES') + + if (response.ROW?.length) { + this.data = response.ROW; + } + } +} +``` + + ### Design tokens Design tokens are declared in the **src/styles/design-tokens.json** file. They offer an effective way to manage and apply styles in your application in a consistent and maintainable manner. diff --git a/docs/001_develop/03_client-capabilities/022_framework-integration/003_integration-react.mdx b/docs/001_develop/03_client-capabilities/022_framework-integration/003_integration-react.mdx index 78d8ec31d4..0c1e1fc158 100644 --- a/docs/001_develop/03_client-capabilities/022_framework-integration/003_integration-react.mdx +++ b/docs/001_develop/03_client-capabilities/022_framework-integration/003_integration-react.mdx @@ -272,6 +272,76 @@ export function MyComponent() { } ``` +## Dependency Injection + +Foundation UI has a suite of services that can be added to your application via dependency injection. + +If you want to use the Connect service, the best approach is to create a class to resolve the dependency injection boilerplate and export it. + +**connect-service.ts** +```ts +import { DI } from '@microsoft/fast-foundation'; +import { Connect } from '@genesislcap/foundation-comms'; +import { API_DATA } from '../config'; + +class ConnectService { + private container = DI.getOrCreateDOMContainer(); + private connect: Connect = this.container.get(Connect); + + getContainer() { + return this.container; + } + + getConnect() { + return this.connect; + } + + isConnected() { + return this.connect.isConnected; + } + + init() { + return this.connect.connect(API_DATA.URL); + } +} + +export const connectService = new ConnectService(); +``` + +**your-react-component.ts** + +This component will use the Connect `snapshot` method to retrieve data from a dataserver query `ALL_TRADES` and render it in a list. + +```ts +import React, { useState, useEffect } from 'react'; +import { connectService } from './connect.service'; // your file location + +export function YourReactComponent { + + const [data, setData] = useState([]); + + useEffect(() => { + const getData = async () => { + const response = await connectService.getConnect().snapshot('ALL_TRADES') + + if (response.ROW?.length) { + setData(response.ROW); + } + } + + getData(); + }, []); + + return ( +
    + {data.map((item) => ( +
  • Direction: {item.DIRECTION} Quantity: {item.QUANTITY} Ticker: {item.TICKER}
  • + ))} +
+ ); +} +``` + ### Design tokens Design tokens are declared in the **src/styles/design-tokens.json** file. They offer an effective way to manage and apply styles in your application in a consistent and maintainable manner. From 57e0f5019a08ae7d71efb05b009299ce4dc2bdf3 Mon Sep 17 00:00:00 2001 From: patrickoneill-genesis <151527745+patrickoneill-genesis@users.noreply.github.com> Date: Fri, 29 Nov 2024 16:23:49 +0000 Subject: [PATCH 13/15] Update docs/001_develop/03_client-capabilities/022_framework-integration/002_integration-angular.mdx Co-authored-by: Matt Walker <43502076+matteematt@users.noreply.github.com> --- .../022_framework-integration/002_integration-angular.mdx | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/001_develop/03_client-capabilities/022_framework-integration/002_integration-angular.mdx b/docs/001_develop/03_client-capabilities/022_framework-integration/002_integration-angular.mdx index 742a0f9655..f6033858bf 100644 --- a/docs/001_develop/03_client-capabilities/022_framework-integration/002_integration-angular.mdx +++ b/docs/001_develop/03_client-capabilities/022_framework-integration/002_integration-angular.mdx @@ -312,7 +312,8 @@ export class ModalExampleComponent implements AfterViewInit { Foundation UI has a suite of services that can be added to your application via dependency injection. -If you want to use the Connect service, the best approach is to create an injection token and register it in your app module. +For example, if you want to use the Connect service, the best approach is to create an injection token and register it in your app module. + **connect-service.ts** From 1b422b2d8e4acb44dd33c6ff4aca4399887c6ca6 Mon Sep 17 00:00:00 2001 From: patrickoneill-genesis <151527745+patrickoneill-genesis@users.noreply.github.com> Date: Fri, 29 Nov 2024 16:24:26 +0000 Subject: [PATCH 14/15] Update docs/001_develop/03_client-capabilities/022_framework-integration/002_integration-angular.mdx Co-authored-by: Matt Walker <43502076+matteematt@users.noreply.github.com> --- .../022_framework-integration/002_integration-angular.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/001_develop/03_client-capabilities/022_framework-integration/002_integration-angular.mdx b/docs/001_develop/03_client-capabilities/022_framework-integration/002_integration-angular.mdx index f6033858bf..636e77c4e5 100644 --- a/docs/001_develop/03_client-capabilities/022_framework-integration/002_integration-angular.mdx +++ b/docs/001_develop/03_client-capabilities/022_framework-integration/002_integration-angular.mdx @@ -372,7 +372,7 @@ export class DIExampleComponent implements OnInit { } } ``` - +You can follow this same prosedure for any other service from the framework that works via depdendency injection. ### Design tokens From 20d39b9e40c7ce0c1f6f92d1bb22726b1b575f18 Mon Sep 17 00:00:00 2001 From: "patrick.oneil" Date: Fri, 29 Nov 2024 16:29:02 +0000 Subject: [PATCH 15/15] Adding info part --- .../022_framework-integration/002_integration-angular.mdx | 4 +++- .../022_framework-integration/003_integration-react.mdx | 4 ++++ 2 files changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/001_develop/03_client-capabilities/022_framework-integration/002_integration-angular.mdx b/docs/001_develop/03_client-capabilities/022_framework-integration/002_integration-angular.mdx index 636e77c4e5..e1917fa584 100644 --- a/docs/001_develop/03_client-capabilities/022_framework-integration/002_integration-angular.mdx +++ b/docs/001_develop/03_client-capabilities/022_framework-integration/002_integration-angular.mdx @@ -314,6 +314,9 @@ Foundation UI has a suite of services that can be added to your application via For example, if you want to use the Connect service, the best approach is to create an injection token and register it in your app module. +:::info +You can follow this same procedure for any other service from the framework that works via dependency injection. +::: **connect-service.ts** @@ -372,7 +375,6 @@ export class DIExampleComponent implements OnInit { } } ``` -You can follow this same prosedure for any other service from the framework that works via depdendency injection. ### Design tokens diff --git a/docs/001_develop/03_client-capabilities/022_framework-integration/003_integration-react.mdx b/docs/001_develop/03_client-capabilities/022_framework-integration/003_integration-react.mdx index 0c1e1fc158..cb8b423e30 100644 --- a/docs/001_develop/03_client-capabilities/022_framework-integration/003_integration-react.mdx +++ b/docs/001_develop/03_client-capabilities/022_framework-integration/003_integration-react.mdx @@ -278,6 +278,10 @@ Foundation UI has a suite of services that can be added to your application via If you want to use the Connect service, the best approach is to create a class to resolve the dependency injection boilerplate and export it. +:::info +You can follow this same procedure for any other service from the framework that works via dependency injection. +::: + **connect-service.ts** ```ts import { DI } from '@microsoft/fast-foundation';