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.

The Pinegrow Editor screen

    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.

jumbotron code
Pinegrow constructs clean code
UIkit logo

    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:

Terminal feedback when cloning repo
github cloning button

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. 

SCSS directory structure

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

Styling files
Location of JS files

    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:

    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:

    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.

    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!

Published: 06.17.2019

In: Pinegrow, Programming

11 thoughts on “Adding UIkit to Pinegrow: Pt 1”

  1. mr. memyselfandi says:

    Thanks a lot, man! Very useful, this opens up some new possibilities to start a project in Pinegrow with some custom framework templates. 

  2. Bob Means says:

    No problem, glad I could help.

  3. Vince says:

    Rob,
    Thank you for your efforts and consideration for putting this together. We’ve been asking for better developer documentation for years from Pinegrow. Hopefully this will generate interest in further expanding on a great tool.
    Be well, (Namaste)
    Vince (Ravi)

    1. Bob Means says:

      Hey Vince,
      Thanks for the comment. Over on Facebook, Matjaz reached out to thank me. At least the people at Pinegrow are watching what is happening in the community, so maybe that documentation will happen. In the meantime it is a bit more pressure on me to interpret the code I’m sorting through correctly!!
      Metta!
      Bob

  4. I am bit confused on what to do with the code right after you talk about Visual Studio. Where do I save it?

  5. Bob Means says:

    Hey Brian – sorry about that. Re-reading my post it looks like I forgot to add some info there – I will update soon! In the meantime, that code should be saved as ‘custom.scss’, in your resources -> css folder.

  6. Thanks Bob and thanks for this tutorial, great work!

  7. schpengle says:

    HI there, Ok Im doing this 🙂

    and the same question arose as in 

        July 4, 2019 at 9:29 pm    
    so dont forget to update this to say where to save that pesky custom.scss file 🙂
    I had to read the comments to clarify.
    Finally, THANK YOU SO MUCH, for creating this tutorial to enable the adding of a whole….THING!
    to Pinegrow.

    It’s a fantastic tool but lacking in user customisations and adding and 3rd party plugins, apart from Ben Hanna 🙂
    I am still waiting for a sublime text plugin…. that’s been a few years now.
    Well written things like this will help get the ball rolling 🙂

    Finally…. wow!
    This tutorial ISN’T responsive…… :p
    hee hee hee

  8. Bob Means says:

    Thanks for reading/trying it out Schpengle! Sorry for the non-clarity – I thought I had edited to main post, but it looks like I didn’t. I will do that after this reply.
    By the tutorial not being responsive, do you mean my webpage design? I threw this theme together pretty quickly without a lot of testing, but I thought it sorted out okay on phone/tablet.

  9. Schpengle says:

    cheers for the additional info edit 😉
    This is a lovely intro and oh! im also a donkey 😉
    for now it IS RESPONSIVE…. My Internet was so slow that it took an AGE FOR PAGE TO RESIZE.
    And since I lost connectivity a few times during the page load, it never did.
    oops!

  10. Bob Means says:

    Okay – if reviewing all of the tutorials I realized that Guttenberg is altering some of the code in my syntax highlighter. In this case, it removed a return in the JSON code that caused a problem with Pinegrow parsing it. This led Pinegrow to ask if you wanted to use SASS, which is just what we didn’t want!! The code snippet above has been corrected

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.