Overview

Skill Level: Any

Adding the new layouts for an existing content type or a page type is fast, simple, and easy. A script command added to the package.json file automatically generates the templates that are required for the types. The following tutorial shows you how to add new layout for an existing content type that is already mapped to a layout.

Prerequisites

To get started, you need:

The layout templates determine how the content is rendered. Content is created from content types, which contain elements such as the text, images, files, and video. These elements, reference content that is created and stored in Watson Content Hub. The content types are mapped to layout templates, which reference the elements in the content types by their key. The content is then added to site pages. The layout mapping determines which layouts belong to which content types. It also defines the default layout for the corresponding content type. A content type can be mapped to several layouts.

Website pages in Watson Content Hub are created from page types, which are created and mapped to layout templates similar to the content types. The layout files point to an angular component that determines how the page type renders when added to the site application. A layout can implement a configurable component that can be added to a page just like any content. The elements of the content type are used as the configuration properties. The layout’s HTML and JS implement the component functionality.

For more information about Watson Content Hub and all the available Watson Content Hub developer tutorials, click here.

Step-by-step

  1. Create additional layouts for an existing content type

    Content types can be mapped to more than one layout.

    1. To create another layout for a content type that is already mapped to a layout, run the command:
      npm run create-layout -- --type <content type name> --name <layout name> 

      Where <content type name> is the name content type for which you want to create an additional layout and <layout name> is the name for the new layout created.

      This command sets up the new layout file, adds it to the layout mapping file, and creates the new angular component where you can specify how the layout is rendered.

      Note: If the layout name you specify exists, the command skips these steps and you must pick a unique name for the new layout and run the command again.

    2. Modify the files src\app\layouts<generated-layout>*
    3. Avoid touching the files in src\app\components<generated-layout>*
    4. Surround the HTML structure with the ID of the content (for future item highlighting):
      <div [id]="renderingContext.id" class="…">…</div> 

      Where renderingContext is the object that contains the representation the content item that is implicitly created by the create-layout command.

    5. The result is then passed into a separate generic component, which is listed under the src/app/components/generic directory along with the filters that are specified by the content type.
    6. The component in src/app/components/generic iterates through the list of filtered results and displays the content item according to its <wch-contentref> layout.
  2. Debug the script for errors

    When the script finishes, a list of files that was generated along with the path to where they were saved is printed in the console. If you get unexpected results from running the script, add the following extra flag to debug the script:
    verbose: add this flag to enable additional logging information to the console. For example,

    npm run create-layout -- --type <content type name> --verbose
  3. Define properties for the layout

    The angular component layout files that are generated are saved under src/app/layouts/layout-name. Similarly, the layout file is generated under src/wchLayouts/layouts and the layout mapping file is generated under src/wchLayouts/layout-mappings.

    • Data from your content type is accessed through the rendering context.
    • Access the elements from the rendering context that are individually bound from the abstract component file in src/app/components/content-type directory. You can define the properties for your layout by referencing these elements.
    • If you have a content type with multiple layouts, common variables and functions can be defined in the src/app/components/content-type-name type component file. These properties are inherited by each layout.
    • After you define the properties, to use the new layouts and components your live site:
      • Build your project with the npm run build command.
      • Then, deploy the project with the npm run deploy command.

    Note: You must re-enter your Watson Content Hub password for you to successfully run the commands.

  4. Preview your code changes locally

    When you change the SPA code, you can preview the new changes locally before you publish them to your site. After you change your code, run the SPA locally.

    1. Open src/app/Constants.ts file.
    2. Add the following lines to the top of the Class and provide your Domain name and Content hub ID. You can obtain the Domain name and the Content hub ID from WCH UI > Hub information.
      static readonly DOMAIN_NAME = "change.this.to.your.domainname"; 
      static readonly CONTENT_HUB_ID = "change-this-to-the-id-for-tenant-that-you-want-to-test-content-on";
    3. From your project folder, run:
      npm start
    4. The site application runs on your local host at http://localhost:4200/. The changes that you make to the code is automatically updated in the local site.

     

  5. Publish the code changes to your site

    After you verify your changes locally, you must publish these changes to your site.

      • Run the following command to build your new site.
        npm run build
      • Run the following command to deploy your updated local site to the remote site.
        npm run deploy

    Note: You must reenter your Watson Content Hub password for you to successfully run the commands.

     

Expected outcome

The new additional layout will now be visible in the content hub UI. The Content composer can now choose this layout when they create content.

Next step – Adding layouts for a new content type or page type

Updating layouts for dynamic list content type

Layouts can be updated and customized for all page types and content types in the website. Updating the layouts for the Dynamic lists content types are a little more complex than the average component.

  • Like other layout files, the Dynamic list layouts extend the src/app/components/type component file. In this file, the queryString for the list is configured with the properties that are specified by the content type.
  • In the src/app/layouts/layout-name layout html file, the queryString is passed into the query component of the SDK. For example, wch-contentquery [query]=”queryString” #q
  • A list of content items that match the specifications of the queryString are generated.
  • The result along with the filters that are specified by the content type is then passed into a separate generic component in the src/app/components/generic directory.
  • The component iterates through the filtered results and displays the content item according to its wch-contentref layout.

For more information about Watson Content Hub and all the available Watson Content Hub developer tutorials, click here.

3 comments on"Adding layouts for an existing content type"

  1. Hi, I got errors when try to create the layout for a page: npm run create-layout — –type
    Please let me know if you need npm-debug.log.
    Thanks,
    hong

    • Hello,
      Has anyone responded to your question?

      Thank you

    • Michael Burati November 03, 2017

      I’m sorry this question was missed. Comments on the documentation here go to the technical writers, not directly to support or development. I can’t tell from the question what the errors were, so could I suggest that you post your question on the Watson Content Hub developer forum (link below) and tag the question with “WCH” and “Watson Content Hub” to be sure the appropriate WCH experts monitoring that forum see and respond to the question?

      Thanks, and I hope that information helps.
      ..Mike Burati
      IBM Watson Commerce and DX Tooling
      https://developer.ibm.com/answers/smart-spaces/301/watson-content-hub.html

Join The Discussion

Your email address will not be published. Required fields are marked *