Components

Smart components are reusable website elements that can have editable areas. Go through this article to learn about everything you can do with them.


Important: Components only work with projects. To use them you have to open the folder where your website is located with File -> Open project.

Use ComponentsTutorial sample project together with this document to explore examples mentioned here.

Smart components are reusable website elements.

Any HTML element can become a smart component.

Why would you want to use components?

Let’s say that you have a Team section with four team members (see 1-team.html in examples). Each team member is a <div> that has a <h3> with name, <p> with description and <img> with their picture.

Instead of creating the same layout four times you could just create one and turn it into a smart component.

How to define a component?

It’s very simple. Just create the first team member in the Team section, like you would normally do.

Then select the Team member element, go to ACT panel and click on “Define component”. This will add “Define component” action to the element and display action properties.

Set component id to something like “team.member” and name to “Team member”.

team1

The component id must be unique across all libraries and plugins that are activated on a page. It’s a good idea to give them a library-specific prefix, for example “myblocks.”.

The orange Update components button will light-up on the top toolbar. Click on it (or press CMD + U) to quickly update components on all open pages. Press SHIFT + CMD + U to update the whole project.

team2

This will add your new component “Team member” into a LIB panel. Choose Actions -> Take component’s photo to add the image to the LIB panel.

team3

If you want to use the photo for a preview but not show it in the LIB panel (only have a text label there), check “Use photo only for preview”. LIB panel will be updated when you update the whole project or use Components -> Reload components from project.

Component definition can also have a description that is shown in the preview of the component in the LIB panel.

c2.def.options

From LIB panel you can place the component on any page in your project. Let’s go ahead and insert three instances of this component after the first team member.

team4

Notice that component definition are marked with a blue border and component instances with a yellow one. This can be turned on and off with Components -> Mark components.

team5

That’s nice. But what’s so “Smart” about these components?

First of all, these components are auto-updatable.

Updating components

Go back to the first team member where the Team member component is defined. Change the picture and set image shape to Circle…

team7b

…and press the Update components button or CMD+U shortcut. The images in all instances of Team member component will become round.

team8b

“That’s so great” you might say and happily start editing the names, pictures and descriptions of team members.

But when you get to the second team member Pinegrow will not let you edit anything! Why not? Because any changes done to component instances will be lost the next time you update components – the second, third and fourth team members (instances of the Team member component) will become the same as the first team member (definition of the Team member component).

team9

“Oh… Such components are useless!”

You’re right! That’s why Smart components have Editable areas. More about that below. Let’s first take a look at options for controlling how component instances are updated.

Disabling auto updating

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. That’s a very powerful feature that is useful in many situations. But sometimes we wan’t to keep things very simple.

Blocks are one such example. 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.

Check out Build your own Blocks for examples.

Option A – Disabling updates on component definition

In such cases we uncheck the “Update instances” property on component definition.

cs.update1

At any time you can manually update instances of such component by choosing “Actions -> Update component instance”:

c2.update2

Option B – Disabling updates on instances

Another way to prevent updating component instances is to check “Don’t update” checkbox on individual component instances.c2.update3

Editable areas

Editable areas define elements, attributes and classes that can be customised in component instances.

Lots of cool things can be done with editable areas, please check out Editable areas documentation for details.

Nested component definitions

Component definitions can be nested. In most cases you want the child components to be defined within an editable area of the parent component. This is easier to explain with an example:

Let’s create a Team section component that will also include definition of Team member component. The benefit of this is that we will also have a ready-made team block that we can just drag on the page and customise it.

Select the container and add “Define component” action to create Team section component. Add a heading and make it editable. Then make the row that contain team members into an editable area. This area contains the team member component definition and two team member instances.

Element that contains child component definitions and instances must be defined as editable area otherwise those components can’t be customised.

Update components and our new Team section component is ready for use.

c2.nested

Organising components into LIB sections

Component sections let us organise components into different LIB sections.

Simply add “Define section” action on any element of the page. All component defined on that element or inside that element will be placed under that section in the LIB panel.

cs.sections1

Sections can also be defined on the top page element. Then, all components on the page will go into the section. In that way we can have each page corespond to a LIB section.

cs.sections2

Make instance of…

“Make instance of” is a super useful feature – if you know how and when to use it.

To use it, select an element on the page, right-click on the component in the LIB panel and chose “Make selected element instance of”.

The selected element will become an instance of the chosen component. Try it on 4-makeinstanceof.html.

But that’s not all. Pinegrow will also try to match component’s editable areas to appropriate elements in the selected element. That will work as long as the structure of the component and the structure of the element are compatible.

Let’s imagine we have an existing page with team members implemented as plain HTML layout, without components. We want to change those team members into instances of our Team member component.

