Documentation: Using Custom Elements

[InoPlugs]

Basics

Using and working with a CET is similar to working with a normal ALB element, but there are a few things you need to know to understand the difference and can take more advantage of this powerfull feature.

To follow this tutorial please use the following settings on WP Dashboard -> Theme Ext4ensions -> Custom Elements:

Custom Elements Management: Editors and Admins Custom Elements Locked Options: Show locked options to all users Checkbox To Show Locked Options: Checked for all users Checkbox Show advanced options: Check

Let us start to explain with a simple ALB button element .

Normal workflow would be:

• Create a new page
• Switch to Advanced Layout Builder
• Drag a button element on the page
• Open the modal popup of the button and make your settings

You might face the following problems if you need more buttons:

• For every button you need on your site you must set the settings seperatly, even if many settings are the same for several buttons
• If you decide to change layout or text settings you must do that for every button

At this point a CET can bring you a great help.

The standard ALB button has default settings that are predefined and preselected (we focus only to a few to make it easier to follow):

• Button Label: Click Me
• Show Button Icon: Display icon to the left
• Button Size: Small
• Button Colors Selection: Basic options only
• Button Color: Theme Color

Let's say, you need a special designed button several times in your site it would help to have your settings already predefined. This is the first use of a CET:

• Click the Custom Elements Tab
• Click the "Add New Custom Element" button to create a new Custom Element
• A modal window opens:
  • Select "Button"
  • Give it a name, e.g. "Contact Me Button"
  • Add an additional tooltip for this button
  • Click button "Create Element"
• The known button modal popup opens with the default settings preselected and a few more settings:
  • Lock Symbol checkbox for most settings (ignore at this stage - we will explain later)
  • "Customize Tab" (ignore at this stage - we will explain later)
  • Change the settings:
  • Button Label: Contact Me
  • Show Button Icon: Display icon to the right
  • Button Size: Large
  • Button Colors Selection: Basic options only (leave it)
  • Button Color: Blue
  • CLick "Save" button
  • In the "Custom Elements" Tab you now see the button "Contact Me Button"
  • Drag this button on the page. When you hover over this button you will see a red closed padlock left of the "Delete" icon. This shows, that this button is based on a CET button
  • Open the modal popup as known from a normal ALB button. The button has the above settings preselected. In background the default settings for this CET have really been changed to your settings.
  • You are free to change any setting of this button on the page

Important: A CET behaves like a normal ALB element but YOUR settings are predefined. For advanced users: the underlying shortcode attributes are modified.

If you later want to change any of these settings:

• Click the "Edit Custom Elements" button
• Hover over the button "Contact Me Button" and click the pencil
• The button modal popup with the additional settings field opens
• Make your changes and save

When you now drag the CET on a page you have the new settings.

Important: All other already existing buttons on your page(s) remain unchanged !!! Only new added buttons have the new settings.

In real world you would like to maintain a consistent layout for your button across your site without the need to edit each button seperatly.

Lets say you must change the color for all your "Contact Me Button" to red:

• Click the "Edit Custom Elements" button
• Hover over the button "Contact Me Button" and click the pencil
• The button modal popup with the additional settings field opens
• Change the color to Red
• Below you see a blue open padlock left of Lock "Button Color"
• Click it - it turns red and gets closed
• Click Save to close the modal
• Click on the button element on the page to edit it
• Check the option Button Color:
  • Selectbox no longer available, only the "locked" value Red
  • Red padlock left of Button Color
  • It is not possible to change this option in this element any longer as it has been locked in the CET this element is based on

If you now reload the pages containing this element you will see that all the buttons have turned red (clear server cache if using a cache plugin and browser cache).

Important:

• Locked values in a CET override any previous value of already existing elements on pages
• Non locked values in a CET DO NOT change any previous value of already existing elements on pages
• Locking/Unlocking a value in a CET DOES NOT make any changes to already existing elements on a page, the locked value replaces the original value on the fly on page load. For advanced users: the underlying shortcode attributes on pages are not modified, when executing the shortcode handler a check for locked values returns and replaces the attribute values from the page shortcode.

