Documentation > Best Practices and Examples > Component Library

Getting Started with Component Library

This article will help you get started with the Component library. The information here is based on common practices from our Professional Services team and is best for developers and architects seeking to understand template creation with the Component Library available in CMS projects.

Once you finish reading this, you should understand what it is, where to find it and what is included in the Component Library. You'll also learn about the role of definition folders and files and how to use the definitions to create templates for based on your design and front end code.

Introduction


The Component Library is a pattern-based methodology we have built into the product to help you create templates using little or no code.

If you are familiar with Crownpeak templates, you are probably familiar with widgets -  an implementation pattern that makes content creation modular.

So let's start with this core concept - Components are not the same a widgets.

Since you will likely use both, here's an overview of the differences.

  • Components are added to templates
    • Components store data directly on the asset
    • You have to enter the data each time you use the component
  • Widgets store data on another asset
    • Users will link to them
    • The data is stored only once

  

Where is Component Library


The Component Library folder is contained inside of  the Component Project folder inside the site root.

For reference, the site root is a folder with the globe icon.

It is designed to be the home for a single site or domain so it can be easily configured for publishing, auto-beacons and search set up. It's also designed to be used with projects.

Only your developers need to have access to the Component Library folder.

Content authors, for example, do not need to interact with the library directly. They work with the assets that use the standard templates that the library generates.

Components are designed to work within the projects and site root structure. They support project branching  to manage component updates.

We are currently in version 2.1 of component library. The improvements include

  • Using code held in our Services Library
  • Faster to set up and configure
  • Support for Drag and Drop page design (Scheduled for general availability in Q3)

One last note - There is usually one installation per site root,but this will depend on your site and content strategy. Contact services for assistance with multiple installations.

What is included?


The Component Library installs with a set of definitions used to generate the standard CMS templates that power your site pages. There are 4 definitions included.

  • Component
  • Layout
  • Wrapper
  • Template

Using these definitions is the best way to deploy and manage your components.

This chart illustrates how these definitions work to create standard templates.for your site.

To the left, are the relationships between the definitions files and folders.

Combined, these generate the library files, wrapper templates and site templates that are applied to your assets using Models and configured with the Site config.

 

Let's walk through the definitions.

The Component Definitions folder contains your site’s components.

  • Components are discrete items that are combined to make up your page.
  • They are reused on as many pages and templates as you need.
  • Components can contain other components. This is a common and a recommended way to use them.
  • They are created based on your site’s design and built into C# class files when  saved.
  • When complex tasks or customizations are needed, the generated components can be overridden with template code.

The Layout Definitions folder contains your site’s layouts.

  • Layouts provide additional HTML markup to position and format your components
  • These are the glue that sticks your components together and are reused a lot.
    • These are not built into classes, but processed when a template is used
  • Make as many layouts as your site needs

The No Rail layout is included in the Component library. It shows your component markup unaltered.

It's a good choice for full-width items and is the most common choice when building a site page.

A layout wraps the component markup with extra items, so this is how you would display your components using a front-end framework such as Bootstrap. As an example, you would use the layout to wrap your components with HTML to apply a grid layout. In Bootstrap, you might use grid  classes like col-md-6 to achieve this.

 

The Template Definitions folder contain your component templates which

  • Use Components and Layouts to create CMS templates
  • Take care of generating the input, validation and output experience for you
  • Use Wrappers to render the final output to the page
  • Are generated  into standard CMS templates when they are saved

Template definitions DO NOT make filename, url, search_g2_*, etc. templates for you. If you need these template files, you need to add these after you generate each template.

Finally, wrappers are available in the Nav Wrapper Definitions folder. These definitions

  • Are like CMS Nav Wrappers, a convention for standard templates
  • Include your site's common navigational and boilerplate elements
  • Are also built into standard CMS templates when they are saved

Note, CMS Nav wrappers and Component Nav Wrapper Definitions 

  • Are often the same across all pages
  • Help to ensure the consistency of your site

Components in detail


