kingcomposer-how-to-create-element

How to create an element for KingComposer page builder

Dear developers,

KingComposer has released on WordPress.org for 7 months. After many changes and improve the system, the stable version KC 2.5  become the most downloaded.

Today, we decide to create this guide to introduce how to create an element for page builder and how to makeup the content display in front-end. Of course, we will have a short video about that on next series.

 

What is an element on page builder

Element know as a part of a section on a WordPress page, it often is a basic content such as a button, an image, a text paragraph, a spacing,.etc.. In KingComposer, we created many basic elements like that. In case, you want to have the specific function, you can create an element for it.

With KingComposer, each element exactly is UI graphic for a shortcode.

Structure of an element

An element often includes two parts:

  • Map param
  • Template

Map param is a set of fields data which you want to user enter data as text, image upload or select actions. The fields are attributes of the shortcode you want to define.

Template display data content which user enter to front-end of a page. In here you can set how that data look like, the position of them. It exactly replaces for the function of the shortcode as standard WordPress add_shortcode function required.

 

How to create

Ok, this is the important part of the article. Firstly, we will create a map params for an element.

Example, I will create an element which displays a text which I can enter from admin panel then display that text to front-end. Include with text can be media image or links.

I called it is Getting Element, the shortcode looks like: [gettings text=”Some text here”]

1. Create map params

With map params we have two way to create:

  • Use Shortcode Mapper tool on KingComposer
  • Define map via add_map function of KingComposer into functions.php file of theme

 

1.1 Shortcode Mapper tool

This is great tools for all developer from basic to senior, you do not need much code. Just design your element with click and click the mouse. You can create that map from any website use KingComposer, then you can export into your theme. Let’s start!

Firstly, go to KingComposer > Shortcode Mapper menu. In here we have two selection:

  • New Shortcode
  • Import/Export
Shortcode Mapper Panel

#1 Shortcode Mapper Panel

 

We click on New Shortcode and new panel show up. We enter the shortcode and attribute you want to have with shortcode. Notice, we just can create one element at the same time.

If you want to add more attributes, you can add later. Now press Parse Shortcode then new panel switch on

kingcomposer-shortcode-mapper-add-new-panel

#2 Add new panel shortcode

 

We have some parts in here:

  1. The icon displays on list element popup. You can select a new icon by click on icon then select. See more image #3
  2. Some information for element:
    • Shortcode Tag: tag name of shortcode, we choose it is ‘gettings’ on example
    • Name: The name of element display on list elements popup. See more image #3
    • Category: The category element belong to, you can enter already category or enter new one
    • Description: Tooltip text when hover mouse on the element in the listing. See more image #3
  3. List attributes of an element, we have the ‘text’ attribute here, you can add new one by press Add Param. To edit param, just click on the name tag. See more image #4
  4. The preview how attributes look on setting panel of an element.
#3 Element listing

#3 Element listing

#4 Edit param

#4 Edit param

 

After put your attributes, just Save it and go to edit a page to see result as image #3

To include the maps into your theme, just export them to a file then use snippet bellow into your functions.php

After download exported file, use method kc_include_map($path); to add maps automatically.
$path is the absolute path of exported_file.kc

 

1.2 Add_map

Please follow document and example in here – Add Map

 

Yeah! we finish the map file. Now we create a page and add element for testing

It will look like image #5. I will enter some content there

#5 Getting Element settings

2. Template for element

In standard, the KingComposer will look for the folder /kingcomposer/ into the activated theme to find the template for shortcodes.

So you do not need to use function add_shortcode any more.

Now we create new file in /kingcomposer/ is gettings.php

The file name must be same as shortcode tag as you register above. In this case, I am using KCtheme, It looks like.

kingcomposer-shortcode-mapper-template-folder

#6 /kingcomposer/ folder

All data of elements was passed to the $atts variable. In gettings.php I will print the structure of element with the snippet bellow:

#7 Print variables

#7 Print variables

And result

#8 Attributes content

#8 Attributes content

 

Gotcha! We got content attribute there, now we make-up them better

kingcomposer-element-result

 

All done!

How do you feel with this instruction. If it is helpful for your works, please like and share with your friends.