Locking depending settings:

Have a look at the button setting Button Colors Selection.

Depending on the selection the option Button Color is visible or not. If you want to make sure that the button color Red is used and cannot be changed you also must lock Button Colors Selection. Keep this in mind and be careful, as you cannot be sure what settings are set in the elements on the pages.

The Customize Tab

This tab in a modal popup contains the option "Select a Custom Element to lock values". In our case open the modal popup of a button and you find in the dropdown:

• No Custom Element used - all options available
• Contact Me Button
• in case you have more CET buttons all buttons are listed

On a page open the modal from:

• an ALB button element: "No Custom Element used ..." is selected, nothing is locked
• a CET button element: "Contact Me Button" is selected and locked values cannot be changed

It is possible to change the underlying Custom Element or back to No Custom Element used - the modal popup is reloaded to reflect the new situation for locked/unlocked values.

This means, if you have an existing page with an ALB button and want this button to have the locked values of a custom element you only need to select this custom element in the list. The other way you can also select another custom element as base for a page element that was originally a CET.

Important: changing the underlying template DOES NOT make any changes to the existing settings of the element on a page. This allows to change and check the styling of an element without loosing your previously made settings when switching around. For advanced users: the underlying shortcode attributes are not changed.

Advanced Option: Hierarchical Custom Elements

This means, that a CET is based on another CET. If the option is set to "Allow use of hierarchical custom elements" then you also have the "Customize Tab" when editing a CET.

This allows to group settings and narrow down the options that can be changed.

Basically the same behaviour as described above, only one big difference:

Important - this behavior is different to the one when used on a page:

When changing to another CET as base the settings of this underlying CET are set as new defaults in this CET - but are not copied when the underlying settings are changed later. When switching back to "No Custom Element used" the existing settings are NOT changed.

Lets have a look at an example, our button element:

Lets say you need a fixed color for all buttons:

Create a CET button "Fixed Color" with color: Red. and lock

Create another CET button "Small":

• Select "Fixed Color" as Custom Element to lock values (= "Fixed Color" becomes parent)
• Color Red is locked, becomes the new default and cannot be changed
• Select Button Size "Small" and lock

When using the CET button "Small" on a page you find both color and size locked.

If you change the color to "Blue" in CET button "Fixed Color", the CET button "Small" on the page changes to blue in frontend. The CET button "Small" did not change the color setting RED.

Important: In case you change the hierarchie of CET: Locked values are checked from first parent up ( "Fixed Color" -> "Small" -> .... )

Advanced Option: Custom Elements For Subitems

It is also possible to use CET for elements which open another modal for subiltems like Button Row which has buttons (as Button Row Items).

By default: 'All subitems use the same custom element template'.

This means, when you create a CET for a Button Row you define and lock your settings for the base element and can open one modal popup for a button and define and lock your settings for a button of the button row.

These settings and locked values are used as base for all buttons you later add to a button row when using this CET on a page.

This theme option setting is a shortcut only. In backend an own CET for this subitem is created and managed. This allows to switch to select individual CET's for each subitem.

When this theme option is selected, hierarchical CET are not possible for elements with subitems.

"Individually select subitem custom element templates"

• create CET's for each of your subitems first (same with Add New Custom Element and select a subitem)
• make your settings and lock values
• in the selectbox "Select a Custom Element to lock values" in the modal popup for subitems you find all available CET's

---

Added 2021-02-28

Extend the description for the last option to make it more clear.

"Individually select subitem custom element templates"

With this option selected you can use seperate subitem CET for each subitem. We will explain this using an ALB button row element.

Create the CET for the Button Row itself

Steps are similar as described for a button:

• Click the Custom Elements Tab
• Click the "Add New Custom Element" button to create a new Custom Element
• A modal window opens:
  • Select "Button Row"
  • Give it a name, e.g. "Custom Button Row"
  • Add an additional tooltip for this button row
  • Click button "Create Element"
