Build your own Blocks

Everybody loves blocks! The idea of having a set of reusable website sections is very appealing. And for a good reason – most websites and web apps share a lot of similar elements: navigation menus, headers, services, portfolios, and so on. So why not package these sections into blocks and use them to quickly build different websites? With Pinegrow, that’s easy & quick!


Let’s build a set of blocks right now.

To start we need a source website that we’ll cut into blocks. We can create it from scratch or use one of our existing websites or templates.

Here we’ll use an existing website, a typical one-page website of a digital services agency. To play along, download the sample website or open one of your websites that contains sections you would like to turn into blocks.

demopage

If you’ll be using an existing website, it’s a good idea to make a copy of the website and define blocks on the copy. That project will become a blocks library.

Download the Pine template (PineThemeOriginal) used in this tutorial and the finished blocks library (PineBlocks) that you can use to build you own websites.

IMPORTANT: Using components requires that you open your website as a project (File -> Open project), not just opening a single file.

Structure

First, we have to decide how to split the webpage into blocks. The document tree lets us explore the page structure.

For some elements the decision is straightforward:

The whole navbar should become a Navbar block.

The whole section#intro should be an Intro block, because both its children – the div with a background image and the container with content – are integral parts of the intro.

One block = One element. We can’t build a block consisting of two top elements. Of course, the top element can contain as many descendants as we want.

The three colored boxes where the company is boasting about its solutions and creative ideas is just a fluid container, without a section wrapping it. Personally I would wrap it in a section so that we would have a consistent layout structure.

About section, on the other hand, contains a couple of parts that would be more useful as separate blocks: content block with image, call to action, Twitter feed carousel, testimonials, vision & mission, the team and counters of achievements. So there we don’t want to add the whole section as a single block.

structure

Some are straight up containers, while others are containers wrapped in divs. That divs create full-width areas with light grey background. Here we have a choice: do we add divs as blocks or just containers? Both options have their advantages and neither is wrong. But whatever we decide it’s a good idea to be consistent. So, either all blocks should contain the full-width color band div (remember, transparent is also a color) or none should.

Here we’ll use the first approach – each block, except navbar, will come wrapped in a section element. To do that we’ll reorder children of the about us section and make each into an individual section.

What we decide here will not fix the way blocks can be used. We’ll still be able to change layout when we use our blocks to build websites.

 

Once we set the structure and decide on the approach the rest is easy.

Making blocks

We’ll use Pinegrow’s Smart components to create blocks.

Let’s start with the navbar.

Select the navbar in the tree, switch to ACT (Actions) panel and add Define component action to the selected element. Clicking on the action name will add the action and show its properties. Clicking on the name again will remove the action from the element. Another click will add it back. And so on.

Every component needs an unique id and a name. A good way to organise ids is to use a unique project prefix. In our case, we’ll use “pine.” since Pine is the name of our template.

So, the id will be pine.navbar and the name will be Navbar. The name doesn’t have to be unique. Just use something that makes sense.

definecomponent

By default Smart components are auto-updatable. That means that updating the project with Components -> Update will replace all instances of the component with its latest definition. We can even define editable areas within the component that will be preserved during updates. That’s a very powerful feature that is useful in many situations. But that’s probably something we don’t want for our simple blocks.

We want to be able to define blocks, place them on pages in various projects and customise them according to the needs of each project, without thinking about updates and editable areas.

So let’s uncheck the Update instances property.

We’ll still be able to change this setting later or to update blocks manually.

With that the component is defined and we use Components -> Update to let Pinegrow process it and list it in the LIB panel from where it can be reused.

Component -> Update is needed for changes to component definitions to take effect.

Let’s also take the photo of the component so that we get a nice image of the block shown in the LIB.

Turning the rest of the sections into blocks is easy.

 

Resources

Usually, it’s not enough to just define HTML elements as blocks. They also require CSS stylesheets, Javascript code, images and other files to display and function correctly. We call these files resources.

To set which CSS stylesheets and Javascript files are required by our blocks open Resources Manager and use Project view to add required files. As a good practice, do not add framework files (like Bootstrap or Foundation) into resources because projects where blocks will be used will most likely already contain the required framework files or could even use customised versions of the files. It’s much better to simply say: “Pine Blocks require Bootstrap.”

resources

For Javascript resource files we’ll choose the option to include them in the footer of the page.

Let’s also add the images folder so that the image placeholders will be there when we use the blocks.

Resources will be included in documents in the order of how they are listed in Resources Manager. Files in the Resources Manager can be reordered at any time.

 

