Adding UIkit to Pinegrow: Pt 2

Namaste!

    In this portion of the tutorial, we will start writing the JavaScript that adds the framework for our UIkit components. While we will utilize many of the built-in properties of the framework constructor, there will be several that I will not use in the code. You can refer to the ‘pinegrow.js’ file in the application to look through the rest -> ‘Contents‘ -> ‘Resources‘ -> ‘app.nw‘ -> ‘lib‘ -> ‘crsa‘ -> ‘pinegrow.js‘ starting at line 2955 in version 5.5.

    Okay, let’s start by navigating to the top of our plugin folder and creating a file called ‘uikitPinegrowPlugin.js‘. Just as a reminder from our last tutorial, I’ve included an image of what our overall folder/file structure

should look like to the right. Now, there is no right way to structure this. I’m going to put this file together in a way that feels natural to me. While we could have this entire plugin exist as an anonymous function, I would rather name it and then invoke it at the correct time. So, I’m going to start by adding an anonymous function that checks if Pinegrow is finished setting up before it fires.

$(function(){
    //Wait to fire functions until Pinegrow is ready
    $('body').one('pinegrow-ready', function(e, pinegrow) {
        //boot our custom function
        createUikitPlugin(e,pinegrow);
    });
});

   Within the body of the function, we put a listener on the body of the Pinegrow editor. This listener invokes our custom function and passes the pinegrow variable once Pinegrow is finished with its set-up. While I wrote it first, I’m actually going to put our custom function prior to this function. That is just the way I roll!

Wonderful Pinegrow Properties!

    The Pinegrow framework is a constructor with the name ‘PgFramework‘. It receives two arguments – ‘key‘ and ‘name‘. Once instantiated with ‘new‘ it can accept a variety of properties. These properties are listed in the ‘pinegrow.js‘ file of the pinegrow app (partially pictured to the left). I’ll only go through a subset of these properties, many of them we won’t be using in our plugin. Let’s walk through the use of a couple by looking at the start to our custom function. Again, add this prior to the anonymous function we wrote earlier.

function createUikitPlugin(e, pinegrow) {
    //Define a prefix for our framework
    let type_prefix = 'pg.3.1.5.uikit';

    var framework = new PgFramework(type_prefix, 'UIkit');

    //Prevent the activation of multiple versions of the plugin
    framework.type = type_prefix;
    framework.allow_single_type = true;
    
    //Add a badge to notify user of new or updated status
    framework.info_badge = 'new';

    //Add a description of the plugin
    framework.description = '<a href="https://getuikit.com/">UIkit</a> javascript, styling, and components.';
    framework.author = 'Bo @ robertmeans.net';
    framework.author_link = 'https://robertmeans.net';

    //Alert Pinegrow that we will be adding custom actions
    framework.has_actions = true;
 
    //get url if script is included directly into edit.html
    framework.setScriptFileByScriptTagId('plugin-uikit-3-1-5');

   //Tell Pinegrow not to display the compiled back up versions of our CSS since we don't want to edit them
    framework.ignore_css_files = [/uikit/i];

  // Tell Pinegrow about the framework
    pinegrow.addFramework(framework);


  //Add our template into the project
    framework.addTemplateProjectFromResourceFolder('template', null, 100);
}

    First up, we define the function with a name, ‘createUikitPlugin’, that accepts two arguments, one of which, ‘pinegrow‘, passes in all of the constructor functions, and contains all the information for communicating with the Pinegrow app.

    As the comment states, first up we give a unique name to our plugin components using a prefix. In this case, I indicate that this component works with Pinegrow – ‘pg‘ – and then I add the UIkit version number – ‘3.1.5‘ – and finally the name of the framework we are adding – ‘uikit‘. I don’t believe that there are any strict requirements for this key other than it has to be unique.

    Next, we create a constructor object using ‘new‘ and pass in both the ‘type_prefix‘ key and a general name for our plugin, in this case ‘UIkit‘. If  you look at a lot of the Pinegrow examples you can see that they often use:

var f = new PgFramework(type_prefix, name)

    While we could use a single letter to define our framework and reduce the overall code size (not to mention the amount of time to type out framework each time!), I’m sacrificing the few bytes for extra legibility in our tutorial.

    The next two lines of code declare our framework type and let Pinegrow know that we only want a single version running at a time.

    The ‘info_badge‘ key is completely optional. It simply will add a small flag to the framework in the list that opens when we select a new file/project type. The string value can be most anything, but another common one is ‘updated‘.

    The next three keys are pretty self-explanatory. They give the end user of our plugin information about what it is and who we are. When the user loads our plugin and starts a new page/project this information will be displayed above our awesome minimalistic template. 

    The next key that we have a value for is ‘has_actions‘. If your plugin only has snippets of HTML that aren’t modified by adding classes or attributes, this can be set to ‘false‘. In our case, UIkit adds a number of modifiers, so we have set it to ‘true‘. 

    The next key:value pair may be a little cryptic, even if you read the comment. When Pinegrow is setting itself up there are core plugins that it loads. These include the Bootstrap and Foundation frameworks, plus styling for the code editor. It does this through an HTML document called ‘edit.html’. While unlikely, ‘setScriptFileByScriptTagId‘ tells Pinegrow that if it finds a script with an ‘id‘ set to that string to ignore our plugin. Basically, don’t double load this JavaScript file. 

    Working our way through the code, next up we have ‘ignore_css_files‘. This accepts a regex expression (link to Mozzila docs on Regex) enclosed in brackets as the value. In this case ‘[/uikit/i]‘. So, the forward slash starts the expression, which is the simple string ‘uikit‘, and the next forward slash ends the search string and is followed by an ‘i‘. That ‘i‘ indicates that our search should be case insensitive. In looking through the last lesson, I realized that I didn’t have you bring the minimized CSS file over into your template or plugin! This line of code isn’t really needed without that file being in your project, but it doesn’t hurt. Just make sure that none of your stylesheets contain ‘uikit‘ or Pinegrow won’t display them.  

    Now that we have defined the majority of our key:value pairs, we have to tell Pinegrow to onload our new object using ‘addFramework‘. Again, since I named it ‘framework‘ rather than ‘f‘, that is the argument we pass into Pinegrow.

    Okay! We have gotten the basics of our new plugin sketched out. Let’s see if it works. Open up Pinegrow and open the file menu. Select the ‘Manage libraries & plugins...‘ item. From the manager select ‘Load plugin‘ at the bottom. Next, click the folder icon and navigate to our newly created JavaScript file, select it and click the ‘Add‘ button. You will get a stern warning, but no fears, click ‘OK‘!! You should now see UIkit at the bottom of the list of resources. Close the manager and then click on the ‘New page or project’ icon. If all went well you should see the ‘UIkit’ resource at the bottom with a fancy yellow ‘NEW’ badge! Clicking on it should bring up our starter template for selection. You can see all of the info that we inserted into our JavaScript file like the author.

    So that is it for the second part of our tutorial. In the next part. we will add in some helper functions and begin to add our various UIkit components. As always, I’m open to comments good or bad. Feel free to reach out either in the comments section or by email for additional help!

Metta!!

Update: I have now finished a full-length version of the UIkit plugin for Pinegrow. Purchase of this plugin not only adds the UIkit framework to Pinegrow for unlimited sites, but it also gives you access to the completed code for learning purposes! As a bonus, I’ll give you access to a Facebook page to discuss coding for Pinegrow. Click here to learn more!!