Component Library: Component Definitions

MarcusEdwards

Part of the Introduction to Component Library series.

Component Definitions

Watch the Component Definitions Component Library video here.

Components are:

fragments of markup from your site design;
that can be combined to create more complex components;
are used, together with layouts, when creating template and nav wrapper definitions.

CL takes Component Definitions and generates C# sources each time the definition is saved. There are two sources: one that is regenerated on every save and which therefore shouldn’t be edited; and one that is only generated on the initial save. This second source is the one that you can safely edit to customise the component code.

Naming

Before creating a component, it is important to consider the naming of your component as there are some constraints and implications.

Component Library does not currently support renaming components. This is because of the difficulty tracking and refactoring all the places your component could be used once it has been created.

The folder name will be used as the section name in the drag and drop panel. The component name is how the component will be labeled in the section of the drag and drop panel.

Component Library will be generating a C# class to represent your component, and the class name is determine by a simple algorithm:

convert the component name to all lower case;
convert that to title case, meaning start with an initial capital letter, then capitalise letters that come after spaces and punctuation;
and finally, remove any spaces.

There are additional constraints on the name as we are bound by the requirements for C# class names. The component name should:

NOT start with a number
NOT contain any punctuation (dashes, underscores, commas etc.)
NOT be a C# reserved word or keyword
NOT be a know C# system class name.

Common problems names are:

class (as in CSS class attribute) – this is a C# reserved word
float (as in CSS property) – C# reserved word
readonly – C# reserve word
string – System class name
event – System class name
date – System class name

Quick test: what do you think of ‘Header & Link – with CTA” as a component name?

Hint: it is a good descriptive component name, but still not a good name as it contains symbols and punctuation.

In summary then, the guiding principle should be to keep the name as descriptive and user friendly as possible, use multiple words separated with spaces but not forget the constraints of C# class names.

Creating

Now that we have the naming out of the way, component definitions are created in the “Component Definitions” folder by using the File > New > Component model.

Component definitions provide a “Pattern” field that the markup for the component should be entered in. This markup is typically a combination of the literal output markup as well as placeholders for fields or content elements.

Fields and sub-components are indicated in the markup using braces or curly brackets. The placeholder must have a field name, “article_publish_date” for example.

Placeholders can also specify the component type by adding a colon and then the name of the generated C# class for the component. “cta: OptionalCtaButton” in this example example.

If you don’t specify the type in the placeholder, Component Library will default the type to “Text” and you will have the option to pick the component type from a drop down in the list of components that appears under the pattern field after saving the component definition.

Having said that, it is strongly recommended that you always use the field name plus type format as this will save you having to save and regenerate the component definitions quite so much.

Before going further, we should look at field naming as this is important too.

The field names will become content asset fields. However, they are also going to become C# class fields which means we are constrained by the requirements of C#.

Field names must:

start with a letter (not a number, symbol or punctuation character;
contain only letters, numbers and underscores;
cannot be a C# reserved word or keyword.

We recommend that you create field names in all lower case, using multiple words and separated by an underscore. If you follow this recommendation, Component Library will automatically create readable labels for the fields on the CMS content form view.

The algorithm is straight forward, Component Library will:

replace underscores with spaces;
convert to title case.

Here are some examples of good and bad field names.

When you save a component definition, two things happen:

Firstly, the Component Library parser will go through the pattern field looking for field placeholders and create a list of identified components below the pattern field.

This list is where you can customise and configure the component. This is important if you didn’t specify the field type in the placeholder directly as you now get to choose it from a dropdown of components.

Secondly, Component Library will generate two C# source files in the Project/Library folder. The “base” component source file is re-generated each time the component definition is updated and saved and therefore should not be edited .

The other source files is where custom code should be added so that it won’t be overwritten the next time the code generation runs. if you look at the source code, you will find three methods: