Documentation > Best Practices and Examples > Component Library

Component Library Support in the CMS Platform

The CrownPeak Component Library is a Framework and a CrownPeak CMS Extension. As a framework, the Component Library defines a process and provides visual tools to define re-usable CMS components that can be used to define templates, models, and assets without writing any CrownPeak API code. As a CMS Extension, the Component Library introduces a zero-implementation experience (Figure 1), allowing users to create and setup complete sites, leveraging a complete library of front-end patterns, developed by Pattern Labs (http://patternlab.io) (Figure 2), as well as Bootstrap, one of the most popular CSS frameworks. All of the artifacts provided by the extension are fully editable allowing for complete customization and flexibility.

Overview


The CrownPeak CMS provides a number of object types, including Templates, Models, and Assets. Templates, which are composed of individual files, provide the ability to configure an authoring experience within the CMS allowing authors/editors to enter, manipulate and manage content, while adhering to specific validation rules, and finally merging the captured content within an approved presentation (HTML/CSS/JS) to produce pages.

These pages are called assets in the CMS, and each has a corresponding Asset ID. The CMS also provides the ability to embed the rendered output of any asset within another, as well as the ability to expose the content of any asset to be queried by, and used, within another.  These re-usable content assets are called widgets. Widgets are normal assets, but the way they’re used as described above, is what makes them widgets. Re-using content in the CMS is achieved with widgets. However, re-using front-end patterns, and CMS API code requires an alternate approach.

The Component Library, as a framework and as an architectural approach, defines a new CMS asset type called Component, where each front-end Pattern is stored. Re-use of CMS API logic is typically available to template developers by encapsulating the repeatable code patterns in Library Methods (or Functions) defined a Class.

These custom library methods are available to all templates, and provide a way to centralize the definition of the code and to re-use the code as many times as required.   The Component Library takes advantage of these CMS capabilities, and defines a framework for defining and associating library classes and methods to work alongside the appropriate components.

Figure 1. Zero-implementation Site Folder

Figure 2. pattern lab (http://patternlab.io/)

What’s new with the version 2 of the Component Library


This update to the Component Library introduces the following capabilities

  • Integration with a rich Library of Patterns, provided by Patternlab.io (Figure 3)
  • Integration with the Bootstrap framework
  • Component library methods are now encapsulated in individual class files, dedicated to each component, each inheriting from a Base Component Class
  • The introduction of visual tools to define Components, Templates, Content Wrappers, and Widgets.  No CrownPeak API skills are required.
  • Auto code generation of Library Files and Template Input, Post-Input and Output files.

Figure 3. Pattern Lab Folder

Figure 4. Component Builder

Benefits of the Component Library


The Component Library provides the following benefits:

    • Leverage a complete set of page types that support themes via Bootstrap styles.
    • Define new Page Types, or edit the provided ones, using the familiar CrownPeak Form View editing experience.   No CrownPeak API skills required.
    • Create new Components, or customize the provided ones, by editing basic HTML tags.   No CrownPeak API skills required.
    • Update look and feel by selecting any of the provided bootstrap themes, or upload your own.
    • The behind the scenes code is fully editable (and consistent with current best practices), allowing for advanced CMS authoring and rendering capabilities, as well as any custom integrations.
    • The ability to use and re-use the components within any and all C# templates.
    • The ability to limit the review and approval of template changes to isolated components.  When a component is approved, the change can be deployed to all affected templates.
    • By separating the presentation of each pattern into separate Component Assets, this allows the look and feel of Templates to be branched, and previewed in separate publishing environments.

    Figure 4. Template Builder

    Figure 5. Theme Selector

    Figure 6. Layout Selector

    Configuring the Component Library


    The Component Library can be configured to support many business processes. Before starting the configuration, it is beneficial to solidify the scope of the configuration. Use this list to determine how the customer is going to use the Component Library in their instance.

    • Does the customer want to leverage an HTML/CSS library of patterns?
    • Does the customer want to re-use capabilities and site components?
    • Does the customer want to streamline the process of making changes to common or shared components?

    The Component Library is best suited when the HTML/CSS is structured and re-usable, where components represent Front-End Patterns that can be assembled into Templates and ultimately Pages.

    CrownPeak Partners and Agencies often provide their own Pattern Libraries.  In addition, there are also a number of open source and free Pattern Libraries available for download and use.

    The Component Library supports patterns that utilize other patterns, which means that Components can be nested within other Components.   The following is a typical hierarchical structure to organize your Components:

    • Atoms or Elements:  Smallest pattern type.  
    • Molecules or Modules:  A collection of elements
    • Organisms or Blocks:  A collection of modules and elements
    • Layouts – A container that provides a way to organize the blocks, modules and elements used on a page
      • Changing a component used by multiple templates will impact all templates. 
      • The CMS will support multiple Component Libraries.
      • Component Libraries can be defined at any level:  Instance, Site Collection, Site, Site Section, etc.
      • The Component Library approach only impacts how Templates are configured. There is no impact at all on the management of Assets, Workflow, Publishing configurations, and ACLs.

     

    Considerations

    • Changing a component used by multiple templates will impact all templates. 
    • The CMS will support multiple Component Libraries.
    • Component Libraries can be defined at any level:  Instance, Site Collection, Site, Site Section, etc.
    • The Component Library approach only impacts how Templates are configured. There is no impact at all on the management of Assets, Workflow, Publishing configurations, and ACLs.

    How to Configure a Component


    An initial Component Library based site will include the following supporting Folders

    • _Assets Folder:  This is where your images, CSS files, JS Files, Font files, and any other supporting assets can be stored
    • _Config Folder:  This is where your site configuration files such as _Config, Masterpage, Header/Footer assets are stored
    • _Components Folder:  This is where you will find the Pattern Lab collection of Components, and is where you may define your own components
    • _Templates Folder: This folder includes template definitions assets allowing any user to create and build CrownPeak Templates without writing or even knowing any CrownPeak API code.

    An initial Component Library based site will also include a number of pre-configured page types that are pre-loaded as Models within the Site Root folder, and any Content Folder

    Page Types

    • Homepage Template
    • Article Template
    • Blog Index Template
    • Landing Page Template
    • Content Template
    • More types will be added regularly

     

    Content Folders

    • Content Folder:  A generic folder to define and store any type of content
    • Campaign Folder:  You may define and create landing pages and microsites in this folder
    • Article Folder:  A folder allowing you to create and define article content
    • Blog Folder: Manage your blog content
    • Press Releases Folder:  A folder to manage your press releases

     

    What are Components?

    A Component is a new CrownPeak object type, introduced by the Component Library.   It holds and stores any front-end code (HTML, CSS, JS). The Component Library comes pre-configured with a large collection of patterns, provided by Pattern Lab.io.  However, creating and defining your own custom components is easy using the new Component Builder. 

    The Component Builder (Figure 4), includes the necessary logic to

    • Parse the front-end pattern (HTML, CSS, JS, or any code) and identify the developer-specified content field(s)
    • Provide a visual editing interface to manage the identified field(s) and configure advanced capabilities
    • Auto-generate the necessary behind-the-scenes code stored in the Component’s Library Class file
    • Define generic/preview-only content to help visual the component’s look and feel

     

     How to build a Component

    The initial version of the Component Library required that a developer enter or paste in the front-end pastern into the markup field of a newly created Component Asset, and to define/code the three required library methods:_input(), post_input() and output() methods for the component. 

    The input method would be defined to prompt the CMS user for the content, as specified in the markup. The post_input method would provide any form validation, or content manipulation logic. The output method would merge the captured content with the markup.

     The Component Library introduced simple Expressions and Directives to help developers define the editable content with in the markup.  For example, to specify an editable field, a developer simply had to enter {fieldname} wherever they wanted to specify editable content within the markup.

    The current version of the Component Library simplifies the Component creation process considerably by auto-generating all the required code on behalf of the CMS user, and in doing so, introducing a no-CrownPeak API code development experience.

    To build a new component

    • Go to the _Components Folder in your site
    • Use the built-in models to create a new Component or Layout
    • Enter or paste in the front-end pattern markup (html/css/js) into the Markup filedSpecify editable content by using the following expression:   {fieldname : fieldType}
    • Where fieldname represents the unique identifier the CMS should use to reference the content captured in the field.   A fieldname within {} is required.
    • And fieldType, an optional parameter, which represents the type of content captured.
    • Field Types can refer to core cms controls, and user defined Components.  Core Field Types include: Text:  Standard Text Control, Wysiwyg:   Wysiwyg Control
    •  Image: Image Capture Control,  Link: Internal and External Links,  Widget: Re-usable Content
    • Press Save and Refresh the input form. This is required to reflect the newly added Input Form

    Example: The following describes the markup and associated generated code for an Article Component (Figure 7)

    <

    Figure 7. Layout Selector

    Assume the markup of an Article Component is as follows

    Lorem ipsum dolor

    Nam te ceteros dignissim expetendis, adhuc theophrastus sit at. Porro viris ornatus ei ius, magna corpora voluptatum ad sea.

    Ex quo dico electram, vel eu iudico doming. Pri no inermis recteque assueverit, et facilisis democritum deseruisse est, mei te viris omnium. Sea eius homero et. Duo id vocent sanctus qualisque, at pri harum accusamus.

    Expressions representing all editable content are defined as follows, replacing all the “lorem ipsum” content, as follows

    {headline : Text}

    {intro : Text}

    {content : Wysiwyg}

    Upon saving, the Component Library will automatically generate a class file called Components_Article.cs with the following code:

    using System;
    using System.Collections.Generic;
    using System.Linq;
    using System.Text;
    using CrownPeak.CMSAPI;
    using CrownPeak.CMSAPI.Services;
    using CrownPeak.CMSAPI.CustomLibrary.Components;
    
    /* Some Namespaces are not allowed. */
    namespace CrownPeak.CMSAPI.CustomLibrary
    {
    public class Article : ComponentBase
    {
    public Text headline { get; set; }
    public Text author { get; set; }
    public Text intro { get; set; }
    public Wysiwyg content { get; set; }
    
    public Article()
    {
    headline = new Text();
    author = new Text();
    intro = new Text();
    content = new Wysiwyg();
    componentMarkup = @"
    

    {headline : Text}

    by {author : Text}
    {intro : Text}
    {content : Wysiwyg}
    "; } public override void input(string label, string name) { this.headline.input(label + " Headline", name + "_headline"); this.author.input(label + " Author", name + "_author"); this.intro.input(label + " Intro", name + "_intro"); this.content.input(label + " Content", name + "_content"); } public override void postInput(PostInputContext context, string name, string index = "") { if (String.IsNullOrWhiteSpace(context.InputForm[name + "_headline" + index])) { context.ValidationErrorFields.Add(name + "_headline" + index, "The Headline is required"); } if (String.IsNullOrWhiteSpace(context.InputForm[name + "_author" + index])) { context.ValidationErrorFields.Add(name + "_author" + index, "The author is required"); } } public override string output(Asset asset, string name, string index = "") { StringBuilder sbContent = new StringBuilder(); sbContent.Append(componentMarkup); sbContent.Replace(@"{headline : Text}", this.headline.output(asset, name + "_headline", index)); sbContent.Replace(@"{author : Text}", this.author.output(asset, name + "_author", index)); sbContent.Replace(@"{intro : Text}", this.intro.output(asset, name + "_intro", index)); sbContent.Replace(@"{content : Wysiwyg}", this.content.output(asset, name + "_content", index)); return sbContent.ToString(); } } }

    How to build a Template


    The initial version of the Component Library did not provide a Template Builder.   Developers could leverage the components they defined by manually adding the corresponding library methods (input, postinput, output) to the templates they were building.

    This current version of the Component Library introduces a new Visual Template Builder that allows any CMS user to build and define CrownPeak Templates, without writing any CrownPeak API Code.   Zero CrownPeak API skills are required to take advantage of Template Builder.

    To build a new Template

    • Go to the _Templates Folder in your site root.  This is not the same /system/templates folder.
    • Use the built-in models to create a new Template or Wrapper
    • Use the Components Tab to define the components and associated layout(s) for the templateYou can define one or more Page Sections with in your template.   A page section is best described as a Row of content.   Two page sections are represented with two Rows of content, and so forth.
    • You must select a layout for each Page Section.   You can select from the predefined Bootstrap layouts, or define your own.  (Figure 8)
    • Within each Page Section, you may select one or more Components using the available List Panel.   You may customize each Component’s Label and Name.   If you leave these fields blank, the CMS will auto generate the Label and Name for you. (Figure 9)
    • Use the Wrapper Tab to select a Wrapper for your template.  The wrapper will provide a header and footer to wrap your content.
    • Use the Settings Tab to manage and set some advanced parameters, such as the name of the Template the CMS will build on your behalf, as well as the location, and other options.
    • Click Save to have the CMS build a Template based on your specifications, and auto-generate the code on your behalf.  You can review the generated code in the Code Tab. 

    Figure 8. Layout Selector

    Figure 9. Component Selector

    Figure 10. Wrapper Selector

    Connect with CrownPeak