React Router w/Page Object

Router w/Page Object Integration Tutorial

How it works:

• Generate a JSON object for each page
• Define routes in React to enable:
  • Loading the CMS content as a JSON object, and rendering it to a React component
  • Page URLs based out of the root of the site
  • Custom Redirects defined in CMS
  • Single-Page / SPA Integration

Overview:

The Router w/Page Object integration method:

• Serves static content (images, files, and JSON page data) out of a public content folder
• Uses React Router to resolve templates, bind links for single-page applications, and implement CMS redirects

Integration:

1. In the jsHarmony CMS, on the Sites tab, create a new Site
   
   
2. Download the jsHarmony Redirects Component and extract into your site's SFTP folder.  This contains a "jshcms_redirects" component that exports the Redirects as JSON into a file named "jshcms_redirects.json" in the root of the site.  A site_config.json file is also included that sets the "redirect_listing_path" parameter to the new file.
   
   
3. In the Site Settings, add a Deployment Target:
   1. Configure the Deployment Target to publish to a folder in the client-side JS application
   2. Set the URL Prefix to the publicly accessible URL path where the CMS Content files (HTML, JSON, Images) will be published, for example "/content/"
   3. Set the "Override Page URL Prefix" to the path prefix for the CMS Page URLs, if different from the CMS Content path.  For example, if URLs should be root-relative, set the Page URL Prefix to "/"
      
      
4. Generate the Integration Code:
   1. In the Deployment Target, click on the "Integration Code" tab
   2. Select the Environment "React" to get the Integration Code
      
      
5. In your React application, install the "jsharmony-cms-sdk-react" module:

   npm install jsharmony-cms-sdk-react

6. In your React application, ensure the that content folder from step 3 exists:

   mkdir public/content

7. In your React application,  add the code from the Integration Code tab in step 4
   * Please note - the JshCms component needs to be an ancestor of all CMS content and routing components 

   import { JshCms } from "jsharmony-cms-sdk-react";
   import React from "react";
   import { createRoot } from "react-dom/client";
   
   // Configure the CMS
   const jshCmsConfig = {
       pageFilePath: "/path/to/page_files",
       redirectListingPath: "path/to/jshcms_redirects.json",
       accessKeys: [/*"ACCESS KEYS"*/]
   };
   
   const root = createRoot(document.getElementById("root")!);
   
   root.render(
       <JshCms {...jshCmsConfig} >
           <App />
       </JshCms>
   );

8. In your React application, create a new component for the CMS template, ex "CmsTemplateDefault.tsx", using jsHarmony CMS Page Template attributes ("cms-title", "cms-content-editor"):

   import React from 'react';
   
   export const CmsTemplateDefault: VFC<{}> = props => {
     return <div>
       <h1 cms-title="true">Page Title</h1>
       <div cms-content-editor="body">Page Content</div>
     </div>
   };

9. In your React Router, add a catchall route, typically at the end of the other application routes, to serve CMS files:

   import React from 'react';
   import { BrowserRouter, Routes, Route } from "react-router-dom";
   import { JshCmsRoute } from 'jsharmony-cms-sdk-react';
   import {CmsTemplateDefault} from './CmsTemplateDefault.tsx';
   
   function App() {
     return (
       <BrowserRouter>
         <Routes>
           <Route path="*" element={<JshCmsRoute path="*" bindLinks={true} component={CmsTemplateDefault} />}/>
         </Routes>
       </BrowserRouter>
     );
   }
   
   
   export default App;
   

10. Add the template to the CMS Site Page Templates
    1. In the CMS Site Settings, select the "Page Templates" tab
    2. Add a Remote Page Template, entering a Name, Title, and the full URL to the page, ex. http://localhost:3000/
    3. Edit the Config for the new Page Template by clicking the pencil icon, and enter the following to export to JSON on publish:

       {
         "templates": { "publish": "format:json" }
       }

       * After this step, it should be possible to add and edit pages from the CMS.
       
       
11. To support multiple templates, make your modify your JshCmsRoute to select the template based on the Template Id (defined as the Template Name in the CMS Page Templates tab).
    
    For example, a new two-column template can be defined in a "CmsTemplateTwoColumn" component, and added to the routing as below:
    

    <Route path="*" element={<JshCmsRoute path="*" bindLinks={true} component={(templateId: string, path: string) => (templateId==='two-column' ? CmsTemplateTwoColumn : CmsTemplateDefault} />}/>

12. In order to publish multiple content areas, such as in a two-column template, modify the "Config" under the CMS Site Settings -> "Page Templates" tab, to define the content areas:

    {
      "templates":{ "publish":"format:json" },
      "content_elements": { "column1": {"title": "Column 1"}, "column2": {"title": "Column 2"} }
    }

13. Add CMS content and publish to the Deployment Target, generating JSON files in the subfolder of the client-side JS application