-
Notifications
You must be signed in to change notification settings - Fork 276
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
[templates/angular-xmcloud][templates/node-xmcloud-proxy] Angular and XM Cloud Proxy Readme updates #1989
Merged
Merged
[templates/angular-xmcloud][templates/node-xmcloud-proxy] Angular and XM Cloud Proxy Readme updates #1989
Changes from all commits
Commits
Show all changes
16 commits
Select commit
Hold shift + click to select a range
5f2b02a
additional readme updates
yavorsk 5d6240a
update changelog
yavorsk 4d899df
fix typos and wording updates
yavorsk c029d4f
List properly not supported features
yavorsk 503dca0
Update README.md - Added TODO's, refactoring
illiakovalenko 94b53a7
updates to readme's
yavorsk 098d66c
Update README.md
anasplat 060d9d1
Update README.md
illiakovalenko c04888f
additional angular xmc readme updates
yavorsk 4abecce
work on proxy readme TODO's
apathania22 87888e4
wording and formatting updates
yavorsk 98ce4bc
additional wording and typo fixes
yavorsk b1b5c21
small update
yavorsk cb5e3b2
links fixes
yavorsk 5621a75
minor fix
yavorsk 864ca0d
Merge branch 'dev' into feature/JSS-4644
yavorsk File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
100 changes: 64 additions & 36 deletions
100
packages/create-sitecore-jss/src/templates/angular-xmcloud/README.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,60 +1,88 @@ | ||
| # Angular for XMCloud | ||
| # Angular for XM Cloud | ||
|
|
||
| > Sitecore JSS Angular App for XM Cloud. For the current release this feature is experimental. | ||
| > Sitecore JSS Angular App for XM Cloud. This feature is currently in public beta. | ||
| > If you encounter any issues or bugs, please submit a new issue in the [JSS GitHub Repo](https://github.com/Sitecore/jss) | ||
|
|
||
| [Documentation](<TODO>) | ||
| [Documentation](https://doc.sitecore.com/xmc/en/developers/jss/latest/jss-xmc/introducing-sitecore-javascript-rendering-sdk.html) | ||
|
|
||
| This Single Page Application (SPA) built with Angular is designed to be fully compatible with XM Cloud, incorporating several key add-ons and features to streamline the development process and enable seamless integration. The supported key features are as follows: | ||
| This Single Page Application (SPA) built with Angular is designed to be fully compatible with XM Cloud, incorporating several key add-ons and features to streamline the development process and enable seamless integration. | ||
|
|
||
| The Angular XM Cloud integration consists of two parts: | ||
| - `XM Cloud Angular`: simplifies connecting the application to XM Cloud and configuring the integration of multiple composable Sitecore products, and provides out-of-the-box helper components. | ||
| - `XM Cloud Proxy`: Adds integration with XM Cloud for the JSS SPA applications and enables editing, personalization and component A/B/n testing support. See [XM Cloud Proxy](../node-xmcloud-proxy/) for more information. | ||
|
|
||
| The following key features are supported: | ||
|
|
||
| - `Context ID`: The Context ID environment variable simplifies setting up and configuring XM Cloud solutions. It's a unified identifier that maps to all your configured resources, such as content, sites, files, forms, and integration settings. | ||
|
|
||
| - `XM Cloud Pages editing integration`: full integration with Pages - the dynamic visual page editor of XM Cloud. | ||
|
|
||
| - `XM Cloud proxy personalization` with embedded personalization and A/B Component Test support. | ||
| - `XM Cloud proxy personalization` with embedded personalization and component A/B/n testing. | ||
|
|
||
| - `Forms support`: provides the capability to consume and post Sitecore Forms from JSS apps. Sitecore Forms is a form-authoring framework that enables marketers to author their own forms, collect data, and analyze form performance. | ||
| - `Forms support`: consume and post XM Cloud Forms in JSS apps. Using Forms, marketers can create forms, collect data, and analyze form performance. | ||
|
|
||
| This SPA is tailored to enhance development workflows and enable full utilization of XM Cloud’s capabilities, providing a seamless and efficient foundation for developers. | ||
| - `Internationalization` support. | ||
|
|
||
| ## Components and Supporting Applications | ||
| > The following features and integrations are not supported by Angular and Proxy apps for XM Cloud: | ||
| > - Multisite | ||
| > - The XM Cloud Components application | ||
| > - BYOC components | ||
| > - SXA sitemap, redirects, error pages | ||
| > - Sitecore Experience Editor | ||
|
|
||
| The following components and supporting applications have been added to the Angular base app to ensure compatibility with XM Cloud: | ||
| ## Getting Started | ||
|
|
||
| - `XM Cloud Angular`: Adds support for the Sitecore Context data, which simplifies connecting the application to XM Cloud and configuring the integration of multiple composable Sitecore products. Angular app provides components and can be used during development. Once the app is built and its build artifacts are copied into the proxy, the proxy app can be used to connect to an XMCloud instance and render its content (including personalization etc). | ||
| ### Development | ||
|
|
||
| - `XM Cloud Proxy`: Adds integration with XMCloud for the JSS SPA applications and enables editing, personalization and A/B component testing support. | ||
| When building and running your app in connected (development) mode the proxy application is not needed. | ||
|
|
||
| ## Environment Variables | ||
| Execute the following commands: | ||
| ```shell | ||
| npm install | ||
| npm run build | ||
| npm run start:connected | ||
| ``` | ||
|
|
||
| The following environment variables can be set to configure the angular app. You can use the `.env` file located in the root of the app or set these directly in the environment (for example, in containers). | ||
| > The following features are not supported in development mode: | ||
| > * personalization | ||
| > * server-side rendering | ||
| > * editing | ||
|
|
||
| | Parameter | Description | | ||
| | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | ||
| | `PROXY_HOST` | Your XM Cloud Proxy hostname is needed to build the app and execute the client-side requests against the proxy server. Default value `http://localhost:3000` | | ||
| | `PROXY_BUILD_PATH` | Your XM Cloud Proxy server path is needed to build the app. The build output will be copied to the XMCloud Proxy application path. Default value `<xmcloud_proxy_path>\dist`. | ||
| | `SITECORE_EDGE_CONTEXT_ID` | The Context ID, which covers many system configurations, required for connecting to the XM Cloud back end. This is an XM Cloud system environment variable. When the application runs on the XM Cloud rendering host, this value is always set to the preview Context ID. | | ||
| | `SITECORE_API_KEY` | The API key for GRAPH_QL_ENDPOINT authentication. For Experience Edge, you can find the API key in the Sites dashboard by opening the actions menu for a site and navigating to Settings > Developer settings. Copy the value for SITECORE_API_KEY. For a preview endpoint (a CM instance either on XM Cloud or locally), use your preview API Key from the CM instance. | ||
| | `SITECORE_API_HOST` | The API hostname, needed to build the application. This should be used in combination with SITECORE_API_KEY for local development or local container setup. For example, https://<xmc_cm_host>.sitecorecloud.io. | | ||
| | `GRAPH_QL_ENDPOINT` | Your GraphQL Edge endpoint. This is typically optional. By default, the endpoint is calculated using the resolved Sitecore API hostname + the `graphQLEndpointPath` defined in your `package.json`. For a preview endpoint (a CM instance on XM Cloud or a local one), the value is <xmc_cm_host>/sitecore/api/graph/edge. | | ||
| | `SITECORE_SITE_NAME` | The name of your site. This variable overrides the config.appName defined in the package.json file. You can find this value in the Sites dashboard by opening the actions menu for a site and navigating to Settings > Developer settings. Default value `<appName>`, | ||
| ` | | ||
| | `DEFAULT_LANGUAGE` | The default language of your app. Default value `en` | | ||
| | `DEBUG` | Optional. Debug level for the proxy. Set the DEBUG environment variable to 'sitecore-jss:*,proxy*,http-proxy-middleware*' to see all logs. Refer to the [official docs](https://doc.sitecore.com/xp/en/developers/hd/latest/sitecore-headless-development/debug-logging-in-jss-apps.html#namespaces) for all the available namespaces. | ||
| ### Production | ||
|
|
||
| To build and run in production mode you need to have your Angular app side by side with the [Node XM Cloud proxy](../node-xmcloud-proxy/). | ||
|
|
||
| ## Build & run | ||
| Execute the following commands: | ||
|
|
||
| ### Running the application in production mode | ||
| For the Angular app: | ||
| ```shell | ||
| npm install | ||
|
|
||
| To build and run in production mode you need to have your angular app side by side with the [Node XM CLoud proxy](https://github.com/Sitecore/jss/tree/dev/packages/create-sitecore-jss/src/templates/node-xmcloud-proxy). For additional information on how to set up and run SPA app in production mode against XM CLoud instance you can check the [spa-starters](https://github.com/sitecorelabs/xmcloud-foundation-head/tree/main/headapps/spa-starter) monoreopo readme. | ||
| # It will build the angular app and copy the the resulting `/dist` folder into the specified proxy app folder | ||
| npm run build | ||
| ``` | ||
|
|
||
| 1. Run `npm install` for both angular and proxy apps | ||
| 2. Run `npm run build` in the angular app root; this will build the angular app and copy the the resulting `/dist` folder into the specified proxy app folder | ||
| 3. Run `npm run start` in the proxy app root | ||
| For the Proxy app: | ||
|
|
||
| ### Running the application in connected mode | ||
| ```shell | ||
| npm install | ||
| npm run start | ||
| ``` | ||
|
|
||
| When building and running your app in connected mode the proxy application is not needed. However, please note that certain features, such as personalization, server-side rendering, and editing, will not be available. | ||
| For additional information on how to set up and run a SPA app in production mode against an XM Cloud instance you can check the [spa-starters monorepo](https://github.com/sitecorelabs/xmcloud-foundation-head/tree/main/headapps/spa-starter) in the XM Cloud Foundation Starter Kit. | ||
|
|
||
| 1. Run `npm install` | ||
| 2. Run `npm run build` | ||
| 3. Run `npm run start:connected` | ||
| ## Environment Variables | ||
|
|
||
| The following environment variables can be used to configure the angular app. You can use the `.env` file located in the root of the app or set these directly in the environment (for example, in containers). | ||
|
|
||
| | Parameter | Description | | ||
| | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | ||
| | `PROXY_HOST` | Your XM Cloud Proxy hostname is needed to build the app and execute the client-side requests against the proxy server. Default value `http://localhost:3000` | | ||
| | `PROXY_BUILD_PATH` | Your XM Cloud Proxy server path is needed to build the app. The build output will be copied to the XM Cloud Proxy application path. Default value `<xmcloud_proxy_path>\dist`. | ||
| | `SITECORE_EDGE_CONTEXT_ID` | The Context ID, which covers many system configurations, is required for connecting to the XM Cloud back end. This is an XM Cloud system environment variable. When the application runs on the XM Cloud editing host, this value is always set to the preview Context ID. | | ||
| | `SITECORE_API_KEY` | The API key for GRAPH_QL_ENDPOINT authentication. It should be used in combination with SITECORE_API_HOST for local development when connecting to a local XM Cloud instance | ||
| | `SITECORE_API_HOST` | The API hostname, needed to build the application. This should be used in combination with SITECORE_API_KEY for local development. For example, https://<xmc_cm_host>.sitecorecloud.io. | | ||
| | `GRAPH_QL_ENDPOINT` | Your GraphQL Edge endpoint. This is typically optional. By default, the endpoint is calculated using the resolved Sitecore API hostname + the `graphQLEndpointPath` defined in your `package.json`. For a preview endpoint (a CM instance on XM Cloud or a local one), the value is <xmc_cm_host>/sitecore/api/graph/edge. | | ||
| | `SITECORE_SITE_NAME` | The name of your site. This variable overrides the config.appName defined in the package.json file. You can find this value in the Sites dashboard by opening the actions menu for a site and navigating to Settings > Developer settings. The default value is the name of your app. | | ||
| | `DEFAULT_LANGUAGE` | The default language of your app. The default value is `en` | | ||
| | `DEBUG` | Optional. Debug level for the application. Set the DEBUG environment variable to 'sitecore-jss:*' to see all logs. Refer to the [official docs](https://doc.sitecore.com/xmc/en/developers/jss/22/jss-xmc/debug-logging-in-jss-apps.html#namespaces) for all the available namespaces. | ||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Confirm with Anastasia whether we need to say this in addition to "The XM Cloud Components application", as Liz stated this is the same thing.