Blog posts by Linh Hoang

Blog posts by Linh Hoang2024-09-04T08:25:21.0000000Zhttps://world.optimizely.com/blogs/linh-hoang/ Optimizely World Optimizely Headless Form Setup1. Create empty CMS applications First, let’s setup an empty CMS application. Install the NuGet packages in your solution using the NuGet Package Manager in Visual Studio or with the command line: <code>dotnet add package EPiServer.CMS</code> 2. Setup headless Optimizely Forms API Optimizely Headless Form API consists of one main NuGet package, Optimizely.Cms.Forms.Service, and some additional NuGet packages let you install only the necessary functionality. Install the NuGet packages in your solution using the NuGet Package Manager in Visual Studio or with the command line: <code>dotnet add package Optimizely.Cms.Forms.Service</code> Configure form headless API options Configure the API in ConfigureServices in startup.cs. <pre class="language-csharp"><code>services.AddOptimizelyFormsService(options => { options.EnableOpenApiDocumentation = true; options.FormCorsPolicy = new FormCorsPolicy { AllowOrigins = new string[] { "*" }, //Enter '*' to allow any origins, multiple origins separate by comma AllowCredentials = true }; options.OpenIDConnectClients.Add(new() { Authority = "" //Enter the client's domain that requires authentication. The domain must include the protocol, e.g., https://localhost:3000. }); });</code></pre> 3. Authentication using OpenIDConnect Install Episerver.OpenIDConnect package using the NuGet Package Manager in Visual Studio or with the command line: <code>dotnet add package Episerver.OpenIDConnect.UI</code> Configure encryption key for OpenIDConnect. <pre class="language-csharp"><code>public class FormServiceOptionsPostConfigure : IPostConfigureOptions<OptimizelyFormsServiceOptions> { private readonly OpenIddictServerOptions _options; public FormServiceOptionsPostConfigure(IOptions<OpenIddictServerOptions> options) { _options = options.Value; } public void PostConfigure(string name, OptimizelyFormsServiceOptions options) { foreach (var client in options.OpenIDConnectClients) { foreach (var key in _options.EncryptionCredentials.Select(c => c.Key)) { client.EncryptionKeys.Add(key); } foreach (var key in _options.SigningCredentials.Select(c => c.Key)) { client.SigningKeys.Add(key); } } } }</code></pre> Configure OpenIdConnect in Startup.cs. <pre class="language-csharp"><code>services.AddOpenIDConnect<ApplicationUser>( useDevelopmentCertificate: true, signingCertificate: null, encryptionCertificate: null, createSchema: true ); services.AddOpenIDConnectUI(); services.TryAddEnumerable(ServiceDescriptor.Singleton<IPostConfigureOptions<OptimizelyFormsServiceOptions>, FormServiceOptionsPostConfigure>());</code></pre> 4. Create key/secret using OIDC UI and test your authentication Open “OpenID Connect” tab in Settings, create new application then input your client id and client secret <img src="/link/473f3a8f485540b28cbcad6fb7f07cf2.aspx" width="893" height="415" /> Test if it all works by making a POST request in Postman to /api/episerver/connect/token with the following parameters: <ul> <ul> <li>client_id: api-client</li> <li>client_secret: SuperSecret</li> <li>grant_type: client_credentials</li> </ul> </ul> You'll receive a time-limited access token. <img src="/link/ec921bd271dc40bdbaecdd4ff1e73d0d.aspx" width="914" height="704" /> 5. Api specification You should have the following endpoints available on your host site: <ul> <li>GET – /_forms/v1/forms/{ContentKey}?language={Language} – Retrieve form data with form elements by content key</li> <li>PUT – /_forms/v1/forms/ – Submit the form.</li> </ul> To verify that the API is working properly, open the Form Headless API in your browser: http://<your-site-url>/_forms/v1/forms/<ContentKey>?language=en Note: ContentKey is the content guid id without hypen For more api details: <a href="https://docs.developers.optimizely.com/content-management-system/v1.2.0-forms/docs/set-up-headless-optimizely-forms-api#put-or-get-endpoint-description">Headless Form Api Specification</a> 6. Create simple hello world form with single text input In right menu panel, create New Form, enter your form name. <img src="/link/cbf50a9b626e4763a4480f796ab8f662.aspx" width="902" height="414" /> Add textbox and submit button to form then publish form. <img src="/link/4df0c7189b5249beaaaddc8f1908579c.aspx" width="903" height="451" /> 7. Retrieve form using Postman Import postman collection <a href="/link/b2290e76cab44813b1c7839910d6b72c.aspx">Headless Sample.postman_collection.json</a> 8. Prepare backend site for form render 8.1. Update Manage Website setting for both case <ul> <li>Browse the site > Manage Websites: Update Delivery site = localhost:3000</li> <li>Browse the site > Manage Websites : Remove Host name = * the list</li> <li>(Optional) Update ManagementSite to use http instead of https on json (if you deploy your site on the local ): "applicationUrl": "<a href="http://localhost:8000">http://localhost:8000</a>",</li> </ul> <ul> <li>Browse React site:http://localhost:3000/en/[pageURL]</li> </ul> 8.2. Render form using ContentGraph <ul> <li>Set up management site</li> </ul> Install Optimizely.ContentGraph.Cms and Optimizely.Cms.Forms.ContentGraph using the NuGet Package Manager in Visual Studio or with the command line: <div class="CodeTabs CodeTabs_initial theme-light"> <div class="CodeTabs-inner"> <pre class="language-csharp"><code>dotnet add package Optimizely.ContentGraph.Cms dotnet add package Optimizely.Cms.Forms.ContentGraph</code></pre> </div> </div> <ul> <li>Add CG key to appsettings.json (at the same level as Episerver).</li> </ul> <div class="CodeTabs CodeTabs_initial theme-light"> <div class="CodeTabs-inner"> <pre class="language-csharp"><code>"Optimizely": { "ContentGraph": { "GatewayAddress": "<<Gateway Address>>", "AppKey": "<<App Key>>", "Secret": "<<Secret>>", "SingleKey": "<<Single Key>>", "AllowSendingLog": true, "ContentVersionSyncMode": "DraftAndPublishedOnly", "Include": { "ContentIds": [], "ContentTypes": [] }, "SyncReferencingContents": true } }</code></pre> </div> </div> <ul> <li>Add settings to Startup.cs</li> </ul> <pre class="language-csharp"><code>//Register ContentGraph for HeadlessForm services.AddContentDeliveryApi(op => { op.DisableScopeValidation = true; op.RequiredRole = null; }); services.ConfigureContentApiOptions(o => { o.FlattenPropertyModel = true; o.IncludeNumericContentIdentifier = true; }); services.AddContentGraph(); services.AddOptimizelyFormsContentGraph();</code></pre> 8.3. Render form using Rest API Add ReactController.cs file in Controllers folder to get all form keys in page <pre class="language-csharp"><code>using EPiServer; using EPiServer.Cms.Shell; using EPiServer.Core; using EPiServer.Forms.Implementation.Elements; using EPiServer.ServiceLocation; using EPiServer.SpecializedProperties; using EPiServer.Web; using EPiServer.Web.Routing; using Microsoft.AspNetCore.Mvc; using System.Collections.Generic; namespace AlloyMvcTemplates.Controllers; [Route("api/[controller]")] [ApiController] public class ReactController : ControllerBase { public ReactController() { } [HttpGet("GetFormInPageByUrl")] public IActionResult GetFormInPageByUrl(string url) { var builder = new UrlBuilder(url); var content = UrlResolver.Current.Route(builder, ContextMode.Default); if (content is null) { return NoContent(); } var contentLoader = ServiceLocator.Current.GetInstance<IContentLoader>(); var pageModel = new PageModel(); if (content is not null) { pageModel.Title = content.Name; pageModel.PageUrl = content.PublicUrl(); foreach (var props in content.Property) { if (!props.IsNull && props is PropertyContentArea) { var contentArea = props as PropertyContentArea; foreach (var item in contentArea.PublicContentArea?.FilteredItems) { var contentItem = contentLoader.Get<IContent>(item.ContentLink); if (contentItem is FormContainerBlock) { pageModel.FormKeys.Add(contentItem.ContentGuid.ToString("N")); } } } } } return Ok(pageModel); } } public class PageModel { public string Title { get; set; } public string PageUrl { get; set; } public List<string> FormKeys { get; set; } = new List<string>(); }</code></pre> 9. Render form using simple react app 9.1. Create a React app template <ul> <li>Create an empty folder : \ClientApp for example</li> <li>Run cmd on the folder : <code>npx create-react-app headless-form --template typescript</code></li> </ul> Result: \headless-form folder is added 9.2. Install JS SDK <ul> <li>Navigate to \headless-form</li> <li>Create a file .npmrc with content:</li> </ul> <code>@episerver:registry=https://pkgs.dev.azure.com/EpiserverEngineering/netCore/_packaging/HeadlessForms/npm/registry</code> <ul> <li>Install react-router-dom. Run cmd: <code>npm install <a href="mailto:react-router-dom@5.3.4">react-router-dom@5.3.4</a> <a href="mailto:@types/react-router-dom@5.3.3">@types/react-router-dom@5.3.3</a></code></li> <li>Install @episerver/forms-react. Run cmd: <code>npm install <a href="mailto:@episerver/forms-react@x.x.x">@episerver/forms-react@1.0.0</a></code></li> <li>Install @episerver/forms-sdk. Run cmd: <code>npm install <a href="mailto:@episerver/forms-sdk@x.x.x">@episerver/forms-sdk@1.0.0</a></code></li> </ul> 9.3. Add file .env with content in both case <pre class="language-csharp"><code>REACT_APP_ENDPOINT_GET_FORM_BY_PAGE_URL=https://localhost:8000/api/React/GetFormInPageByUrl?url= REACT_APP_HEADLESS_FORM_BASE_URL=https://localhost:8000/ REACT_APP_AUTH_BASEURL=https://localhost:8000/api/episerver/connect/token</code></pre> Render form using Content Graph, add the lines below to the .env file <pre class="language-csharp"><code>REACT_APP_CG_PREVIEW_URL={GatewayAddress}/content/v2 REACT_APP_CONTENT_GRAPH_GATEWAY_URL={GatewayAddress}/content/v2?auth={SingleKey} REACT_APP_LOGIN_CLIENT_ID=frontend REACT_APP_HEADLESS_FORM_BASE_URL=https://localhost:8000/</code></pre> NOTE:  <ul> <li>Update the port = ManagementSite’s URL if needs</li> <li>GatewayAddress, SingleKey are from appsetting.json</li> </ul> 9.4. Add the file \src\useFetch.ts that contains a function to request form data <pre class="language-csharp"><code>import { useEffect, useState } from "react"; export const useFetch = (url: string) => { const [data, setData]= useState<any>(null); const [loading, setLoading] = useState<boolean>(false); const [error, setError] = useState<any>(null); useEffect(()=>{ const fetchData = async () => { setLoading(true); fetch(url) .then(async (response: Response)=>{ if(response.ok){ setData(await response.json()); } }) .catch((err: any)=>{ setError(err); }) .finally(()=>{ setLoading(false); }); }; if(!loading){ fetchData(); } // eslint-disable-next-line react-hooks/exhaustive-deps },[url]); return {data, loading, error}; }</code></pre> 9.5. Update \src\App.tsx <pre class="language-csharp"><code>import './App.css'; import { useFetch } from './useFetch'; import { Form, FormLogin } from '@episerver/forms-react'; import { FormCache, FormConstants, IdentityInfo, extractParams } from '@episerver/forms-sdk'; import { useState } from 'react'; import { useHistory, useLocation } from 'react-router-dom'; function App() { const location = useLocation(); const { language } = extractParams(window.location.pathname) const url = `${process.env.REACT_APP_ENDPOINT_GET_FORM_BY_PAGE_URL}${location.pathname}`; const { data: pageData, loading } = useFetch(url); const formCache = new FormCache(); const [identityInfo, setIdentityInfo] = useState<IdentityInfo>({ accessToken: formCache.get<string>(FormConstants.FormAccessToken) } as IdentityInfo); const history = useHistory() const handleAuthen = (identityInfo: IdentityInfo) => { setIdentityInfo(identityInfo); } return ( <div className="App"> Hello {loading && <div className='loading'>Loading...</div>} {!loading && pageData && ( <> <h1>{pageData.title}</h1> <div className='main'> <div className='left'> {pageData.formKeys.map((key: any) => ( <Form key={key} formKey={key} language={language ?? "en"} baseUrl={process.env.REACT_APP_HEADLESS_FORM_BASE_URL ?? "/"} identityInfo={identityInfo} history={history} currentPageUrl={pageData.pageUrl} // optiGraphUrl={process.env.REACT_APP_CONTENT_GRAPH_GATEWAY_URL}//uncomment this line if you want to render using content graph /> ))} </div> <div className={`right`}> <h2>Login</h2> <FormLogin clientId='TestClient' authBaseUrl={process.env.REACT_APP_AUTH_BASEURL ?? ""} onAuthenticated={handleAuthen} /> </div> </div> </> )} </div> ); } export default App;</code></pre>  2024-09-04T08:25:21.0000000Z

Blog post