Here are the basic steps to create a component in the Component Definitions
folder

  1. From the top menu, select File > New > Component and enter a name
    1. It’s not easy to rename components, so choose carefully
  2. Paste in your markup
  1. Replace user-editable content with field definitions
    1. For example, {name} represents a field called “name”
    2. Separate multiple words with underscores – e.g. {header_name}
    3. Labels will be created automatically – e.g. Project Name
              <div class="col-lg">
                <h2>{header_name}</h2>
                <p>{section_content}</p>
                <p></p>
          </div>
  1. Try to keep all your components at the same level
    1. For example all inside  <div class=“column”>
  2. Once you’re done, click Save
  3. Refresh the view
  4. Below the Markup field, expand the Component Details panel
    1. Here you can confirm and configure your components
  1. Choose a Component Type for each component
    1. You can specify the type automatically with {body : Wysiwyg}
    2. The default will be Text if you don’t specify one
  2. Make the component required if a value must be provided
  3. Change the label displayed for the component data entry field
  4. Add a message above the component. This is useful for grouping fields

The first time you save, the Component Library creates two C# class files in Component Project/Components.

You can see the names of these classes on the Advanced tab.

For example, if your component was called “Test”, you'll find these library files are generated

  • Components_TestBase.cs
  • Components_Test.cs

 

Important Note: Never edit the “Base” class – this is regenerated on each save

The other class is available for you to edit to customize your component’s behavior. 

Put logic in here to supplement or replace:

  • ComponentInput() – for the input experience
  • ComponentPostInput() – custom validation run when the user clicks Save
  • ComponentOutput() – control exactly what your control outputs

Wrap or replace the base method call depending on your requirements

Layouts in detail


Found in the Component Library/Layout Definitions folder, these are useful for configuration components.

  1. Select File > New > Layout and enter a name
  2. Enter markup – use {coln} for your columns

<div class="row">
    <div class="col col-md-8">{col1}</div>
    <div class="col col-md-4">{col2}</div>
</div>

  1. Up to four columns are allowed in each layout
  1. Select which column to use when placing a component on a template
  2. As with components, try to keep your layouts at the same level
    1. For example, all inside <div class=“container”>
    2. If you don’t want output, don’t enter any markup

Wrappers in detail


Create a Wrapper in Component Library/Nav Wrapper Definitions

  1. Select File > New > Wrapper and enter a name
  2. In the Components tab, add your sections
    1. Choose Header or Footer to select where the sectin will be placed on the page. 
    2. Each section has a layout – use “no rail” if you don’t need markup
    3. Each section corresponds to a tab on the Site Configuration template
    4. Sections can contain one or more components
      1. Input-only components are useful here 
  3. Open the Wrapper tab to enter markup to surround your components
    1. Header, Before content, After content and Footer
  4. In the Header and Footer, use special markup {css} and {javascript} to include code and styles
    1. If you need finer control {css:1} etc. allows access to each item
  5. Use the Settings tab to choose a name and select the destination folder
    1. Always pick Component Project/Templates
  6. Choose an asset to use for configuration
    1. This will use the template and act as your _Site Config asset

 

Note

You don’t have to use the Nav Wrapper Definition - you can still create a nav-wrapper manually. This is useful if you have more advanced requirements.

For example, create a wrapper manually when you want to create an ASP.NET master page, or a Java Tag page.

We strongly recommend this approach, otherwise you have to republish every page when your navigation or site config changes.

Tips for manual wrapper templates:

  • Output placeholders or tag markup as required
  • Call back to a template created with Nav Wrapper Definition for preview
  • Don’t forget to update your template if the original changes

Templates in detail


Create a Template in Component Library/Template Definitions 

  1. Select File > New > Template and enter a name
  2. In the Components tab, enter your sections
    1. Each section has a layout. Use “no rail” if you don’t need markup
    2. Each section corresponds to a tab on the Input template
      1. In Customize you can also choose to continue on the previous tab. Useful for controlling the input experience
    3. Sections can contain one or more components
    4. Choose which column to use for your component based on the layout
    5. Enter a message to show above the component if the page is complex
  3. On the Wrapper tab, choose the wrapper to be used for this template
    1. If you manually create a nav wrap, choose Custom Built Wrapper
  4. On the Settings tab, make sure Create is checked
  5. Provide a name for your new template
  6. Select Component Project/Templates as the folder to use
  7. Check Enable Page Metadata to get meta tags for SEO
  8. Click Save to create your template

This creates a new template with input.aspx, post_input.aspx and output.aspx template files

Note: Look, but don’t touch – changes will get overwritten without warning

Make these adjustments to complete your template

  1. Add filename.aspx and url.aspx to your template
    1. Copy from another template in your site
    2. These ensure your asset has a consistent file name when published
  2. Other template files may also be copied as required
  3. Create a model using your new template and apply it to a folder
    1. Models go in Component Project/Models

Connect with Crownpeak