• The known button row modal popup opens with the default settings preselected and a few more settings:
  • Disabled setting "Create an editable template" with "Base element template"
  • One button with default settings already added
  • Lock Symbol checkbox - Lock "Add/Edit Buttons"

You need a buttonrow several times with the same buttons

• Add your buttons as used from normal ALB Element, make all the settings for the buttons
• Click the padlock Lock "Add/Edit Buttons"
• CLick "Save" button
• In the "Custom Elements" Tab you now see the button "Custom Button Row"
  • Drag this button on the page and click to edit
  • The buttons cannot be changed, added or removed - settings from CET for the buttons will be used

You want to add buttons later

• You can ignore the Add/Edit Buttons button - any settings you make will be ignored, also if you add buttons
• Make your settings for the other options and lock, what you like
• CLick "Save" button

Now you must create your button row buttons, called button row item, for each styling you need:

• Click the "Add New Custom Element" button to create a new Custom Element
• A modal window opens:
  • Select "--- Button Row Item"
  • Give it a name, e.g. "Button Row Item1"
  • Add an additional tooltip for this button row item
  • Click button "Create Element"
• The known button row modal popup opens, only 2 options available as we must edit the item only:
  • Disabled setting "Create an editable template" with "Item element template"
  • One button with default settings already added
  • Click the button
  • Modal popup for the button opens with padlocks, make your changes
• CLick "Save" buttons to close popups
• Add as many subitems as you like via "Add New Custom Element" button
• Drag the button row CET on the page and click to edit
• Now you can add as many buttons you like and in the modal popup of each button select the CET from the dropdown (Customize Tab)

[mgmason]

I recommend making these text changes, I also added some screenshots that may help with the explanation:

Basics

Using and working with a CET is similar to working with a normal ALB element, but there are a few things you need to know to understand the difference between the two so you can take full advantage of this powerful feature.

To follow this tutorial please use the following settings on WP Dashboard -> Theme Extensions -> Custom Elements:

Custom Elements Management: Editors and Admins
Custom Elements Locked Options: Show locked options to all users
Checkbox To Show Locked Options: Checked for all users
Checkbox Show advanced options: Check

Let us start our example with a simple ALB button element.

The Normal workflow would be:

• Create a new page
• Switch to Advanced Layout Builder
• Drag a button element on the page
• Open the modal popup of the button and make your settings

You might face the following problems if you need more buttons:

• For every button you use on your site you must set their settings separately, even if they share many of the same settings across your site.
• In the future if you decide to change your button layout or text settings you must do this for each button.

This is the point were a CET can help greatly.

The standard ALB button has default settings that are predefined and preselected (we will focus on only a few to make it easier to follow):

• Button Label: Click Me
• Show Button Icon: Display icon to the left
• Button Size: Small
• Button Colors Selection: Basic options only
• Button Color: Theme Color

Let's say, you want a specially designed button used several times on your site, it would help to have your settings already predefined. This is the first use of a CET:

• Click the Custom Elements Tab
• Click the "Add New Custom Element" button to create a new Custom Element

• A modal window opens:
  • Select "Button"
  • Give it a name, e.g. "Contact Me Button"
  • Add an additional tooltip for this button
  • Click button "Create Element"
  
• The known button modal popup opens with the default settings preselected and a few more settings:
  • Lock Symbol checkbox for most settings (ignore at this stage - we will explain later)
  • "Customize Tab" (ignore at this stage - we will explain later)
• Change the settings:
  • Button Label: Contact Me
  • Show Button Icon: Display icon to the right
  • Button Size: Large
  • Button Colors Selection: Basic options only (leave it)
  • Button Color: Blue
  
• Click the "Save" button
• In the "Custom Elements" Tab you now see the button "Contact Me Button"

• Drag this button on the page. When you hover over this button you will see a red closed padlock left of the "Delete" icon. This shows, that this button is based on a CET button