c2.make1

When using “Make instance of” Pinegrow will inspect the structure of the component definition and of the selected element and try to match editable areas in the component to elements in the target element. For example, if H1 is used for the team member’s name in the definition and H1 is also used for team member’s names on the page, Pinegrow will automatically convert the target heading into an editable area.

c2.make2

This is very handy when adding components to an existing HTML page and when changing one component instance into an instance of another component.

Go to definition…

Right-click on any component in the LIB panel and select “Go to definition” to open the page where the component is defined and select the component definition.

c2.gotodef

Note, this command will also open components defined in external projects. If you make changes to the definition, you will have to do “Components -> Refresh loaded libraries” before updating components.

Duplicate definition…

Right-click on a component in the LIB panel and select “Duplicate definition” to clone the definition and insert it right after the selected element. Pinegrow will ask if you want to change the id of the new definition. Id of the copy should be different than the id of the source component, unless you plan to delete the source definition after duplicating it.

c2.duplicate

Where to define components?

In the example above we defined components on the page where they were also used. We defined the Team member component on the first occurrence of team member in index.html. Then we used this component to create additional three team members.

Another approach would be to create a special page, for example called lib.html and define the Team member component there. Then we would place four instances of this component into the Team section on index.html.

In our experience the special page approach is easier to maintain and reuse. Still, you can select the one that works best for your project.

Reusing components between projects

Up to now we were using components within a single project. Let’s call it Project A. The Team member component was both defined and used in Project A.

Imagine that now we start to work on a website for another client that will also include a Team section. Let’s call this project Project B.

Wouldn’t it be convenient if we could simply use the Team member component from Project A in Project B?

We can do that with Pinegrow!

Open Project B and open or create the page where team members will be listed.

Use “File -> Load project as library” to load Project A as a component library.

Team member component is now listed in LIB panel. Simply place team members on the page just like you would any other element from the LIB panel.

What should we do if we need to change the component defined in library project?

Imagine that we want to change the Team member component by adding the job title of each member under the name. Because the component is defined in Project A, we have to open Project A and make the change there.

No need to close Project B to do that! Select “File -> Open project” in new window and open Project A in a new Pinegrow window.

There we make the necessary edits (add <p class=”job-title”> under <h3> and make the element editable with Editable area action) and save changes.

Back in Project B we choose “Components -> Refresh loaded libraries” and then Update components. That will reload components from Project A and update components on open pages.

Check out Using Blocks to see this in practice. Video is included.

Component library resources

In many cases components rely on CSS stylesheets, Javascript files, images and other files to display and function correctly. These files are called component library resources.

Imagine that we add team.css to Project A. This CSS file includes CSS rules for styling team members. We also add a folder assets/images/team with placeholder images for team members.

We want these resource files to be included in Project B (or any other projects that will use the Team member component).

But first we have to set which resources are required for Project A component library.

To do that we open Project A, and in PRJ tab right-click on team.css and select “Required by library”. That will open the Resource editor dialog and add team.css to the list of resources. There we can reorder resources to set the correct order for how they’ll be included on pages. For Javascript files we can also choose to include them in the footer of pages (by default CSS and Javascript files will be included in the <head> element).

Do the same for assets/images/team folder – right click on the folder in PRJ view and choose “Required by library”.

Click on Save in Resource editor window to save changes.

Back in Project B choose Components -> Refresh loaded libraries and Components -> Add or update resources. A dialog window will open. Under Project A section choose either “Add to all files” or “Add to the current page” to copy resources to Project B and include them on pages. Library resources are placed in folder components/<library name> in order to avoid conflicts with existing files.

These steps are needed only when library resources change and need to be updated or added to the project that is using the library.

If we would now open Project C and load Project A as library, Pinegrow would ask us immediately if we want to add Project A library resources to Project C.

Check out our Blocks tutorial to see how resources are added and used.

Tutorials and sample projects

ComponentTutorial – Sample project with examples mentioned in this document.

Build your own Blocks – Step by step tutorial on building library of reusable website sections. It even comes with a sample project that you can use to create your own websites.

Opening times widget with Component and Tutorial – A reusable Pinegrow component for showing opening times with step-by-step tutorial.

Download sample project used in this article with Team members, Navbar and Service components.

Did you know?

  • Every project is its own library. (Open Project A and check File -> Manage libraries and plugins and you’ll see Project A listed among the loaded libraries)
  • Every project can be loaded as a library of another project.
  • Use “Update components” button or Components -> Quick update to update components on all open pages. Use “Components -> Update whole project” to update components on all files in the project.
  • Components are a powerful feature. It is strongly recommended that you use some kind of source control (Git, for example) with your projects.