Building Custom Blocks and Templates for MTBuilder on RISE CRM
MTBuilder for PolyCMS on RISE CRM runs on a Virtual DOM state engine that separates visual drag-and-drop editing from lightweight production HTML output. Developers can extend the MTBuilder canvas from any PolyCMS sub-plugin using MTBuilder.registerBlock(), customize editor panels via JavaScript filters, embed native RISE CRM lead capture forms, and compile optimized production bundles through Webpack.
Core Architecture and Storage Lifecycle
When an editor saves a page in MTBuilder, two synchronized representations are persisted to your RISE CRM MySQL database (using your dynamic {db_prefix}, default rise_):
- Virtual DOM JSON Schema (
mtbuilder_data): Stored in{db_prefix}blog_page_meta(rise_blog_page_meta). This JSON tree preserves nested sections, rows, columns, block settings, and CSS mappings so subsequent editing sessions reconstruct the exact workspace state. - Compiled Production HTML (
content): Generated bygenerateCleanHtml(), which strips editor overlays, drag handles, and admin controls before writing clean HTML directly into{db_prefix}blog_pages(rise_blog_pages). Public visitors receive static-speed HTML without loading the visual editor runtime.
Reusable full-page layouts and Template Parts are stored in {db_prefix}blog_mtbuilder_templates (alongside preset layout definitions in rise_blog_templates / rise_blog_mtbuilder_templates).
JavaScript Block Registration API
Register custom draggable blocks inside any PolyCMS sub-plugin using MTBuilder.registerBlock(blockType, config). Each block declares its sidebar group, icon, sidebar settings schema, and dual-mode render() method (Editor mock preview vs. Frontend output).
Example: Creating a RISE CRM Lead Capture Form Block
Create plugins/polycms/plugins/my-custom-plugin/assets/js/crm-lead-block.js:
MTBuilder.registerBlock('rise_crm_lead_form', {
name: 'RISE CRM Lead Capture Form',
icon: 'fa fa-user-plus',
group: 'crm_integrations',
acceptChildren: false,
// Sidebar Inspector schema
settingsSchema: [
{
key: 'formId',
label: 'RISE Lead Form ID',
type: 'select',
options: {
'1': 'Standard Newsletter & Inquiry Form',
'2': 'Enterprise Demo Request Form'
},
default: '1'
},
{
key: 'bgColor',
label: 'Background Color',
type: 'color',
default: '#f8fafc'
},
{
key: 'buttonText',
label: 'Preview Button Label',
type: 'text',
default: 'Submit Request'
}
],
// Dual-mode render callback for Editor canvas and Public frontend
render: function (node, renderChild, isFrontend) {
const el = document.createElement('div');
const formId = encodeURIComponent(node.settings.formId || '1');
const bgColor = node.settings.bgColor || '#f8fafc';
const btnText = node.settings.buttonText || 'Submit Request';
el.className = 'mtb-rise-lead-wrap rounded shadow-sm p-4 w-100';
el.style.backgroundColor = bgColor;
if (isFrontend) {
// Public frontend: embed the live RISE CRM Lead Capture Form
el.innerHTML = `
<div class="rise-crm-lead-form">
Enqueuing Your Custom Block Script in the MTBuilder Editor
Inside RISE CRM, plugins/polycms/index.php hooks into RISE's app_hook_layout_main_view_extension on PolyCMS admin pages and fires the bridged app_admin_footer action. Attach your block script to app_admin_footer and gate it strictly to MTBuilder editor URIs so it never loads on unrelated CRM screens:
app_hooks()->add_action('app_admin_footer', function () {
$CI = &polycms_ci();
$uri = $CI->uri->uri_string();
if (strpos($uri, 'polycms/mtbuilder/editor') !== false) {
$src = polycms_asset_url('plugins/my-custom-plugin/assets/js/crm-lead-block.js');
echo '<script src="' . esc_attr($src) . '"></script>' . "\n";
}
});
Integration Workflow with Theme and Plugin Scaffolds
Follow this separation of concerns when delivering production sites on RISE CRM:
- Build or extend a PolyCMS Theme to control global typography, headers, footers, and full-width landing templates.
- Package custom MTBuilder blocks and CRM integrations inside a PolyCMS Sub-Plugin.
- Let marketing and content teams assemble landing pages visually using MTBuilder Template Parts and your registered blocks.
Quick links:
- Building a Custom Theme for PolyCMS
- Building a Custom Plugin for PolyCMS
- MTBuilder Visual Page Builder User Guide
Developer Hooks and Filters Reference
1. PHP Filter Hooks (Content Transformation)
polycms_post_content and polycms_page_content
Fired before compiled post or page HTML renders on the public frontend. MTBuilder attaches filter_the_content at priority 10 to expand dynamic shortcodes such as [mtbuilder_blog_posts], [mtbuilder_blog_search], and [mtbuilder_blog_directory].
polycms_add_filter('polycms_page_content', function ($content, $page) {
if (function_exists('is_mtbuilder_used') && is_mtbuilder_used($page->id)) {
$content .= '<div class="custom-campaign-banner text-center my-5 p-4 bg-light rounded">'
. '<h3>Need a Tailored Demo?</h3>'
. '<p>Schedule a live walkthrough with our RISE CRM specialists.</p>'
. '<a href="/contact" class="btn btn-primary">Book a Demo</a>'
. '</div>';
}
return $content;
}, 15, 2);
polycms_the_content
Unified PolyCMS content filter where MTBuilder runs at priority 10 to safely expand nested visual shortcodes while preserving clean inline layout attributes.
2. PHP Action Hooks (Lifecycle and Asset Injection)
polycms_head
Fires inside the active theme's <head> section. MTBuilder uses this hook to enqueue mtbuilder-frontend.css so grids, cards, buttons, and responsive columns render accurately for public visitors.
polycms_plugin_activated and polycms_plugin_deactivated
Triggered when a sub-plugin is activated or deactivated in PolyCMS > Plugins. MTBuilder listens to polycms_plugin_activated to initialize template tables and seed the 6 bundled preset templates into {db_prefix}blog_mtbuilder_templates (rise_blog_templates / rise_blog_mtbuilder_templates).
polycms_add_action('polycms_plugin_activated', function ($plugin_file) {
if ($plugin_file === 'mtbuilder/mtbuilder.php') {
$seeder = polycms_module_dir_path('polycms', 'plugins/mtbuilder/includes/seeder.php');
if (is_file($seeder)) {
require_once $seeder;
MTBuilder_Preset_Seeder::run();
}
}
}, 10, 1);
app_admin_footer (Bridged via app_hook_layout_main_view_extension)
Fired at the bottom of PolyCMS admin screens via RISE CRM's app_hook_layout_main_view_extension hook in plugins/polycms/index.php. MTBuilder uses app_admin_footer both to inject the Edit with MTBuilder button on Post/Page forms and to load builder.js strictly on polycms/mtbuilder/editor views.
app_hooks()->add_action('app_admin_footer', function () {
$CI = &polycms_ci();
$uri = $CI->uri->uri_string();
if (strpos($uri, 'polycms/mtbuilder/editor') !== false) {
echo '<script src="' . esc_attr(polycms_asset_url('plugins/mtbuilder/assets/js/builder.js')) . '"></script>' . "\n";
}
});
3. JavaScript Filters (Workspace Customization)
JavaScript filters execute inside the MTBuilder editor workspace so plugins can register new sidebar groups or augment existing block schemas dynamically.
sidebar_groups
MTBuilder.addFilter('sidebar_groups', function (groups) {
groups.push({
id: 'crm_integrations',
name: 'CRM Integrations',
icon: 'fa fa-handshake'
});
return groups;
});
sidebar_blocks
MTBuilder.addFilter('sidebar_blocks', function (registry) {
if (registry.icon) {
registry.icon.settingsSchema.push({
key: 'customClass',
label: 'Custom CSS Class',
type: 'text',
default: ''
});
}
return registry;
});
Styling Isolation and Link Protection
To prevent global theme link styles (especially a:visited) from reducing button contrast, MTBuilder enforces a strict Style Isolation layer inside mtbuilder-frontend.css:
a.mtb-button-primary,
a.mtb-button-primary:visited,
a.mtb-button-primary:hover {
color: var(--btn-color) !important;
background-color: var(--btn-bg) !important;
text-decoration: none !important;
}
When compiling custom buttons, the rendering engine also writes critical spacing, border radius, and color declarations inline so blocks stay visually faithful across every PolyCMS theme.
Webpack Asset Compilation Pipeline
MTBuilder uses Webpack with Terser (JavaScript) and Clean-CSS (stylesheets) to compile production bundles inside dist/assets/. Whenever you edit files inside plugins/polycms/plugins/mtbuilder/assets/, rebuild via:
cd plugins/polycms/plugins/mtbuilder
npm install
npm run build
Always resolve runtime asset URLs with polycms_asset_url(), which automatically maps unminified development paths to their compiled .min.js and .min.css bundles:
echo '<script src="' . esc_attr(polycms_asset_url('plugins/mtbuilder/assets/js/builder.js')) . '"></script>';
// Resolves to: /plugins/polycms/plugins/mtbuilder/dist/assets/js/builder.min.js
Related Documentation
- Building a Custom Plugin for PolyCMS - Plugin scaffold, docblock headers, and
menu.jsonsidebar setup. - Building a Custom Theme for PolyCMS - Full-width landing template patterns for MTBuilder pages.
- Hooks and Filters Complete Reference - Full PolyCMS and RISE CRM hook catalog.
- MTBuilder Visual Page Builder - End-user guide for designing pages and Template Parts.