Documentation

Table of contents

  1. Installation
  2. Content editing
  3. Front end editor
  4. Mapping shortcodes
  5. Settings
  6. Customize
  7. Configuration file
  8. Adding and overriding content elements in a theme

Installation

Rapid Composer (RC) is installed like any other WordPress plugin:

  • Extract rapid_composer folder from downloaded zip archive
  • With your FTP client application, upload rapid_composer folder to wp-content/plugins.
  • Go to Plugins screen and look for the newly uploaded Rapid Composer in the list.
  • Click Activate to activate it.

The other option is to select “Installable WordPress file only” when downloading from Envato and then use downloaded zip archive with Plugins > Add New > Upload Plugin option.

To install Rapid Starter theme (rapid-starter.zip file) you can follow similar procedure.

After plugin and theme installation and activation, you can import demo RC_demo.xml file. To import demo please follow this procedure: https://wordpress.org/support/article/importing-content/#wordpress.

Demo contains some basic content including Header, Footer and Off-canvas content. After demo is imported you may additionally go to Appearance > Customize > RC Fonts and select Open Sans as Body Font and Merriweather as Heading Font (these two fonts are included with the plugin in google_fonts folder as an example of self-hosted fonts but you can also select other fonts). Also in Menus you can select Primary checkbox to show imported menu.

Content editing

After Rapid Composer plugin is activated, go to Pages > Add New.

You may use Switch Editor button to switch to between Rapid Composer editor and WP default editor. Click Custom CSS button to add some custom CSS to current page/post.

Click big ‘+’ button to start adding content. By default, root element is Section (bt_rc_section). Because Section only is almost never used, RC will automatically add Row and Column elements to Section. Place mouse over top of element to show element toolbar. Click Add (‘+’ icon inside toolbar) to add element inside current one (try to add some elements to Column).

Row element has Edit Layout icon instead of Add Element. Click Edit Layout to select one of predefined layouts or insert your own layout – e.g. 1/2+1/2 means two columns half of full width each. Three equal columns with 1/3 of full width will be defined like this: 1/3+1/3+1/3, etc. You can edit layout for each of 5 breakpoints. This gives optimal level of control over responsive layout, e.g. for two equal columns (second predefined layout) you will see that for all breakpoints except XS layout is 1/2+1/2 which will show two columns in one row. For XS, layout is 1/1+1/1 which means that each of two columns will have full width (and consequently second column will be displayed under the first). Depending on your content you might want to change that so that SM layout is also 1/1+1/1, etc.

You can also clone and drag & drop columns (just like other elements) which may lead to improper number and/or width of columns. That is why after clone or drag & drop columns are automatically resized and if there is improper number of columns parent Row is marked with red border.

After ‘+’ inside Column toolbar is clicked you will see a list of elements which you can click and insert inside the Column.

You can use drag & drop to rearrange elements. Just grab element while holding mouse button and drag around. Green indicator will show you where element will be placed.

Hold Ctrl while dragging to create copy of element (element will stay at current location but copy will be created at new location, when you release mouse button).

Other element toolbar commands are Toggle, Edit, Duplicate, Delete and clipboard commands (Copy, Copy + and Paste). Click Toggle to toggle element. Click Edit to edit element params (shortcode attributes).

Duplicate will create a copy of current element and place it below current element. Delete will delete the element.

Clipboard commands are used to copy and paste elements or stacks of elements. You can copy and paste on the same page/post or across pages/posts. Click Copy to copy element to clipboard. Click ‘Copy +’ to add another element to clipboard (create stack). Click Paste to paste inside or after the element (depending on type of elements in clipboard). To create new stack, just click Copy again.

Mixing different element types on stack is limited, e.g. you can not mix root elements with other elements. Also, pasting is limited, e.g. you can not paste root element inside some other element, or element inside any element which does not accept it (check accept and accept_all params).

To paste on (empty) page/post use toolbar Paste command (used to paste root elements).

Click Clipboard Manager to export or import current clipboard content. This is useful if you want to save current clipboard content for later use, share it, or copy/paste across websites/domains.

When you click Export, input field will get some encoded content which you can copy using your standard OS clipboard (Ctrl + C). Then you can e.g. save it as text file and later just paste it to input field and click Import. It will be imported to RC clipboard.

Front end editor

