How to Create Custom Components Using Component IO

My Introduction to Component IO article described how you could use pre-built components on any site regardless of the Content Management System, languages, or technologies used. The benefits include:

• hundreds of ready-made, attractive and configurable components to choose from including content blocks, galleries, navigation bars, social media widgets, forms and more
• component code can be installed with a simple cut and paste
• the same components can be used across other pages and sites will updated instantly
• it’s easy for non-technical editors to make changes in a WYSIWYG editor and check it with a live preview
• all users can share Component IO dashboard links and collaborate on the same items
• Component IO is fast and delivers items quickly with a single API call, regardless of the number embedded in the page
• you can switch CMS or build processes at any point and retain components
• a full help guide and real-time chat assistance is available
• a free trial account can be used to test the service with your system.

Component IO Custom Components

Despite the huge range available, Component IO permits developers to create and edit their own components. In this tutorial, I will illustrate how to create a simple custom bar chart component which can be displayed and configured on any site:

Component Development Concepts

Component IO uses the Vue.js component model. Those with experience with the framework will immediately recognize the concepts and syntax. That said, I’m no Vue.js expert — but a little HTML, CSS and JavaScript knowledge is enough to build a complex component.

All components are encapsulated; their styles and code cannot ‘leak’ to other parts of the page. For example, the bar chart component’s title is an H2 element and we can apply any styles, e.g.

h2 {
  font-family: comic-sans;
  font-size: 8em;
  color: #f00;
}

Vue.js will ensure those (awful!) styles are only applied to our component and not H2 headings elsewhere on the page. However, a style applied to all H2 titles on the page can cascade to our component title. This can be useful since our component can inherit default fonts, colors and dimensions.

Step 1: Create a Blank Component

Log in to component.io, and then click Blank component on the Project page:

From the Edit menu, choose Edit component name and enter “barchart” or another suitable name.

Step 2: Define Fields

Fields are used to configure a component. They allow:

1. Content editors to modify values.
2. Other components to be created with a different configuration. For example, if we require two bar charts, we can duplicate the first and change the field values accordingly.

From the Edit menu, choose Add / remove fields and enter the fields you require:

For this control, I defined:

1. A single title text field.
2. The barvalue numeric field which defines the bar’s value.
3. The barlabel text field which defines the bar’s label.
4. The barcolor color field which defines the bar’s color.

These last three items had the repeat checkbox checked. We can therefore define any number of data items in our bar chart.

Step 3: Set the Initial Data

Hit the Edit menu to open the Content and Code control. Remaining in the Content section, I entered values for the title and three data items:

Step 4: Define the Component Code

Hit the Code toggle to open the code editor. This is where the component’s HTML, CSS and JavaScript is defined:

The component HTML documentation describes how templates are created. There is no need for an outer DIV or other element because the component will be automatically given one.

The title field is added first:

<h2 v-text="title"></h2>

Alternatively, we could use:

<h2>{{ title }}</h2>

The chart bars will be contained in a <ul> list element where each <li> displays a single value. The HTML code:

<ul>
    <li v-for="item in items" :style="item.style">
        <span>{{ item.barlabel }} 
            <strong>{{ item.barpc }}</strong>
        </span>
    </li>
</ul>

v-for renders the <li> element multiple times depending on the repeating source data (it is assigned to the items array). Note that I have not defined fields for item.style and item.barpc at this stage since they will be calculated in JavaScript code.

The component CSS can now be defined. This will only be applied to the component itself and not any other page elements. Sass SCSS syntax can be adopted for variables, nesting and other functions but I’ve kept it simple here:

h2 {
    font-weight: normal;
}

ul {
    padding: 2px 0;
    margin: 1em 0;
    list-style-type: none;
    border-left: 1px solid #666;
}

li {
    line-height: 1.2;
    padding: 1px 4px;
    margin: 0 0 1px 0;
}

span {
    display: block;
    color: #888;
    mix-blend-mode: difference;
}

strong {
    float: right;
    font-size: 0.8em;
    font-weight: normal;
    line-height: 1.5;
}

Note that I have not set font styles or sizes so the component can inherit these from the page where it is used.

Each Component IO component is a Vue.js instance and can use the standard JavaScript properties and methods. For example:

• component.data holds field values such as component.data.title and component.data.items[0].barlabel. If we change a value, it will be instantly updated in the component.
• the component.mounted method is called as soon as the component has been rendered.

The barchart component requires initialization code to calculate:

1. the sum of all bar values (totValue), and
2. the highest value (maxValue). This will have a bar which uses 100% of the available space.

// initialisation
let 
    items = component.data.items,
    totValue = 0, maxValue = 0;

for (let i = 0; i < items.length; i++) {
    totValue += items[i].barvalue;
    maxValue = Math.max(maxValue, items[i].barvalue);
    items[i].style = '';
}

The component.mounted method can now calculate each bar’s percentage and create the bar lengths using a CSS background linear-gradient:

// component created
component.mounted = function() {

    for (let i = 0; maxValue && i < items.length; i++) {

        let 
            color = items[i].barcolor || '#888',
            pc = Math.round(items[i].barvalue / maxValue * 100);

        // calculate bar percentage
        items[i].barpc = (Math.round(items[i].barvalue / totValue * 100)) + '%';

        // set bar style
        items[i].style = 'background-image:linear-gradient(90deg,' + color + ' ' + 
            pc + '%,transparent ' + pc + '%,transparent ' + (100 - pc) + '%);';
    }

};

Hit Save (or press Ctrl + S) and close the editor using the X at the top-left.

Step 5: Preview Your Component

All going well, the component is now rendered as expected:

You can change field data to see how it affects the component.

If anything fails, open your browser developer tools (F12 or Ctrl|Cmd + Shift + I) and examine any error messages in the console. The Component IO Guide provides further information about APIs and using code within other frameworks.

Step 6: Install the Component on Your Site

The component can be installed on any website where you are able to insert HTML code (a system such as CodePen.io is ideal). Hit the Install button to view the instructions.

The first component on the page will require both the component HTML, e.g.

<component key=XXXXX></component>

… and the Component IO script (just before the closing </body> tag is ideal):

<script project="YYYYY" src="https://cdn.component.io/v1"></script>

Subsequent components on that page just need their <component> tag.

See the Pen Component.io custom components by Craig Buckler (@craigbuckler) on CodePen.

Users will see an edit icon on the right-hand side of the page if they are logged in to their Component IO account. When they click the icon, they can choose one of the components and edit the field data or code.

Cue Componentized Workflow!

Custom components provides a flexible, modular development workflow for any website regardless of the CMS, server-side language, or technologies. Components can be shared, modified, duplicated and put live without a complicated build process or a rigid CMS plug-in system. You can be productive immediately without having to learn yet another web-based eco-system!

Component IO provides a simple tool which could revolutionize how you approach new features and updates for clients. It’s easy to start with pre-built widgets then create your own component collection. Sign-up is free – you have nothing to lose!

Frequently Asked Questions about Creating Custom Components Using Component.io