Editable areas

Editable areas are used in both Master pages and Smart components. They are layout elements that can be customized on content pages and in component instances. Different aspects of elements can be defined as editable: the content, attributes and classes.


Use ComponentsTutorial project to explore examples mentioned in this document.

Let’s take a look at the Team member component example to explore editable areas. We’ll make name, image, description and a couple of other elements editable, so that each component instance can represent a different team member.

Select the name (the <h3> element) in the Team member component definition (1-team.html) and add “Editable area” action from the ACT panel. Set the Field to something like “name”.

Editable content

By default the content of an editable area is editable.

team10

Field ids (names) only need to be unique within the component. That means that you can use nice Field ids like “name” on other components as well.

Now Update components.

Notice that name elements are highlighted and marked in the tree view as Editable. That means that the content of <h3> name elements can be edited and will not be lost when components are updated. Now we can fill in the names of our team members.

team11

Let’s go back to the component definition (the first team member) and change the name tag to <h1>.

team12

Update components. All names were changed to <h1> but the names of team members were preserved. Quite smart, isn’t it?

team13

Editable images (and editable attributes)

We can do the same for the team member picture. Select the <img> in component definition and add Editable area action to it. Because the image displayed with <img> is set with src attribute, we set the editable attributes to src.

team14

Update components and set images for team members. Like names, images will also be preserved during component updates. Let’s try this by changing the shape of the image in component definition to Rounded.

team15

Update components and voila – all images are now round.

team16

Editable classes

We can also declare some classes as editable. This is very useful for menus where the active menu item has .active class. Make each menu item Editable and set classes to active. That will tell Pinegrow to remember which menu item was active during component updates. We can place the navbar component on multiple pages and have “active” class assigned to the correct menu item.

Example: Navbar with editable “active” class on menu items

Let’s define a Navbar component for our website and set class “active” as editable on all menu items:

navbar1

Update components and Navbar will appear in the LIB panel. From there we place it on the Services page and mark Services menu item as active:

navbar2

Let’s switch to mobile size for better view. Then, in Navbar component definition, we change the navbar color to Inverse. Update components. See, the right menu items are still selected!

navbar3

Example: Editable Font Awesome icons with regular expressions

Pinegrow 2.93 added an easy, one-click way to make Font Awesome icon editable. See extensions below.

We can use regular expressions /…/ for advanced class control. For example use the following regular expression to let user choose Font Awesome icons while keeping icon sizes defined by the component. (And don’t forget to activate Pinegrow’s FontAwesome plugin for easy Font Awesome icon selection and configuration.)

See example in 2-services.html:

/(?!fa\-border|fa\-spin|fa\-pulse|fa\-flip\-horizontal|fa\-flip\-vertical|fa\-fw|fa\-inverse)(fa-[a-z\-]*)$/

fontawesome

Sometimes we just want to make classes or attributes editable and the content fixed. Check “Don’t edit content” to prevent content from being edited.

Editable background image

Since Pinegrow 2.92 background images can also be editable. That’s useful for headers, jumbotrons, sections and similar elements that display a background image with background-image CSS property.

To make background image editable select the element that will have the background image, add Editable area in the ACT panel, set Do not edit content if needed and then check Bck. image checkbox. See 3-background-image.html for example.

editable.bck

Note that in this case we have selected “Do not edit content” because we don’t want to make the whole inner content of the element editable. We have separate editable areas for title and text of the poster.

Take a look in the Components tutorial project for an example of component with editable background in background-image.html.

After updating components background images of editable areas can now be edited with Component properties or Style section, both in PROP panel:

editable.bck.set

Editable background images are set with background-image inline CSS property in the style attribute.

Default background image can be defined with a normal CSS rule for the element. This will work because background-image defined in inline style will take precedence.

CSS rules should also be used to define background image size, for example setting background-size to cover so that background image covers the whole element.

Collections – Specifying which component types can be used in the editable content

Since 2.92 you can specify which component types are editable in the inner content of the editable area.

Take a look at our Team component. It has an editable row “members” that contains instances of Team member component. Without limiting the types that can be used within this editable area content the whole inner content is editable. We could add any element into it, not just team members. In most cases, that’s not what we want.

edit.types.1

We can specify which component types are allowed inside the content by editing “Allowed components in content” property of the Define editable area action:

edit.types.2

Only component types defined in the project or loaded project libraries can be used here. To list general elements like H1 you first have to define them as components.

Here, we set that the editable area content can only include instances of Team member component. Pinegrow will let us add new Team members and duplicate, delete and rearrange the existing ones.

Component properties in the PROP panel will also get a handy “+ Add Team member” button that will insert new team member into the members editable area.