To activate front end editor click RC FE Editor button inside WP admin toolbar. After front end editor is loaded you can switch back with RC BE Editor button.

To save edited content click red Save button.

Editing is similar to back end with some advantages and disadvantages. Back end editor is generally faster, and if you are familiar with the template and content elements it is the fastest way to create new content.

With front end editor you can see how edited elements look like but the price for that is slower operation because of AJAX requests which are required to generate accurate rendering of content elements. Also, there are other limitations: you can not drag and drop column from one row to another and it is not possible to edit all content elements directly (mainly because of complex inner structure and/or element design). That is why in some content elements you will see Edit in BE editor icon instead of Edit icon. This will switch back to BE editor with corresponding content element marked with blue color and scrolled into view. After you edit its content, just click RC FE Editor to continue editing on front end.

Mapping shortcodes

Unmapped shortcode tags are displayed in red color.

There are two levels of mapping – primary (using php function bt_rc_map) and secondary (manual mapping using built-in mapping interface).

Secondary mapping can override primary mapping. You will learn more about that later.

To create shortcode mappings with bt_rc_map php function in your theme or plugin use the bt_rc_map function like this:

function my_mapping_function() {
	if ( function_exists( 'bt_rc_map' ) ) {
		$params_some_shortcode = array(...);
		bt_rc_map( 'some_shortcode', $params_some_shortcode );
		$params_other_shortcode = array(...);
		bt_rc_map( 'other_shortcode', $params_other_shortcode );
		/* add more mappings... */
	}
}
add_action( 'plugins_loaded', 'my_mapping_function' );

Here is the list of all parameters:

Name Type Description
name string Name of shortcode.
description string Description of shortcode.
root boolean Set to true if it is root element.
container string Can be ‘horizontal’ or ‘vertical’, usually it is ‘vertical’.
toggle boolean Set to true if you want to toggle element in Rapid Composer.
show_settings_on_create boolean Set to false if you do not want to show settings when element is added.
width_param string Parameter from params array which defines width of element. Used for elements which are contained in horizontal containers.
accept array Array of elements which can be contained by the current element. Special one is ‘_content’ which represents standard WP editor content wrapped by shortcode tag. If element accepts ‘_content’ then it can not accept other elements. In RC interface it is a node marked by ]…[.
accept_all boolean Set to true if you want to contain all elements; accept param will override this.
as_child array Limit parent element scope, e.g. use ‘as_child’ => array( ‘only’ => ‘bt_rc_tabs’ ) to be able to add element only to bt_rc_tabs.
post_type array e.g. ‘post_type’ => array( ‘only’ => ‘rc-header’ ) or
‘post_type’ => array( ‘except’ => ‘rc-header’ )
params array Array of mappings for shortcode attributes; see next table.
base string Not required for bt_rc_map, but required in JSON used in secondary mapping.
auto_add string Add another element automatically (enter shortcode name).

Most important parameter within basic array is params which contains mappings for shortcode attributes. It is array of arrays, each holding mapping options for specific shortcode attribute. Here you can see all parameters used to map single shortcode attribute:

Name Type Description
param_name string Name of parameter (shortcode attribute).
type string Type of field: ‘textfield’, ‘textarea’, ‘textarea_object’, ‘dropdown’, ‘colorpicker’, ‘iconpicker, ‘attach_image’, ‘attach_images’, ‘checkbox’, ‘hidden’.
heading string Title of parameter (this will be displayed above param input field).
description string Description of parameter.
value string or array Default value or array of values, not required, except for dropdown and checkbox where you have to enter array of values.
default string Default value for array value.
preview boolean Set to true if you want to show current parameter value inside corresponding Rapid Composer element.
group string Name of tab which will show this param.
weight integer You can use this to order params.
responsive_override boolean Set to true if you want to be able to override this
param for different screen sizes (currently works
with dropdown and checkbox input types). See
content_elements/bt_rc_column/bt_rc_column.php
for implementation.

Example mappings for param types:

'params' => array(
	array(
		'type' => 'textfield',
		'param_name' => 'example_param1',
		'heading' => __( 'Simple text input', 'txtdomain' ),
	),
	array(
		'type' => 'textarea',
		'param_name' => 'example_param2',
		'heading' => __( 'Textarea field', 'txtdomain' ),
	),
	array( 
		'type' => 'dropdown',
		'param_name' => 'example_param3',
		'heading' => 'Row stretch',
		'value' => array(
			__( 'Default', 'txtdomain' ) => '',	
			__( 'Stretch row', 'txtdomain' ) => 'stretch_row'
		)
	),
	array(
		'type' => 'colorpicker',
		'param_name' => 'example_param4',
		'heading' => __( 'Pick a color', 'txtdomain' ),
	),
	array(	
		'type' => 'attach_image',
		'param_name' => 'example_param5',
		'heading' => __( 'Select one image', 'txtdomain' ),
	),
	array(
		'type' => 'attach_images',
		'param_name' => 'example_param6',
		'heading' => __( 'Select one or more images', 'txtdomain' ),
	),
	array(
		'type' => 'checkbox',
		'param_name' => 'example_param7',
		'heading' => __( 'VALUE IS REQUIRED!', 'txtdomain' ),
		'value' => array( __( 'Click me!', 'txtdomain' ) => 'yes' )
	)
)

To create secondary mapping click Shortcode Mapper icon ( […] ) on the toolbar which you will see at the lower part of screen. You will see a dialog with list of shortcodes. Unmapped shortcodes are displayed in red color.

If shortcode has primary mapping it will have /p suffix and if it has secondary mapping it will have /s suffix. If there is primary mapping and secondary you will see /p /s. It means that secondary mapping is overriding primary mapping.

To create secondary mapping, click shortcode you want and then click Insert Mapping button. You will see JSON mapping inserted in textarea. It corresponds to bt_rc_map function, except for ‘base’ parameter which you must enter here, but you do not have to enter in bt_rc_map params array.

If shortcode is already mapped with Visual Composer, mapper will generate suggested JSON template with most of VC mapped properties automatically picked and transformed in Rapid Composer format. Please note that in most cases it is not enough to just insert VC mapping. You need to manually check params and tune them according to your needs.

if there is primary mapping, it will be displayed as JSON allowing you to quickly modify it and save it as secondary mapping which will override primary mapping.

if there is no VC mapping and no primary RC mapping, only basic JSON template will be inserted allowing you to quickly continue with manual mapping.

When you are done with mapping click Save to save secondary mapping. Click Delete if you want to delete secondary mapping.

Settings

From main WP menu select Settings > Rapid Composer to open Rapid Composer Settings.

With first option, Show shortcode tag instead of mapped name, you can select Yes if you want to show shortcode tag name instead of mapped name.

Set Content elements toolbar style to Keyboard shortcuts to show keyboard shortcuts instead of icons (to use keyboard shortcut toolbar must be active, so just place mouse pointer over the top of element and press a key; keyboard shortcuts can be also used if Icons option is selected).

Post types option is used to select on which post type edit pages do you want to show Rapid Composer interface.
Select Skin to change back end interface appearance.

Collapse top level elements initially is used to collapse top level elements (Sections) when edit page is loaded. This can be used (if you have many Sections on your pages) to quickly locate some specific Section.

Customize

From main WP menu select Appearance > Customize. There you will see theme options but also Rapid Composer RC General Settings, RC Fonts and RC Template sections.

In RC General Settings you can reset RC settings.

In RC Fonts, you can select body font, heading font and up to 5 different additional Google Fonts fonts which can be used by some content elements (e.g. Heading). API key is not required but if entered it will be used to get most up to date list of fonts.

In RC Templates, you can select Header, Footer and Off-canvas posts.

Configuration file

One if unique RC features is configuration file which can be used to configure various options.

Just copy bt_rc_config.php file from RC root to your theme root and start editing.

Take a look at comments in config.php file to learn more about individual options.

Adding and overriding content elements in a theme

To add new content element, create bt_rc_content_elements folder in your theme or child theme, then copy one of existing content element folders from rapid_composer/content_elements to bt_rc_content_elements folder, e.g. bt_rc_button and modify content element name (it is required that folder name, file name and php class name are identical, e.g. bt_rc_my_button).

Similarly, to override existing content element, just copy its folder located in rapid_composer/content_elements to folder bt_rc_content_elements inside the theme parent folder or child theme folder.

You can change files inside bt_rc_content_elements as you want, while keeping original rapid_composer/content_elements unmodified.