diff --git a/.eslintignore b/.eslintignore index f47a86b..d54e2b0 100644 --- a/.eslintignore +++ b/.eslintignore @@ -1,2 +1,3 @@ +cookbook/src/gatsby-theme-carbon/** +dist/** node_modules/** -dist/** \ No newline at end of file diff --git a/.prettierignore b/.prettierignore new file mode 100644 index 0000000..273db18 --- /dev/null +++ b/.prettierignore @@ -0,0 +1,2 @@ +cookbook/.cache/** +cookbook/src/gatsby-theme-carbon/** diff --git a/cookbook/.markdownlint.json b/cookbook/.markdownlint.json index 9d01f65..66791a2 100644 --- a/cookbook/.markdownlint.json +++ b/cookbook/.markdownlint.json @@ -7,5 +7,5 @@ "MD033": false, "MD040": false, "no-trailing-spaces": true, - "MD024": { "siblings_only": true} + "MD024": { "siblings_only": true } } diff --git a/cookbook/gatsby-browser.js b/cookbook/gatsby-browser.js index e848af3..c6c9925 100644 --- a/cookbook/gatsby-browser.js +++ b/cookbook/gatsby-browser.js @@ -1 +1 @@ -import './src/styles/index.scss'; +import "./src/styles/index.scss"; diff --git a/cookbook/gatsby-config.js b/cookbook/gatsby-config.js index e6409c8..d0470ee 100644 --- a/cookbook/gatsby-config.js +++ b/cookbook/gatsby-config.js @@ -1,30 +1,29 @@ -const siteTitle = 'Merative SPM UI Addon Development Environment' - -var sitePrefix = process.env.SITE_PREFIX || "/spm-ui-addon-devenv" -console.log(`Using SITE_PREFIX: '${sitePrefix}'`) +const siteTitle = "Merative SPM UI Addon Development Environment"; +const sitePrefix = process.env.SITE_PREFIX || "/spm-ui-addon-devenv"; module.exports = { siteMetadata: { title: siteTitle, - description: 'Merative Social Program Management UI Addon Development Environment', - keywords: 'merative,curam,containers', + description: + "Merative Social Program Management UI Addon Development Environment", + keywords: "merative,curam,containers", }, pathPrefix: sitePrefix, plugins: [ { - resolve: 'gatsby-plugin-manifest', + resolve: "gatsby-plugin-manifest", options: { name: siteTitle, short_name: siteTitle, start_url: sitePrefix, - background_color: '#ffffff', - theme_color: '#0062ff', - display: 'browser', - icon: 'node_modules/gatsby-theme-carbon/src/images/favicon.svg' + background_color: "#ffffff", + theme_color: "#0062ff", + display: "browser", + icon: "node_modules/gatsby-theme-carbon/src/images/favicon.svg", }, }, { - resolve: 'gatsby-theme-carbon', + resolve: "gatsby-theme-carbon", options: { isSearchEnabled: true, withWebp: true, diff --git a/cookbook/src/data/nav-items.yaml b/cookbook/src/data/nav-items.yaml index 7c7ef18..d64448c 100644 --- a/cookbook/src/data/nav-items.yaml +++ b/cookbook/src/data/nav-items.yaml @@ -1,6 +1,6 @@ - title: Overview pages: - - path: /overview + - path: /overview - title: Setting up for development pages: - title: Prerequisites and supported software @@ -32,10 +32,10 @@ path: /deployment - title: Customizing the Case Overview path: /extend-case-overview -# - title: Integrating components with UIM -# pages: -# - title: Integrating components with the UIM page -# path: /integrate-addon-in-uim + # - title: Integrating components with UIM + # pages: + # - title: Integrating components with the UIM page + # path: /integrate-addon-in-uim hasDivider: true - title: Reference pages: diff --git a/cookbook/src/pages/404.js b/cookbook/src/pages/404.js index 4cbd5ed..73a882f 100644 --- a/cookbook/src/pages/404.js +++ b/cookbook/src/pages/404.js @@ -1,10 +1,10 @@ -import React from 'react'; -import { FourOhFour } from 'gatsby-theme-carbon'; +import React from "react"; +import { FourOhFour } from "gatsby-theme-carbon"; const links = [ - { href: '/components/markdown', text: 'Markdown' }, - { href: '/components/Aside', text: 'Aside' }, - { href: '/components/demo', text: 'Demo' }, + { href: "/components/markdown", text: "Markdown" }, + { href: "/components/Aside", text: "Aside" }, + { href: "/components/demo", text: "Demo" }, ]; const Custom404 = () => ; diff --git a/cookbook/src/pages/build.mdx b/cookbook/src/pages/build.mdx index 493490a..808cae1 100644 --- a/cookbook/src/pages/build.mdx +++ b/cookbook/src/pages/build.mdx @@ -3,16 +3,15 @@ title: Building during development description: Building components during development --- -Build your components in your development environment during development. For more information about commands and command configuration, see the [Command reference](command-reference). - +Build your components in your development environment during development. For more information about commands and command configuration, see the [Command reference](command-reference). 1. Build your component. Ideally, run this command each time you add new files to the repository. - ``` + ``` npm run build ``` -2. Run a development build to integrate the component with the web client application. Any updates you make to existing files while the development build is running are reflected in the application. +2. Run a development build to integrate the component with the web client application. Any updates you make to existing files while the development build is running are reflected in the application. If you don't use the GraphQL mock service, use this command to run the development build. The GraphQL data from the REST Service is used. @@ -21,7 +20,7 @@ Build your components in your development environment during development. For mo ``` If you use the GraphQL mock service, use this command to run the development build. The command is the same as the `npm run dev` command, but prioritizes the data from the mock GraphQL service over the real REST Service when running in Social Program Management. - + ``` export GRAPHQL_SERVER_URL=http://localhost:4000/graphql && npm run dev-with-mockgraphql ``` diff --git a/cookbook/src/pages/command-reference.mdx b/cookbook/src/pages/command-reference.mdx index 383d359..c56b3ca 100644 --- a/cookbook/src/pages/command-reference.mdx +++ b/cookbook/src/pages/command-reference.mdx @@ -23,7 +23,7 @@ After you run the command, any JavaScript or SCSS files that are updated are aut export GRAPHQL_SERVER_URL=http://localhost:4000/graphql && npm run dev-with-mockgraphql ``` -This command is the same as the `npm run dev` command, but prioritizes the data from the mock GraphQL service over the real REST Service when running in SPM. It requires the `CLIENT_DIR` environment variable to be set. +This command is the same as the `npm run dev` command, but prioritizes the data from the mock GraphQL service over the real REST Service when running in SPM. It requires the `CLIENT_DIR` environment variable to be set. ``` npm run test diff --git a/cookbook/src/pages/development-environment.mdx b/cookbook/src/pages/development-environment.mdx index 17abcdd..67d2fad 100644 --- a/cookbook/src/pages/development-environment.mdx +++ b/cookbook/src/pages/development-environment.mdx @@ -5,30 +5,30 @@ description: Development environment Among other files, the repository contains the following significant items. Depending on your operating system, you might need to show hidden files to see them all. - ``` - SPM-UI-ADDON-DEV - └───.storybook The stories for the sample components. Add stories for your components here. - └───cookbook The developer documentation source files. - └───packages The repository provides these packages. - └───carbon-addon-devenv - └───custom-carbon-addons - └───graphql-mocks - .env A starter React environment variable configuration file. - ``` +``` +SPM-UI-ADDON-DEV +└───.storybook The stories for the sample components. Add stories for your components here. +└───cookbook The developer documentation source files. +└───packages The repository provides these packages. + └───carbon-addon-devenv + └───custom-carbon-addons + └───graphql-mocks + .env A starter React environment variable configuration file. +``` ## The `carbon-addon-devenv` package -The `carbon-addon-devenv` package contains the development environment to work with Carbon components and to develop custom Carbon add-on components. +The `carbon-addon-devenv` package contains the development environment to work with Carbon components and to develop custom Carbon add-on components. -It contains two sample add-on components to help you to get started, which need a Java renderer and a GraphQL query to integrate them onto a UIM page. +It contains two sample add-on components to help you to get started, which need a Java renderer and a GraphQL query to integrate them onto a UIM page. - ``` - carbon-addon-devenv - └───sample_renderers - └───src - └───stories - PersonFolio.stories.js - ``` +``` +carbon-addon-devenv +└───sample_renderers +└───src +└───stories + PersonFolio.stories.js +``` An `npm` file is provided for the following open source packages: @@ -43,12 +43,12 @@ An `npm` file is provided for the following open source packages: The `custom-carbon-addons` package is where you must place all of your custom files, to ensure that upgrades do not affect your custom content. - ``` - custom-carbon-addons - └───renderers - │ index.js - └───src - package.json_sample +``` +custom-carbon-addons +└───renderers +│ index.js +└───src + package.json_sample ``` @@ -57,15 +57,15 @@ The `custom-carbon-addons` package is where you must place all of your custom fi The `graphql-mocks` package is where you can place data for mock GraphQL queries. This package essentially provides a lightweight mock GraphQL service that simulates the real GraphQL service from SPM. - ``` - graphql-mocks - └───resolvers - │ └─── data - │ index.js - └───typeDefs - └───server.js - package.json - ``` +``` +graphql-mocks +└───resolvers +│ └─── data +│ index.js +└───typeDefs +└───server.js + package.json +``` The `resolvers` directory contains the resolver functions, also known as data fetcher functions in GraphQL terminology, that resolve to data values. The `data` subdirectory in the `resolvers` directory contains the diff --git a/cookbook/src/pages/development-process.mdx b/cookbook/src/pages/development-process.mdx index 1ae8c6a..b61c6f3 100644 --- a/cookbook/src/pages/development-process.mdx +++ b/cookbook/src/pages/development-process.mdx @@ -16,7 +16,7 @@ The Carbon Design System provides design guidance for the development of user in - For more information about IBM Carbon Design System, see the [Carbon v10 website](https://v10.carbondesignsystem.com/) and the [Carbon v10 Storybook](https://v10-react.carbondesignsystem.com/?path=/story/getting-started--welcome). - If you are new to Carbon and React development, see [Carbon React Frameworks](https://v10.carbondesignsystem.com/developing/frameworks/react/) and the [Carbon v10 React tutorial](https://v10.carbondesignsystem.com/developing/react-tutorial/overview/), and the Facebook [Create React App](https://github.com/facebook/create-react-app/blob/main/packages/cra-template/template/README.md) documentation to get you started. - + # Back-end development Using the Social Program Management server development environment and GraphQL functionality, implement domain definitions and the services (business logic) to create/update/get the data for your components. GraphQL is recommended for the back-end data service, especially for data intensive screens, see [https://www.ibm.com/docs/en/spm/8.0.2?topic=apis-graphql](https://www.ibm.com/docs/en/spm/8.0.2?topic=apis-graphql). diff --git a/cookbook/src/pages/environment-variables.mdx b/cookbook/src/pages/environment-variables.mdx index 5d52d7e..0fff874 100644 --- a/cookbook/src/pages/environment-variables.mdx +++ b/cookbook/src/pages/environment-variables.mdx @@ -2,6 +2,7 @@ title: Environment variables description: Environment variables --- + The following environment variables are available for the development environment. ## Basic configuration diff --git a/cookbook/src/pages/extend-case-overview.mdx b/cookbook/src/pages/extend-case-overview.mdx index df8ff01..60eed1d 100644 --- a/cookbook/src/pages/extend-case-overview.mdx +++ b/cookbook/src/pages/extend-case-overview.mdx @@ -8,55 +8,55 @@ The Case Overview provides an Entitlements card by default, which is rendered wi The following guidance assumes that you have developed some Carbon components and want to extend the Case Overview page. For more information about developing custom Carbon components, see [Creating a custom Carbon add-on component](/new-custom-component.md). 1. On the server, create a new domain definition for your custom component in the EJBServer custom component directory. For example, CUSTOM_CASEOVERVIEW. - For more information about configuring domain definitions, see [Configuring a domain definition](https://www.ibm.com/docs/en/spm/8.0.2?topic=workflow-configuring-domain-definition). + For more information about configuring domain definitions, see [Configuring a domain definition](https://www.ibm.com/docs/en/spm/8.0.2?topic=workflow-configuring-domain-definition). 2. Update the `DomainsConfig.xml` file in your custom component in the `webclient` directory to map the new domain definition to a new Java renderer. If the `DomainsConfig.xml` file does not exist in your custom component, you must create it. For example: - ```XML - - - - - - ``` + ```XML + + + + + + ``` 3. Implement a custom Java renderer, for example `CustomCaseOverviewRenderer`, by extending the existing `CaseOverviewRenderer` Java renderer as shown in the following example. This example extends the Case Overview page with the `ComponentX` component. In your custom Java renderer, you render both the existing components and the custom components. You create an HTML element for the custom components and call a JavaScript renderer function to integrate the custom components into the renderer. - ```java - public void render(final Field field, final DocumentFragment fragment, - final RendererContext context, final RendererContract contract) - throws ClientException, DataAccessException, PlugInException { - - // render the OOTB Case overview UI - final DocumentFragment baseFragment = - fragment.getOwnerDocument().createDocumentFragment(); - super.render(field, baseFragment, context, contract); - fragment.appendChild(baseFragment); - - // create a HTML element to render the custom carbon component - // and extend the OOTB Carbon components - final Element carbonWrapperDiv = - fragment.getOwnerDocument().createElement("div"); - final String carbonWrapperDivID = "CarbonWrapperDiv"; - carbonWrapperDiv.setAttribute("id", carbonWrapperDivID); - HTMLUtils.appendComment(carbonWrapperDiv, "filler"); - carbonWrapperDiv.setAttribute("class", "spm-custom-component"); - - // append the new element to the fragment - fragment.appendChild(carbonWrapperDiv); - // placeholder in case overview before content is rendered - HTMLUtils.appendComment(carbonWrapperDiv.getPreviousSibling(), "filler"); - - // render the custom Carbon component into the new HTML element - // For example, to render a custom Carbon ComponentX it would be the following - final Map map = new HashMap(); - // Make a call to integrate ComponentX into the renderer by using - // the ComponentXRenderer JavaScript renderer function - includeCarbonComponent(context, carbonWrapperDivID, "{}", "{}", - "window.spmcustom.renderers.ComponentX.ComponentXRenderer", - map); - } - ``` + ```java + public void render(final Field field, final DocumentFragment fragment, + final RendererContext context, final RendererContract contract) + throws ClientException, DataAccessException, PlugInException { + + // render the OOTB Case overview UI + final DocumentFragment baseFragment = + fragment.getOwnerDocument().createDocumentFragment(); + super.render(field, baseFragment, context, contract); + fragment.appendChild(baseFragment); + + // create a HTML element to render the custom carbon component + // and extend the OOTB Carbon components + final Element carbonWrapperDiv = + fragment.getOwnerDocument().createElement("div"); + final String carbonWrapperDivID = "CarbonWrapperDiv"; + carbonWrapperDiv.setAttribute("id", carbonWrapperDivID); + HTMLUtils.appendComment(carbonWrapperDiv, "filler"); + carbonWrapperDiv.setAttribute("class", "spm-custom-component"); + + // append the new element to the fragment + fragment.appendChild(carbonWrapperDiv); + // placeholder in case overview before content is rendered + HTMLUtils.appendComment(carbonWrapperDiv.getPreviousSibling(), "filler"); + + // render the custom Carbon component into the new HTML element + // For example, to render a custom Carbon ComponentX it would be the following + final Map map = new HashMap(); + // Make a call to integrate ComponentX into the renderer by using + // the ComponentXRenderer JavaScript renderer function + includeCarbonComponent(context, carbonWrapperDivID, "{}", "{}", + "window.spmcustom.renderers.ComponentX.ComponentXRenderer", + map); + } + ``` diff --git a/cookbook/src/pages/feedback.mdx b/cookbook/src/pages/feedback.mdx index 174e916..5ff3d52 100644 --- a/cookbook/src/pages/feedback.mdx +++ b/cookbook/src/pages/feedback.mdx @@ -4,7 +4,7 @@ description: Feedback --- If you have feedback, or want to raise an issue and you are not a Merative - representative, please contact your local Merative account executive. +representative, please contact your local Merative account executive. To submit an issue or provide feedback, create an [issue](https://github.com/merative/spm-ui-addon-devenv/issues). @@ -24,9 +24,9 @@ Provide clear and concise steps to reproduce the behavior. For example: -* One -* Two -* Three +- One +- Two +- Three ### Expected behavior diff --git a/cookbook/src/pages/graphql-query.mdx b/cookbook/src/pages/graphql-query.mdx index a011251..9b08fd2 100644 --- a/cookbook/src/pages/graphql-query.mdx +++ b/cookbook/src/pages/graphql-query.mdx @@ -16,7 +16,7 @@ Use the following guidance to familiarize yourself with GraphQL queries in Socia 1. You must enable GraphQL and GraphQL introspection by setting the `curam.graphql.endpoint.enabled` and `curam.graphql.introspection.enabled` system properties, see [Configuring GraphQL properties](https://www.ibm.com/docs/en/spm/8.0.2?topic=graphql-configuring-properties). 2. Build the application in your Tomcat environment to make the GraphQL APIs available, see [Building and deploying GraphQL APIs on Tomcat](https://www.ibm.com/docs/en/spm/8.0.2?topic=apis-building-deploying-graphql-tomcat). 3. View the available resources on an existing GraphQL API, such as the `readIntegratedCase` API, see [Viewing the GraphQL queries by using the GraphiQL IDE](https://www.ibm.com/docs/en/spm/8.0.2?topic=graphql-viewing-queries-by-using-graphiql-ide). -4. Run some test queries to understand how to get the data you need from GraphQL APIs, see [Testing a GraphQL query by using the GraphiQL IDE](https://www.ibm.com/docs/en/spm/8.0.2?topic=graphql-testing-query-by-using-graphiql-ide). +4. Run some test queries to understand how to get the data you need from GraphQL APIs, see [Testing a GraphQL query by using the GraphiQL IDE](https://www.ibm.com/docs/en/spm/8.0.2?topic=graphql-testing-query-by-using-graphiql-ide). # Creating GraphQL queries and GraphQL APIs @@ -25,9 +25,11 @@ When you understand how GraphQL queries work, you can create your own queries, s For data that is not available through existing GraphQL APIs, create your own GraphQL APIs, see [Developing a GraphQL API](https://www.ibm.com/docs/en/spm/8.0.2?topic=graphql-developing-apis). # Setting up the mock GraphQL service + While the REST Service provides the real data from the GraphQL queries in Social Program Management, you can use a lightweight mock GraphQL service to enable rapid development almost exclusively in your front-end environment. To develop your Carbon components before the real GraphQL queries are available, you can use the mock GraphQL service with Carbon components in Storybook or when testing the integration with SPM. -To add mock data to the mock GraphQL service, complete the following steps in the `graphql-mocks` package. Refer to the provided examples in the directories for guidance. - - In the `typeDefs` directory, add a new GraphQL query type definition and update the `index.js` file in that directory to export it. - - In the `resolvers` directory, add a new resolver and update the `index.js` in that directory to export it. - - Add the data to the `resolvers/data` subdirectory and import the data in your new resolver. +To add mock data to the mock GraphQL service, complete the following steps in the `graphql-mocks` package. Refer to the provided examples in the directories for guidance. + +- In the `typeDefs` directory, add a new GraphQL query type definition and update the `index.js` file in that directory to export it. +- In the `resolvers` directory, add a new resolver and update the `index.js` in that directory to export it. +- Add the data to the `resolvers/data` subdirectory and import the data in your new resolver. diff --git a/cookbook/src/pages/index.mdx b/cookbook/src/pages/index.mdx index 289a820..d8a7f4d 100755 --- a/cookbook/src/pages/index.mdx +++ b/cookbook/src/pages/index.mdx @@ -1,4 +1,4 @@ -import HomepageTemplate from 'gatsby-theme-carbon/src/templates/Homepage'; +import HomepageTemplate from "gatsby-theme-carbon/src/templates/Homepage"; export default HomepageTemplate; diff --git a/cookbook/src/pages/new-custom-component.mdx b/cookbook/src/pages/new-custom-component.mdx index 63326dc..c7e99f9 100644 --- a/cookbook/src/pages/new-custom-component.mdx +++ b/cookbook/src/pages/new-custom-component.mdx @@ -14,10 +14,10 @@ The steps do not need to be done in this order, but it is currently the recommen - In the `custom-carbon-addon/src/scss/addons` directory, create an SCSS file for the component. For example, `componentX.scss`. - Import `componentX.scss` into the `index.scss` file. 3. Implement a query provider in Apollo Client. An Apollo Client query provider enables the cached data from GraphQL to be integrated with a React component. Complete the following steps: - - Create a directory in the `custom-carbon-addon/src/apollo-client-hooks/hooks` directory. For example, `componentX`. - - Create the JavaScript files for your query provider with reference to the samples in `carbon-addons-devenv/src/apollo-client-hooks/hooks/hook_samples`. - Use the `ApolloClientDataProvider`, `ApolloClientQueryProvider`, and `ApolloClientHookTemplate` React helper components in `carbon-addons-devenv/src/apollo-client-hooks/hooks/core` to help with this task. - - Create a query that accesses data from the back-end by importing `gql` and `useQuery` from `@apollo/client`. If you already have a GraphQL query that serves a number of components, you can use that query. + - Create a directory in the `custom-carbon-addon/src/apollo-client-hooks/hooks` directory. For example, `componentX`. + - Create the JavaScript files for your query provider with reference to the samples in `carbon-addons-devenv/src/apollo-client-hooks/hooks/hook_samples`. + Use the `ApolloClientDataProvider`, `ApolloClientQueryProvider`, and `ApolloClientHookTemplate` React helper components in `carbon-addons-devenv/src/apollo-client-hooks/hooks/core` to help with this task. + - Create a query that accesses data from the back-end by importing `gql` and `useQuery` from `@apollo/client`. If you already have a GraphQL query that serves a number of components, you can use that query. 4. Test the Carbon component in Storybook. To test `componentX` in storybook, you can test components in isolation before you integrate them into Social Program Management. - In the `stories` directory of the `custom-carbon-addon` package, create a directory for the component. For example, `custom-carbon-addon/stories/componentX`. Run `npm run storybook` to test components. -5. Create a JavaScript renderer function. You can use the `Renderer.create()` helper function to implement a JavaScript Renderer function to integrate the component into a Java Renderer on the UIM page. You can place your renderer functions in the `custom-carbon-addon/renderers` directory. For example, create the`CarbonComponentXViewRenderer` function. +5. Create a JavaScript renderer function. You can use the `Renderer.create()` helper function to implement a JavaScript Renderer function to integrate the component into a Java Renderer on the UIM page. You can place your renderer functions in the `custom-carbon-addon/renderers` directory. For example, create the`CarbonComponentXViewRenderer` function. diff --git a/cookbook/src/pages/overview.mdx b/cookbook/src/pages/overview.mdx index 483825a..fba39aa 100644 --- a/cookbook/src/pages/overview.mdx +++ b/cookbook/src/pages/overview.mdx @@ -8,17 +8,17 @@ You can create complex views with React JavaScript components based on Carbon an Social Program Management developers can: -* Use a lightweight JavaScript development environment that complements the existing Java™ and UIM web client development environment. -* Develop complex views with the latest front-end tools and libraries, and integrate them into the Social Program Management web client. -* Develop front-end content quickly and iteratively. JavaScript developers can view their changes without a client build. -* Use GraphQL and Apollo Client to configure complex data queries. JavaScript Developers can use mock GraphQL APIs to enable rapid development of custom components and test them in the development environment (not shown in diagram). -* Build robust front-end content through easier test automation. +- Use a lightweight JavaScript development environment that complements the existing Java™ and UIM web client development environment. +- Develop complex views with the latest front-end tools and libraries, and integrate them into the Social Program Management web client. +- Develop front-end content quickly and iteratively. JavaScript developers can view their changes without a client build. +- Use GraphQL and Apollo Client to configure complex data queries. JavaScript Developers can use mock GraphQL APIs to enable rapid development of custom components and test them in the development environment (not shown in diagram). +- Build robust front-end content through easier test automation. ![React Development Environment](../images/SPM_Addons_IDE.svg) The Social Program Management UI Addon Development Environment provides: -* Documentation: Instructions to get up and running in a JavaScript environment, with examples and design guidance. -* Code: Commands to integrate your compiled JavaScript into the Social Program Management web client. -* Samples: Some sample React components that contain IBM Carbon styles and GraphQL queries. -* Storybook: You can use Storybook to render components locally for testing. +- Documentation: Instructions to get up and running in a JavaScript environment, with examples and design guidance. +- Code: Commands to integrate your compiled JavaScript into the Social Program Management web client. +- Samples: Some sample React components that contain IBM Carbon styles and GraphQL queries. +- Storybook: You can use Storybook to render components locally for testing. diff --git a/cookbook/src/pages/prerequisites.mdx b/cookbook/src/pages/prerequisites.mdx index 4ed4479..99f7d0d 100644 --- a/cookbook/src/pages/prerequisites.mdx +++ b/cookbook/src/pages/prerequisites.mdx @@ -14,21 +14,21 @@ Node.js is a prerequisite for installing the Merative Social Program Managment U ## Merative Social Program Management -| UI Addon Development Environment | Social Program Management | IBM Carbon | -| :------------------------------- | :------------------------ | :----------- | -| 1.0.0 | 8.0.1, 8.0.2, 8.0.3 | v10 | -| 1.1.0 | 8.0.1, 8.0.2, 8.0.3 | v10 | -| vNext | vNext | v11 | +| UI Addon Development Environment | Social Program Management | IBM Carbon | +| :------------------------------- | :------------------------ | :--------- | +| 1.0.0 | 8.0.1, 8.0.2, 8.0.3 | v10 | +| 1.1.0 | 8.0.1, 8.0.2, 8.0.3 | v10 | +| vNext | vNext | v11 | ## Integrated Development Environment (IDE) The SPM UI Addons Development Environment does not depend on a specific IDE, you can choose your own. There are many IDEs that you can choose, such as Microsoft Visual Studio Code, Atom, or Sublime. However, Merative uses Microsoft Visual Studio Code to develop Social Program Managment UI Addons, it supports many plugins that make development faster and easier, for example it supports the following tools: -* Linting tools (ESLint) -* Code formatters (Prettier) -* Debugging tools (Debugger for Chrome) -* Documentation tools (JSDoc) +- Linting tools (ESLint) +- Code formatters (Prettier) +- Debugging tools (Debugger for Chrome) +- Documentation tools (JSDoc) Merative does not own, develop, or support these tools. @@ -39,4 +39,4 @@ The repository includes some basic configuration for Microsoft Visual Studio Cod The open source software is hosted on GitHub so we recommend that you use Git for source control. [Git](http://git-scm.com/): The [Github Guide to - Installing Git](https://help.github.com/articles/set-up-git/) is a good source of information. +Installing Git](https://help.github.com/articles/set-up-git/) is a good source of information. diff --git a/cookbook/src/pages/samples-reference.mdx b/cookbook/src/pages/samples-reference.mdx index 6ef62ce..b5ae69d 100644 --- a/cookbook/src/pages/samples-reference.mdx +++ b/cookbook/src/pages/samples-reference.mdx @@ -5,21 +5,22 @@ description: Samples reference Some sample Carbon component are provided in the `carbon-addons-devenv` package, which you can use as a reference or aid when starting to develop new Carbon components. - - PersonFolio - - Logo +- PersonFolio +- Logo These samples contain all that is needed for Carbon components: - - The React component - - Sass - - A query provider in Apollo Client - - A JavaScript renderer wrapper function +- The React component +- Sass +- A query provider in Apollo Client +- A JavaScript renderer wrapper function - Unit tests, a storybook wrapper, and a JavaScript documentation example are also provided. +Unit tests, a storybook wrapper, and a JavaScript documentation example are also provided. The sample components are ready to be fully implemented and integrated into a custom UIM page by using a Java Renderer. ### Examples of integrating components into a Java renderer + For guidance, the following code snippets, which don't include the imports, demonstrate how the PersonFolio and Logo sample components can be integrated into a Java Renderer. Configuring a Java render is described in [Rendering components on a UIM page](spm-uim-integration) An example of integrating the sample PersonFolio component into a domain Java renderer on a UIM page is shown. @@ -93,4 +94,3 @@ public class LogoSampleRenderer extends AbstractViewRenderer { } } ``` - diff --git a/cookbook/src/pages/setup.mdx b/cookbook/src/pages/setup.mdx index 9cccec3..59dc013 100644 --- a/cookbook/src/pages/setup.mdx +++ b/cookbook/src/pages/setup.mdx @@ -4,26 +4,25 @@ description: Setting up your development environment --- 1. Download and install Node.js from [https://nodejs.org](https://nodejs.org). The installation includes the npm (Node package manager), which you can use to install your Node packages. -2. Download and install your IDE. Microsoft Visual Studio Code [https://code.visualstudio.com/download](https://code.visualstudio.com/download) is the recommended IDE. Install any needed extensions, such as ESLint or Prettier. +2. Download and install your IDE. Microsoft Visual Studio Code [https://code.visualstudio.com/download](https://code.visualstudio.com/download) is the recommended IDE. Install any needed extensions, such as ESLint or Prettier. 3. Download the `main` branch of the SPM UI Addon Development Environment code from [https://github.com/merative/spm-ui-addon-devenv](https://github.com/merative/spm-ui-addon-devenv). You can choose one of the following options: + 1. Download as Zip. Select the Code drop-down menu and select the **Download Zip** option. 2. Open with GitHub Desktop. - 3. Clone the repository. - If you have Git set up, you can clone the repository by opening a command prompt and running the command: + 3. Clone the repository. If you have Git set up, you can clone the repository by opening a command prompt and running the command: - ``` - git clone https://github.com/merative/spm-ui-addon-devenv.git - ``` +``` +git clone https://github.com/merative/spm-ui-addon-devenv.git +``` -1. Install the SPM UI Addon Development Environment on your computer by using npm. To install the code, change to the `spm-ui-addon-devenv` directory and run the command: +4. Install the SPM UI Addon Development Environment on your computer by using npm. To install the code, change to the `spm-ui-addon-devenv` directory and run the command: - ``` - npm ci - ``` +``` +npm ci +``` -2. You can now open the repository in your IDE. For example, Microsoft Visual Studio Code. +5. You can now open the repository in your IDE. For example, Microsoft Visual Studio Code. -3. Configure your React development environment variables. Before you start to work with React components, you must set node environment variables in the `.env` file. -Update the `.env` file, which sets the environment variables for production builds. For information about the enviroment variables to set in these files, see [Environment variables](environment-variables). +6. Configure your React development environment variables. Before you start to work with React components, you must set node environment variables in the `.env` file. Update the `.env` file, which sets the environment variables for production builds. For information about the enviroment variables to set in these files, see [Environment variables](environment-variables). diff --git a/cookbook/src/pages/spm-uim-integration.mdx b/cookbook/src/pages/spm-uim-integration.mdx index 9e0d8db..a59462b 100644 --- a/cookbook/src/pages/spm-uim-integration.mdx +++ b/cookbook/src/pages/spm-uim-integration.mdx @@ -11,40 +11,46 @@ Complete the following steps to integrate the component into a Java renderer: 1. Create a custom UIM page in your web client custom components directory. 2. Create a Java renderer in the web client custom component directory. Refer to the PersonFolio and Logo samples for guidance, see [Samples reference](samples-reference). - - For this example, create the `CarbonComponentXViewRenderer.java` Java renderer in the `JavaSource/custom` subdirectory. The renderer extends the - `AbstractViewRenderer`` (curam.util.client.domain.render.view.AbstractViewRenderer) class. - - Make a call to the `includeCarbonComponent()` function to call the custom component. For more information about the `includeCarbonComponent()` function, see the the Java documentation. Call the following code from the `render()` method: - ``` - // making the call to integrate the ComponentX component into the renderer via - // the ComponentXRenderer JavaScript renderer function - includeCarbonComponent(context, carbonWrapperDivID, labels, "{}", - "window.spmcustom.renderers.ComponentX.ComponentXRenderer", - map); - ``` - You can specify the following code variables as optional configuration: - - ``` - // labels to be used to pass translated labels into the carbon component. - final String labels = "{}"; - // the id of the HTML element on the renderer that will host the HTML content from the Carbon component - final String carbonWrapperDivID = "ComponentX"; - // map can be used for extra configuration that may be needed, such as passing argument to GraphQL queries - final Map map = new HashMap(); - ``` -2. Configure your Java renderer by doing the following: - - On the server, create a `CUSTOM_CARBON_COMPONENT_X` domain definition for your custom component in the the `EJBServer` custom component directory. For more information about configuring domain definitions see [https://www.ibm.com/docs/en/spm/8.0.2?topic=workflow-configuring-domain-definition ](https://www.ibm.com/docs/en/spm/8.0.2?topic=workflow-configuring-domain-definition). + + - For this example, create the `CarbonComponentXViewRenderer.java` Java renderer in the `JavaSource/custom` subdirectory. The renderer extends the + `AbstractViewRenderer`` (curam.util.client.domain.render.view.AbstractViewRenderer) class. + - Make a call to the `includeCarbonComponent()` function to call the custom component. For more information about the `includeCarbonComponent()` function, see the the Java documentation. Call the following code from the `render()` method: + +``` +// making the call to integrate the ComponentX component into the renderer via +// the ComponentXRenderer JavaScript renderer function +includeCarbonComponent(context, carbonWrapperDivID, labels, "{}", +"window.spmcustom.renderers.ComponentX.ComponentXRenderer", +map); +``` + +You can specify the following code variables as optional configuration: + +``` +// labels to be used to pass translated labels into the carbon component. +final String labels = "{}"; +// the id of the HTML element on the renderer that will host the HTML content from the Carbon component +final String carbonWrapperDivID = "ComponentX"; +// map can be used for extra configuration that may be needed, such as passing argument to GraphQL queries +final Map map = new HashMap(); +``` + +3. Configure your Java renderer by doing the following: + - On the server, create a `CUSTOM_CARBON_COMPONENT_X` domain definition for your custom component in the the `EJBServer` custom component directory. For more information about configuring domain definitions see [https://www.ibm.com/docs/en/spm/8.0.2?topic=workflow-configuring-domain-definition](https://www.ibm.com/docs/en/spm/8.0.2?topic=workflow-configuring-domain-definition). - Update the `DomainsConfig.xml` file in your custom component in the webclient directory to map the new domain definition to the new Java renderer. If this file does not exist in your custom component, you must create it. For example: - ``` - - - - - - - ``` - - In the renderer, create a HTML element to host the output from the Carbon component. This HTML element must have the `spm-custom-component` CSS class name. For example: - - ``` -
- ``` + +``` + + + + + + +``` + +4. In the renderer, create a HTML element to host the output from the Carbon component. This HTML element must have the `spm-custom-component` CSS class name. For example: + +``` +
+``` diff --git a/cookbook/src/styles/index.scss b/cookbook/src/styles/index.scss index 40b1268..ecbe08e 100644 --- a/cookbook/src/styles/index.scss +++ b/cookbook/src/styles/index.scss @@ -1,6 +1,6 @@ // This is where your application styles could go. -[class*='PageHeader-module--page-header'] { +[class*="PageHeader-module--page-header"] { height: auto !important; min-height: 13rem; max-height: 15rem; @@ -8,7 +8,7 @@ } @media (min-width: 99rem) { - [class*='PageHeader-module--text'] { + [class*="PageHeader-module--text"] { font-size: 4rem !important; } } @@ -22,39 +22,39 @@ line-height: 1.2rem; } -[class*='Tabs-module--panel'] { +[class*="Tabs-module--panel"] { padding-bottom: 1rem; max-width: calc(67% + 1rem); } -[class*='Tabs-module--panel'] ul.bx--list--unordered { +[class*="Tabs-module--panel"] ul.bx--list--unordered { width: 100%; } -[class*='Tabs-module--panel'] ul.bx--list--unordered li, -[class*='Tabs-module--panel'] div.bx--row p { +[class*="Tabs-module--panel"] ul.bx--list--unordered li, +[class*="Tabs-module--panel"] div.bx--row p { font-size: 14px; } -[class*='Tabs-module--panel'] ul + pre { +[class*="Tabs-module--panel"] ul + pre { margin-top: 1rem; } @media (min-width: 66rem) { - [class*='Tabs-module--panel'] { + [class*="Tabs-module--panel"] { padding-bottom: 1rem; max-width: 75%; } - [class*='Markdown-module--list'] { + [class*="Markdown-module--list"] { max-width: 90%; margin-bottom: 10px; } - [class*='Tabs-module--panel'] [class*='Code-module--row'] { + [class*="Tabs-module--panel"] [class*="Code-module--row"] { width: 100%; } - [class*='Markdown-module--list'].bx--list--nested { + [class*="Markdown-module--list"].bx--list--nested { width: calc(100% - 1rem); margin-bottom: 10px; } @@ -70,54 +70,83 @@ max-width: 90%; } - li [class*='InlineNotification-module--notification'].bx--col-md-6.bx--col-lg-8 { + li + [class*="InlineNotification-module--notification"].bx--col-md-6.bx--col-lg-8 { display: block; flex: 0 0 100%; max-width: 100%; } h3#global-properties + div.bx--row table.page-table tbody tr td:nth-child(1), - h3#liberty-runtime + div.bx--row + div.bx--row table.page-table tbody tr td:nth-child(1), - h3#batch-jobs + div.bx--row + div.bx--row table.page-table tbody tr td:nth-child(1) { + h3#liberty-runtime + + div.bx--row + + div.bx--row + table.page-table + tbody + tr + td:nth-child(1), + h3#batch-jobs + + div.bx--row + + div.bx--row + table.page-table + tbody + tr + td:nth-child(1) { width: 35%; } - h3#ibm-mq + div.bx--row + div.bx--row table.page-table tbody tr td:nth-child(1), - h3#static-content-server + div.bx--row table.page-table tbody tr td:nth-child(1), + h3#ibm-mq + + div.bx--row + + div.bx--row + table.page-table + tbody + tr + td:nth-child(1), + h3#static-content-server + + div.bx--row + table.page-table + tbody + tr + td:nth-child(1), h3#xml-server + div.bx--row table.page-table tbody tr td:nth-child(1), - h3#universal-access-react-app-optional + div.bx--row table.page-table tbody tr td:nth-child(1) { + h3#universal-access-react-app-optional + + div.bx--row + table.page-table + tbody + tr + td:nth-child(1) { width: 30%; } } @media (max-width: 66rem) { - [class*='Tabs-module--panel'] { + [class*="Tabs-module--panel"] { max-width: 100%; } - [class*='Tabs-module--panel'] [class*='Code-module--row'] { + [class*="Tabs-module--panel"] [class*="Code-module--row"] { width: 100%; } } // Hide SideBar and Footer when printing @media print { - [class*='LeftNavWrapper-module--expanded'] { + [class*="LeftNavWrapper-module--expanded"] { display: none; } - [class*='Footer-module--footer'] { + [class*="Footer-module--footer"] { display: none; } } -[class*='Code-module--row'] { +[class*="Code-module--row"] { width: 70%; } -[class*='Markdown-module--list'] { +[class*="Markdown-module--list"] { width: 77.5%; } -li [class*='Code-module--container'] { +li [class*="Code-module--container"] { width: 100%; } @@ -129,17 +158,17 @@ li [class*='Code-module--container'] { width: 86%; } -[class*='InlineNotification-module--notification'].bx--col-md-6.bx--col-lg-8 { +[class*="InlineNotification-module--notification"].bx--col-md-6.bx--col-lg-8 { display: block; flex: 0 0 80%; max-width: 80%; } -[class*='Markdown-module--list-item'] .bx--row { +[class*="Markdown-module--list-item"] .bx--row { max-width: 100%; } -[class*='Caption-module--caption'] { +[class*="Caption-module--caption"] { max-width: 95%; }