• Opening the modal popup is the same as a normal ALB button. The button has the above settings preselected. In background the default settings for this CET have been changed to your settings.
• You are free to change any of the settings of this button on this page and it will follow these settings. The power of a CET is that you are able to predefine the settings and speed up your workflow.

Important: A CET behaves like a normal ALB element but YOUR settings are predefined. For advanced users: the underlying shortcode attributes are modified for the element.

If in the future you want to change any of these settings:

• Click the "Edit Custom Elements" button
• Hover over the button "Contact Me Button" and click the pencil

• The button modal popup with the additional settings field opens
• Make your changes and save

When you now drag the CET on a page you have the new settings.

Important: All other already existing buttons on your page(s) remain unchanged !!! Only newly added buttons have the new settings.

In the real world you would like to maintain a consistent layout for your buttons across your site without the need to edit each button separately.

Lets say you must change the color for all your "Contact Me Button" buttons to red:

• Click the "Edit Custom Elements" button
• Hover over the button "Contact Me Button" and click the pencil
• The button modal popup with the additional settings field opens
• Change the color to Red
• Below you see a blue open padlock left of Lock "Button Color"
• Click it - it turns red and gets closed

• Click Save to close the modal
• Click on the button element on the page to edit it
• Check the option Button Color:
  • Selectbox no longer available, only the "locked" value Red
  • Red padlock left of Button Color
  • It is not possible to change this option in this element any longer as it has been locked in the CET this element is based on
  

If you now reload the pages containing this element you will see that all the buttons have turned red (clear server cache if using a cache plugin and browser cache).

Important:

• Locked values in a CET override any previous value of already existing elements on pages
• Non locked values in a CET DO NOT change any previous value of already existing elements on pages
• Locking/Unlocking a value in a CET DOES NOT make any changes to already existing elements on a page, the locked value replaces the original value on the fly on page load. For advanced users: the underlying shortcode attributes on pages are not modified, when executing the shortcode handler a check for locked values returns and replaces the attribute values from the page shortcode.

Locking depending settings:

Have a look at the button setting Button Colors Selection.

Depending on the selection the option Button Color is visible or not. If you want to make sure that the button color Red is used and cannot be changed you also must lock Button Colors Selection. Keep this in mind and be careful, as you cannot be sure what settings are set in the elements on all of the pages across your whole site.

The Customize Tab

This tab in a modal popup contains the option "Select a Custom Element to lock values". In our case open the modal popup of a button and you find in the dropdown:

• No Custom Element used - all options available
• Contact Me Button
• in case you have more CET buttons all buttons are listed

On a page open the modal from:

• an ALB button element: "No Custom Element used ..." is selected, nothing is locked
• a CET button element: "Contact Me Button" is selected and locked values cannot be changed

It is possible to change the underlying Custom Element or switch to No Custom Element used, in either case the modal popup is reloaded to reflect the new situation for locked/unlocked values.

This means, if you have an existing page with an ALB button and want this button to have the locked values of a custom element you only need to select this custom element in the list. Another way is to select another custom element as a base for the page element and select the CET you wish.

Important: changing the underlying template DOES NOT make any changes to the existing settings of the element on a page. This allows you to change and check the styling of an element without loosing your previously made settings when switching between them. For advanced users: the underlying shortcode attributes are not changed.

Custom Elements Advanced Option: Hierarchical Custom Elements

If this option is set to "Allow use of hierarchical custom elements" then a CET can be based on another CET. Then you can make your settings in the "Customize Tab" when editing a CET.

This allows you to group settings and narrow down the options that can be changed.

Basically the same behavior as described above, only one big difference:

Important - this behavior is different to the one when used on a page:

When changing to another CET as base the settings of this underlying CET are set as new defaults in this CET - but are not copied when the underlying settings are changed later. When switching back to "No Custom Element used" the existing settings are NOT changed.

Lets have a look at an example, with our button element:

Lets say you need a fixed color for all buttons:

Create a CET button "Fixed Color" with color: Red. and lock

Create another CET button "Small":

