Skip to content

Short intro to plugin API

matjaztrontelj edited this page May 9, 2015 · 3 revisions

Short intro to plugin API

Introduction

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);
pgel.remove();
pgel.html('<h1>....</h1>');

operations are done on both nodes.

Events

Event hooks can be placed on:

  • Plugin
  • Component
  • Component property

Plugin events

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

Example:

// 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.

Events:

$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)

Example:

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(obj.data); //obj.data 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 = obj.data;
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:

Text

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

Select

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'}
    ]
}

Checkbox

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

Clone this wiki locally
You can’t perform that action at this time.