You Do: Create a feature with content editable fields

One powerful aspect of PageBuilder magic is the ability for editors to quickly change text or links on the page, on the fly, without even selecting the custom field pane. Using content editable for text that might change frequently (such as headlines) is a way to streamline an editor's workflow.

Goals:

1. Create a PageBuilder feature that allows an editor to manually curate text by clicking on an admin page.
2. Beneath that text, allow an editor to set a link, with content-editable text.

If you already have a test feature you've been working on, you can skip steps 1 - 3, which involve creating a PageBuilder feature with gulp commands, and displaying that data on the page. The most important parts of this lesson are the attributes needed to make a PB feature content editable, described in Step 4.

Code is provided at the end of Step 1 & 2, Step 3, and 4.

View the complete code on Github.

Step 1: Create a PB feature

Make sure you have PB up and running with vagrant up, and you have started Tomcat and PB from the localhost:9999 screen before doing these steps.

You can optionally do this with Gulp by running gulp createFeature. If you aren't familiar with this step, see the section labelled Gulp Task Automation.

Run gulp createFeature from the root of the repo to get started.

Step 2: Create the required custom fields.

This feature is going to be a "Trending Link" feature. It will display an editable label, as well as a trending link to a story that an editor can curate. (Yes, this example is a bit contrived).

First, add the labelText field. Run gulp addCustomField, and enter the following:

Next, add the trendingLink custom field. This will be the actual URL a user is brought to when the click on the link. Run gulp addCustomField again, with this info:

Next, add the trendingLinkText custom field. This is the text for the link a user should click on. Run gulp addCustomField again, with this info:

Confused? View the current Step 1 and 2 code on Github.

Step 3: Display information from your feature.

Inside the feature.jsp of your newly created feature, you will see that two variables from custom field variables: labelText, trendingLinkText and trendingLink have been assigned (one of the perks of using gulp).

If you try to put the feature on a page now, you will see a big white screen of... nothing. However, you will see your Custom Fields in the Custom Fields tab.

Troubleshooting: I don't see my feature in the dropdown of features.

Make sure that PB was up and running by going
to the localhost:9999 screen and starting PB and Tomcat.

Once it's up and running, run gulp and save example/trending-link/config.json. This will trigger gulp to reload the configurations for the feature, so it can be used locally.

If that doesn't work, try going to the Load Configurations screen and entering example/trending-link in the input box at the lower-left of the screen and clicking Load.

To display the values from your code, add the following below the declared variables in feature.jsp:

<label>${labelText}</label>
<a href="${trendingLink}">${trendingLinkText}</a>

Optional styles: If you want your test feature to look like it came from the 90s, run gulp and leave it running, then add these styles to style.scss.

Save, and check again -- you should see text on the page, and you can change the values of the custom fields to whatever you'd like, and watch them edit almost in real time.

View the code up to this point on Github.

Step 4: Make these fields editable on the page.

This is pretty cool, but it can be tedious to open the custom field pane every time. Wouldn't it be nice to edit these fields directly on the page? We'll do that now.

First: We'll make the label content editable. Add the following attributes to the label container:

data-pb-field="custom.labelText" 
data-pb-placeholder="Default Label Text" 
data-pb-field-type="text"

The completed label will look like this:

<label data-pb-field="custom.labelText"
       data-pb-placeholder="Default Label Text"
       data-pb-field-type="text">${labelText}</label>

Go to the page and click on the label -- you can now edit it directly on the page. The custom field saves every time you make a change.

Note: You need to make sure not to leave any whitespace around ${labelText} -- see how it is carefully nestled between the two <label> tags. If you do have whitespace, it will still be editable, but will jump around on the screen. Try adding some, and you'll see it.

You can usually automatically prevent this behavior by including the trimwhitespace tag at the top of your feature.jsp.

Second: Make the link content editable. Add the following attributes to the a tag:

data-pb-url-field="custom.trendingLink"
data-pb-field="custom.trendingLinkText"
data-pb-field="text"
data-pb-placeholder="Enter link text."

The completed link will look like this:

<a data-pb-url-field="custom.trendingLink"
   data-pb-field="custom.trendingLinkText"
   data-pb-field="text"
   data-pb-placeholder="Enter link text."
   href="${trendingLink}">${trendingLinkText}</a>

Go to the page and click on the link -- you will see a small brownish-grey box that appears at the bottom of the screen where you can edit the text of the link as well as the link itself. You can also edit the text directly on the page -- awesome!

View the completed code on Github.

Summary:

You can make nearly any HTML element content editable using the attributes above, to help make an editor's workflow easier.