Script blocks

Just one more thing to do. Notice that our blocks page uses an inline script block to initialise Javascript plugins. Without this code, the Javascript part of our blocks will not function correctly. But we can’t include this code as a resource in Resource manager because it is not a Javascript file.

This part is specific to our example template. But we often find inline script in the wild and it’s good to know how to handle them.

We have two options here:

  1. Save the code into a separate Javascript file and include it with Resource manager – or –
  2. Add the script as a block and remember to manually add it to the page where we’ll use blocks.

We’ll use the second approach because it is cool that we can convert scripts into blocks.

script

Here’s the whole process:

 

With that our Pine blocks library is complete.

Using blocks

We can use blocks in the same project where they are defined or in other projects.

Why would we want to use blocks in the same project where they are defined?

Imagine we have a project, a website about a very specialised topic with many subpages. We could define a set of blocks specific to that topic and reuse them across those pages. In practice it might be better to use auto-updatable components with editable areas for such scenarios. That’s a topic for later.

We can either add blocks to an existing project or start a new one.

We’ll use our freshly baked blocks to create a new website project.

Let’s open a new Pinegrow window and select File -> New page -> Bootstrap -> Index. Save the file into a new folder and choose to open the folder as a project.

Adding blocks library to the project

Use Page -> Manage libraries and plugins -> Load component library to load Pine blocks. Simply select the project folder where blocks are defined.

Pinegrow will load the library.

We have to activate the library for the current page / project to actually use it there.

Pinegrow will ask if we want to add the required resource files to the project. Say yes, of course. At the moment our project has only one HTML page so it doesn’t matter wether we choose to add resources to the current file or to all files in the project. We can also add or update resources later by going to Library & Plugins manager and clicking on Resources next to the library.

Placing blocks on the page

Blocks are now listed in the LIB panel.

From there we can drag them to the page or to the tree, just like any other element from the LIB panel.

By default, only editable areas of Pinegrow components can be edited. But, remember, we unchecked the Auto update property on our block components. That means that we can freely edit any part of our block. We have to be aware though, that updating component instances (blocks placed on the page) will restore the block instance to its original definition and all our edits will be lost.

 

Changing and updating blocks

At any time we can open the project where blocks are defined (the Pine template in our case) and modify the blocks. To update blocks instances in projects where they are used, open that project, refresh libraries and then update blocks one by one, by selecting a block and using Actions -> Update instance.

In case of auto-updatable components Components -> Update command would do that for us automatically.

Master pages

Even though our Pine blocks are defined on a single HTML page, we can place them on multiple pages within our new project. To do that we simply duplicate or add new pages and add blocks to them as desired.

As soon as we have more than one HTML page in our project it makes sense to start using Master pages. We can create a special page called master.html (or similar) or we can just use the index.html as the master page. Let’s do that.

We have to choose which element on the master page will be the editable content area. For this purpose we might have to add an element like div that will act as the container for the content that will differ from page to page.

In most cases it is best to define the navbar on the non-editable parts of the master page and set editable classes on menu items so that each subpage can highlight a different menu item.

Page title and description fields in the HTML head are also good candidates for editable areas, so that each page can have its own title and description.

Master pages will let us quickly apply edits to all pages in the project.

 

WordPress & PHP blocks

When defining and reusing blocks (and components in general) we’re not limited to HTML. We can also create block with Pinegrow WordPress actions or blocks that contain PHP code blocks. Bootstrap Blocks for WordPress are a good example of that.

Doing that lets you create reusable building blocks for WordPress themes and PHP applications.

Collaboration and source control

Blocks are defined by simply adding data-pgc-* attributes to the regular HTML code. That means that you can freely use source control like Git or any other web development & team collaboration tool that operates on HTML and CSS files to edit and manage blocks libraries.

Organising libraries with lots of blocks

Our Pine template had just a couple of blocks, so it made sense to keep them all on the same page and displayed in the same section in the LIB panel.

In larger libraries we can define blocks on multiple pages and use Define section actions to organise blocks into different LIB sections.

Guidelines to remember:

  1. One element = one block. If you need two or more elements at the top-level of the block, wrap them in a div (or section) and make that a block.
  2. Consistency across the whole library is more important than optimising blocks on individual basis.
  3. Avoid using HTML ids in CSS selectors. That will make it impossible to place more than one instances of the block on any given page because ids have to be unique. After changing the id of such a block CSS rules won’t target it any more.
  4. Use unique and sensible prefixes for all component ids.
  5. Use auto-updatable components if you need to update existing block instances after changing the block definition.