Adding UIkit to Pinegrow: Pt 1

Namaste!

NOTE: This post has been edited on July 5, 2019, for clarity (Thanks, Brian!) and to correct an error. And again on Aug. 11, also for clarity (Thanks, Schpengle!) For some reason, some of the JSON sections are not being read correctly when a new project is started, so I will eliminate them and talk about them in a future tutorial.

   In the next series of posts, I’m going to walk through putting together a plugin for the Pinegrow web editor.

    First, a few details about Pinegrow for those that haven’t heard of it. Pinegrow is part of a new generation of page builders. It has a number of capabilities that allow web designers to both take control of the code that is generated, but also tools for quick page layout. These include “blocks” or snippets of HTML that can be dragged onto the editor screen to visually construct your page. There is the ability to edit inline text and manipulate many aspects of your page very easily.

    Pinegrow comes standard with several frameworks, including Materialize, Bootstrap, and Foundation. Each of these frameworks has a number of associated blocks to make the construction of new pages easy. For example, the iconic Bootstrap 4 ‘Jumbotron’ can be added to the page by simply dragging and dropping the element from your library to the screen. 

This adds in the typical Jumbotron with filler text that can be edited. Examining the actual code for the page you can see that the final code doesn’t show the presence of any added fingerprints from Pinegrow.

    Okay, enough of the ad for Pinegrow. Several people on the Pinegrow Facebook page and over at the forum have asked about utilizing a specific framework, UIkit. This framework is composed of a number of HTML, custom CSS, and JavaScript components. It powers a large number of modern websites and is well supported by a large open-source development team on GitHub. There are some simple ways that we could begin the usage of UIkit with Pinegrow. The simplest would be to use our favorite code editor to alter our basic HTML template to load the minimized UIkit files and then start designing. The problem with this is that none of the components would be available to drag-and-drop. Hence, this tutorial about adding UIkit components in as a plugin to provide the native functions of UIkit in our Pinegrow editor panels.

    The documentation for the Pingrow plugin API is a little short and sketchy, but the code for adding the 960 Grid system to Pinegrow is quite extensive. This nicely covers the main component that needs to be in our plugin, the main JS file that defines the framework. There are several other sets of components that we could add and will be using in this project. One important one for utilizing the UIkit framework is a theme file containing all of the .scss files. In order to provide previews of the components that we want to add, we will also need to provide a folder with a preview image for each. Finally, we can provide a starter template for the user, rather than having them add the UIkit library to some other template with potential conflicts. There isn’t really any limit to what you can add into your plugin and only the core JS file is really required.

    Let’s get started! First, create a home folder for your project and add two sub-folders to start off: images and template. Within the template folder add an additional sub-folder – resources. Next, we are going to clone the GitHub repo for UIkit. This is because we want to use the Sass files, otherwise, we could just download the compiled libraries. There are multiple ways that you can do this, but the easiest for me is to pull up a command line terminal and clone the repo to your computer. This requires that you have Git installed on your computer. If so, navigate in your terminal to the folder that was just created and issue the command:

git clone https://github.com/uikit/uikit.git

If you don’t have git set-up on your computer ( What!!!!! Have you no version control! ) then you can navigate to the GitHub repo and click on “Clone”. This will give you an option to download a .zip of the repo to your desktop. Download and unzip wherever is easiest for you. Next, we will move some of the files into the folders where we want them for our plugin. 

    First, let’s move the SCSS files into our uikit_theme folder. Navigate to the repo 'src' folder and find the enclosed 'scss' folder. Copy all of the files from there into a folder named'uikit_theme' inside the ‘resources‘ folder. Note: if you prefer Less over Sass (Sassy CSS – scss) you can elect to grab those files instead – like keeping it all JavaScript, don’t you, you devilish beast!!

    Alrighty – next up, let’s create two new folders in our 'resources' folder. One named 'css' and one named 'js'. Navigate into the 'uikit' -> 'dist' -> 'css' folder and grab the two minified .css files. Copy those files into your 'resources' -> 'css' folder. From the UIkit 'dist' -> 'js' folder copy the two minified files to your new 'js' folder.

    Okay, for now, we are good. We will dive into the delicious goody bag of the UIkit source for additional components in future parts of this tutorial. For now, we have copied everything we need to get started. To give the plugin user access to the built-in Sass functions of Pinegrow, we need to create one additional file – the file containing the compiled CSS that we can link to the various variable files, as well as a custom SCSS file for storing changes to the framework.

    At this point, I’m going to open up the entire project in Visual Studio Code. It is available for most O/S, has a ton of plugins, and great features. I’ll just drag the home folder into VSC to open it. Next, create a new file named 'custom.scss' in the 'template' -> 'resources' -> 'css' folder and add the following code:

//Import any fonts here, (e.g., @import url('https://fonts.googleapis.com/css?family=Roboto&display=swap');)

