Router w/Static HTML Integration Tutorial

How it works:

  • Generate static HTML pages in a subfolder of the site, based on static HTML templates.
  • Include a Router to enable:
    • Page URLs anywhere in the site
    • Redirects defined in CMS


Router w/Static HTML Limitations:

  • No Server-side code in pages (unless publish templates are used)


Overview:

The Router integration method:

  • Serves static content (images, files) out of a public content folder
  • Adds a route to the Zend / Laminas application, to serve CMS pages and redirects

 The route should be placed at the end of other application routes.


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 public folder in the Zend / Laminas project
    2. Set the URL Prefix to the path prefix for the CMS Content files
    3. Set the "Override Page URL Prefix" to the path prefix for the CMS Page URLs, if different from the CMS Content path

  4. Generate the Integration Code:
    1. In the Deployment Target, click on the "Integration Code" tab
    2. Select the Environment "PHP - Router" to get the Integration Code

  5. In your Zend / Laminas project, install the "jsharmony-cms-sdk-php" Composer library:
    composer require apharmony/jsharmony-cms-sdk-php
  6. Add a new Handler named "jsHarmonyCmsHandler.php" to the "src/App/src/Handler" folder, with the following code.  Replace the jsHarmony CMS Router initialization with the Router Initialization parameters from the Integration Code tab in step 4.


    * Be sure to update the "content_path" property to match the CMS files publish folder in your Zend / Laminas project

    <?php
    
    namespace App\Handler;
    
    use Laminas\Diactoros\Response\EmptyResponse;
    use Laminas\Diactoros\Response\HtmlResponse;
    use Laminas\Diactoros\Response\RedirectResponse;
    use Laminas\Diactoros\Response\TextResponse;
    use Psr\Http\Message\ResponseInterface;
    use Psr\Http\Message\ServerRequestInterface;
    use Psr\Http\Server\RequestHandlerInterface;
    use apHarmony\jsHarmonyCms\CmsRouter;
    
    class jsHarmonyCmsHandler implements RequestHandlerInterface
    {
        public function handle(ServerRequestInterface $request) : ResponseInterface
        {
          $url = $request->getAttribute('url');
    
          // Initialize the jsHarmony CMS Router
          $cmsRouter = new CmsRouter([
              "redirect_listing_path" => "jshcms_redirects.json",
              "cms_server_urls" => ["https://cms.example.com/"],
              "content_path" => $_SERVER['DOCUMENT_ROOT']."/path/to/published_files"
          ]);
    
          return $cmsRouter->serve($url, [
              'onPage' => function($router, $fileName){
                  return new HtmlResponse($router->getFile($fileName));
              },
              'on301' => function($router, $url){
                  return new RedirectResponse($url, 301);
              },
              'on302' => function($router, $url){
                  return new RedirectResponse($url, 302);
              },
              'onPassthru' => function($router, $url){
                  $passthru = $router->passthru($url);
                  return new TextResponse($passthru->content, $passthru->http_code, ['Content-Type' => $passthru->content_type]);
              },
              'on404' => function($route){
                  return new TextResponse('Page not found.', 404);
              },
        ]);
        }
    }
    
  7. Add the jsHarmonyCmsHandler to the end of your "config/routes.php" file:
    $app->get('/{url:.*}', App\Handler\jsHarmonyCmsHandler::class, 'jsharmonycms');
    
  8. Create a Page Template:
    1. Local Page Templates can be defined in the CMS, by using the Site's SFTP
    2. Remote Page Templates can be defined in a public subfolder of the Zend / Laminas project, and linked to the CMS in the Site Settings "Page Templates" tab.

  9. If using Remote Page Templates, add the CMS Editor Launcher to each remote page template.  Copy the integration code from the Integration Code tab in step 4
    <script type="text/javascript" class="removeOnPublish" src="/.jsHarmonyCms/jsHarmonyCmsEditor.js"></script>
    <script type="text/javascript" class="removeOnPublish">
    jsHarmonyCmsEditor({"access_keys":["****ACCESS_KEY*****"]});
    </script>
    * Be sure to keep the "removeOnPublish" class in the Launcher script tags, so that the Launcher will not be included in the published pages
    * The jsHarmonyCmsEditor.js file is automatically served by the jsHarmonyCmsRouter.  The path can be updated in the Router config['cms_clientjs_editor_launcher_path'] parameter

  10. Add CMS content and publish to the Deployment Target, generating HTML files in the subfolder of the Zend / Laminas project
Loading
Loading