Skip to content

Short intro to plugin API

matjaztrontelj edited this page May 9, 2015 · 3 revisions

Short intro to plugin API


Pinegrow works with two types of nodes:

  • DOM node is a browser DOM element
  • pgParserNode is a source-code representation of the node

DOM nodes are mapped to pgParserNodes with data-pg-id attribute.

DOM nodes created by JS code at runtime don't have associated pgParserNodes because they don't exist in the HTML source. These dynamic elements can't be edited in Pinegrow.

pgQuery class is a helper that connects DOM and pgParserNode elements.

var pgel = new pgQuery($el); //where $el is a jQuery wrapped DOM element

Then when you do things like:

pgel.attr('href', url);

operations are done on both nodes.


Event hooks can be placed on:

  • Plugin
  • Component
  • Component property

Plugin events

f.on_page_loaded = function(crsaPage) {} //Called when page is loaded


// Revolution slider uses this event to stop sliders when page is loaded
f.on_page_loaded = function(crsaPage) {
    setTimeout(function() {
        $(function() {
            var $html = crsaPage.get$Html();
            $html.find('.rev_slider').each(function(i,c) {
                var $c = $(c);
                callSlider($c, "revpause()", "Revolution Slider paused.");
    }, 3000);

Component events

Most component and property events get jQuery DOM element passed, in one way or another. Use pgQuery to construct a DOM - pgParserNode pair and do operations on that.


$el is a jQuery DOM element. cp is a CrsaPage object.

def.on_changed = function($el, cp)

This event will be called also if any of element's descendants changes. Changes include DOM structure change and property changes.

def.on_inserted = function($el, cp)

Called after the element is inserted on the page.

slider.on_inserted = function($el, page) {
    var $body = $(page.getBody());
    var id = $el.attr('id');
    if(id) {
        var ini_str = '$("#' + id + '").revolution();';
        pinegrow.addScriptToPage(page, ini_str);
        pinegrow.showNotice('<p>Revolution slider initialization Javascript was appended to the end of the page</p>', 'Revolution Slider inserted', 'revolution-on-inserted');

def.on_moved = function($el, from_cp, to_cp)

Element was moved.

Property events

These events are defined on component properties.

field.on_changed = function(obj, prop, value, oldValue, fieldDef, $field, eventType)


def.sections = {
    wp_site_options : {
        name : 'Options',
        fields : {
            wp_site_option_is_master : {
                type : 'checkbox',
                name : 'This is the master page',
                attribute : 'wp-site-is-master-page',
                empty_attribute: true,
                value: 'true',
                action : 'element_attribute',
                on_changed : function(obj, prop, value, oldValue, fieldDef, $field, eventType) {
                    var pgel = new pgQuery(; // is jQuery element
                    //$field is the input field with wrapper
                    //... do stuff

Updating the tree structure

If you change the DOM structure, update the tree with:

var $el =;
var pgel = new pgQuery($el);
var cp = pinegrow.getCrsaPageOfPgParserNode(pgel.get(0).pgel);
if (cp) {
    $.fn.crsa('updateStructureAndWireAllElemets', cp.$iframe, $el, true);

Property types

Property types:


tooltip_title : {
    type: 'text',
    name: 'Title',
    action: 'element_attribute',
    attribute : 'title'


tooltipos : {
    type: 'select',
    name: 'Placement',
    action: 'element_attribute',
    attribute : 'data-placement',
    'show_empty' : true,
    'options' : [
        {'key' : 'top', 'name' : 'Top'},
        {'key' : 'right', 'name' : 'Right'},
        {'key' : 'bottom', 'name' : 'Bottom'}


tooltiphtml : {
    type: 'checkbox',
    name: 'Html',
    action: 'element_attribute',
    attribute: 'data-html',
    value: 'true',
    negvalue: 'false'

Image / Filepicker

tooltip_src : {
    type: 'image',
    name: 'Src',
    action: 'element_attribute',
    attribute : 'src'

Calling external services

Use jQuery ajax, it works cross-origin.

Learn more, take a look at examples