//Add your custom variables and variable overwrites here, (e.g., $primary-color: #DA7D02;)

//This imports the default variables and mixins
@import "../../uikit_theme/variables-theme.scss";
@import "../../uikit_theme/mixins-theme.scss";

//Add in any custom mixin overwrites here

//Import the UIkit
@import "../../uikit_theme/uikit-theme.scss";

    Okay, if you are used to working with Sass or Less this will look familiar to you. UIkit requires that the processor walk through the compiling in a strict order. Part of this is due to CSS rules and part of it is due to getting the precedence correct. Starting from the top:

1. We put in a comment to remind users to stick any font imports into the sheet prior to any CSS rules.
2. Next, UIkit requires that you make any variables available prior to it working through the existing SCSS sheets and we remind the user of this.
3. Next, we bring in the variable and mixin SCSS sheets. This loads in a list of all of the variables and mixins, respectively.  In this case, I have elected to bring in the theme sheets, which basically load in the entire kitchen sink. In you know UIkit, you can pick and choose, but you can also throw out unused variables from Pinegrow later.
4. Next, we add a comment to remind the user to add in custom mixins.
5. Finally, we bring in the main SCSS sheet that will load all of the component files. Again, I went with the theme sheet that loads everything.

    Next, create another file in the same folder simply named ‘custom.css‘.  This file will recieve all of our compiled CSS. If you chose you can also add in another style sheet for conventional CSS or add a new one when starting a project. Whichever you prefer.

    With that saved away, we are just a few steps away from having our plugin structure set-up. While it would be easy enough for the end-user of our plugin to manage the style sheets manually for compilation, it is somewhat unpleasant for it to ask us about stylesheet compilation as soon as we start a new template. We don’t roll that way, do we!! Pinegrow stores a JSON file within your project to keep track of a lot of different settings, like CSS breakpoints and stylesheets. Within the home folder, create a new file named 'pinegrow.json'. Open the file up and add the following:

{"files":{"starter.html":{
    "frameworks":
    ["pg.insight.events","pg.css.grid","pg.image.overlay","pg.code-validator","pg.project.items","pg.asset.manager","pg.uikit","pg.html","pg.components"],
    "last_page_width":1024
    }},
    "breakpoints":["640px","960px","1200px","1600px"],
    "frameworks":
    ["pg.insight.events","pg.css.grid","pg.image.overlay","pg.code-validator","pg.project.items","pg.asset.manager","pg.uikit","pg.html","pg.components"],
    "template_framework_id":"pg.uikit",
    "useSourceStylesheet":{
"resources/css/custom.css":"true",
"template/resources/css/custom.css":"true"
    }
}

    This section of JSON code will tell Pinegrow that we want to compile the 'custom.scss' file into the 'custom.css' file in the same directory.

    Only two steps left, hang in there!!!

    Next up, navigate to the ‘template‘ folder and create a new file named ‘starter.html'. At this point, I’m only going to put some very basic page boilerplate with some specific links. Feel free to add your own favorite boilerplate here.

<!DOCTYPE html>
<html lang="en-gb" dir="ltr">
    <head>
        <meta charset="utf-8">
        <meta name="viewport" content="width=device-width, initial-scale=1">
        <title>UIkit Starter Template</title>
        <link rel="stylesheet" href="resources/css/custom.css">
    </head>
    <body>
        <!--[if IE]>
      <p class="browserupgrade">You are using an <strong>outdated</strong> browser. Please <a href="https://browsehappy.com/">upgrade your browser</a> to improve your experience and security.</p>
    <![endif]-->
        <!-- Add your site or application content here -->
        <h1>Starter Template</h1>


        <!-- UIkit core JavaScript  ===================== -->
        <!-- Placed at the end of the document so the pages load faster -->
        <script type="text/javascript" src="../resources/js/uikit.min.js"></script>
        <script type="text/javascript" src="../resources/js/uikit-icons.min.js"></script>
    </body>
</html>

    Overall, the page shouldn’t be hard to interpret. We are just bringing our customized CSS stylesheet at the top and loading in the UIkit JavaScript at the bottom. Now that we have created this document, go ahead and open it in your favorite browser. Take a screenshot and convert the resulting file to a ‘jpg/jpeg’. This is the picture that will be displayed when people go to load this template from the ‘New page or project’ selection in Pinegrow. Create a folder named ‘screenshots‘ within the ‘template‘ folder and save your photo there. The name of the screenshot should be the same as the template file name, so in my case ‘starter.jpg‘. If you are including more than one template, each should have a screenshot with a matching name.

    Okay, that wraps up the first tutorial. Yes, I’m almost always this long-winded, I love ??? to hear myself type! Hopefully, if you bear with me the payoff will be worth it. The next steps are beginning to program the core framework for the plugin, followed by actually putting all the different code blocks together, and then wrapping up the entire package. Feel free to give any comments good or bad!

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!!