edit.types.3

Component definition can include other elements inside the editable area. But only specified component types will be editable.

Extensions

Pinegrow 2.93+ lets plugins define editable areas extensions.

Font Awesome editable icon

When Font Awesome plugin is activated and <i> or .fa element is selected, Define editable area action includes a checkbox that makes the icon editable:

ed6c

Bootstrap button type

Bootstrap plugin adds Button type checkbox to editable area definitions on .btn elements:

Editable areas as properties in PROP panel

Editable areas are also listed as component properties in the PROP panel. That’s a very convenient way to edit component instances. Let’s take a look at a couple of examples.

Our team member definition and instances have properties for changing the name, description and image:

c2.editable.props

Editable classes are also listed in Properties. For our navigation bar we can easily select which menu item is active:

cs.editable.props.nav

This works even for complex components like the opening times widget:

cs.editable.props.ot

You don’t have to do anything to get editable areas listed as properties – Pinegrow does that for you.

Repeatable elements

Components can have elements that can be repeated one or more times.

Let’s add a star rating to our team member component:

Insert Font Awesome star below the name and add a CSS class to make it golden. Update the components. Everybody got a one-star rating! We can’t even duplicate stars in component instances because the star is not editable.

cs.repeat1

Now, in team member definition, add “Repeatable area” action to the star and do the quick update. We need to name the area, for example with “star”.

cs.repeat2

With that we can duplicate stars in component instances to create individual star rating for each team member. Updating components will preserve the stars.

cs.repeat3

Repeated elements can also be editable, or they can contain editable areas.

Let’s add list of projects to team members:

Add heading and a list with one item below the team member description. The list item contains a link to the project.

Adding “Repeatable area” action to the list item (not on the link) will let us create as many list items as needed for each team member.

cs.repeat4

Then, we make the link (not the list item) editable by adding “Editable area” action and setting both the content of the link (that’s on by default) and the HREF attribute as editable.

cs.repeat5

Let’s update the components.

Now we can go to each team member, duplicate as many list items as we need and fill in project names and links. Updating components preserves our edits.

cs.repeat6

We can now change the layout of the project list (for example, change it to columns) and as long as field ids stay the same we’ll be able to update all instances without losing any editable data.

Optional elements can be deleted from component instances and will not be restored when components are updated. To restore all optional elements in an component instance use Page -> Restore optional components.

Optional areas

What if some team members don’t work on projects? At the moment we have no way of removing project list from team member instances. We could define a second team member component without the project list and use it for those team members.

But, there is a better way: we’ll make the project list optional.

Select the Projects heading and add “Optional area” action. As with editable and repeatable areas, we also have to name optional areas.

c2.optional1

Then, add “Optional area” to the project list and update components.

c2.optional2

Oh no! Now projects in all team member instances are gone!

c2.optional3

Why? The reason is that we defined elements as “Optional areas” after they already existed in team member instances. Projects heading and Project lists didn’t have the corresponding ids and Pinegrow could not correctly match the elements. The update assumed that those areas are not present in instances, and since they are optional, it didn’t add them to the instances.

In this situation – when we make elements that already exist in instances optional – we check “Ignore on update” on “Define optional area” action and then run the update. Optional elements will not be removed in existing instances.

c2.optional4

After the update is done and optional areas are marked in existing components we uncheck the “Ignore on update” checkbox, update components and start using optional areas.

Above step is not necessary if elements that are marked as optional don’t yet exist in component instances.

Now we can delete optional elements from component instances. Updating the components will not add removed elements back.

c2.optional5

But what if we change our mind? How can we get deleted optional elements back?

Easy. Select the instance and chose “Restore optional areas” from Actions. Note that this will restore all optional areas in the component instance.

c2.optional6

Storing unused editable data

Some actions can lead to loss of edited information in component instances. Pinegrow saves that data so that you can easily get it back.

Deleting the editable element from the component definition will remove the element from all component instances. Let’s delete team member heading and update components. The names of all instances are gone, as they should be.

cs.saved1

But Pinegrow doesn’t just throw the data away. Take a look at the instances source code. Unused edits are stored as HTML comments.

cs.saved2

So if you add the editable area back to the component definition (or another element with the same field id) and update components, the saved edited data will re-appear.

Another scenario where edits get lost is changing the field id of an editable area and updating components without changing the field ids in component instances. Thanks to saved editable data, restoring the field id will bring the original edits back.

cs.saved3

But what to do if we really don’t need the saved data anymore? Easy. Use Components -> Clear unused edits to remove HTML comments with saved edits either from the current page or from the whole project. You should do that before deploying your project to production.

cs.saved4