• Select "Fixed Color" as Custom Element to lock values (= "Fixed Color" becomes parent)
• Color Red is locked, and it becomes the new default and cannot be changed

• Select Button Size "Small" and lock

When using the CET button "Small" on a page you find both color and size locked.

If you change the color to "Blue" in CET button "Fixed Color", the CET button "Small" on the page changes to blue in frontend. The CET button "Small" did not change the color setting RED.

Important: In case you change the hierarchy of CET: Locked values are checked from first parent up
( "Fixed Color" -> "Small" -> .... )

Custom Elements Advanced Option: Custom Elements For sub-items

It is also possible to use CET for elements which open another modal for sub-items like Button Row which has buttons (as Button Row Items).

By default the setting is: 'All sub-items use the same custom element template'.

With the default setting, when you create a CET for a Button Row and you define and lock your settings for the base element, and you can open one modal popup for a button and define and lock your settings for a button in the button row.

These settings and locked values are used as base for all buttons you later add to a button row when using this CET on a page.

This theme option setting is a shortcut only. In the backend a new CET for this subitem is created and managed. This allows you to select individual CET's for each subitem.

When this theme option is selected, hierarchical CET's are not possible for elements with sub-items.

"Individually select subitem custom element templates"

• create CET's for each of your sub-items first (same with Add New Custom Element and select a subitem)
• make your settings and lock values
• in the selectbox "Select a Custom Element to lock values" in the modal popup for sub-items you find all available CET's

[mgmason]

Update for last section

"Individually select subitem custom element templates"

With this option selected you can use a seperate subitem CET, for each subitem used in the parent. We will explain this using an ALB Button Row element.

Create the CET for the Button Row itself

Steps are similar as described for a button:

• Click the Custom Elements Tab
• Click the "Add New Custom Element" button to create a new Custom Element
• A modal window opens:
  • Select "Button Row"
  • Give it a name, e.g. "Custom Button Row"
  • Add an additional tooltip for this button row
  • Click button "Create Element"
• The known button row modal popup opens with the default settings preselected and a few more settings:
  • You will find the "Create an editable template" setting is set to "Base element template".
  • One button is already added with the default settings.
  • An added Lock Symbol to lock the "Add/Edit Buttons" option.
  

If you want a Button Row used several times with the same buttons

• Add your buttons as usual from this "Button Row - Customize: Custom Button Row", as shown above, and make all the settings for the buttons you wish.
• Click the padlock Lock "Add/Edit Buttons", to lock the option.
• CLick the "Save" button.
• In the "Custom Elements" Tab you now see the button "Custom Button Row"
• Drag this button on the page and click to edit
  • The buttons cannot be changed, added or removed - settings from CET for the buttons will be used

If you want to add CET buttons to the Button Row later

• You can ignore the Add/Edit Buttons option as any settings or buttons you make will be ignored.
• Make your settings for any other options and lock as you wish.
• CLick the "Save" button

Now you must create a button for your Button Row, called a "Button Row Item":

• Click the "Add New Custom Element" button to create a new Custom Element
• A modal window opens:
  • Select "--- Button Row Item"
  • Give it a name, e.g. "Button Row Item1"
  • Add an additional tooltip for this button row item
  • Click button "Create Element"
  
• The known Button Row modal popup opens, and only 2 options shown as we can only edit the button item:
  • The "Create an editable template" is set with "Item element template", and can not be changed.
  • One button with default settings is already added and available.
  
  • Click the button
  • Modal popup for the button opens with padlocks for each option, make change as you wish.
  
• Then click the "Save" buttons to close the popups.
• Add as many Button Row Items as you would like via "Add New Custom Element" button, following the same steps as above.
• Then drag the Button Row CET onto the page and click to edit.
• Now you can add as many Button Row Items you wish, in the modal popup of each Button Row Item select the CET from the dropdown in the Customize Tab.

Here the Button Row CET shows the "Button Row Item" CET

Please Note: A subitem CET, such as the "Button Row Item", will not show in the ALB Custom Elements block area, but it will be available within the parent element CET.