Home > Support > Wicked Block Builder > Using Wicked Block Builder > Attributes

Attributes

The Attributes screen lets you define the attributes that your block will have. Attributes can either store data for your block or extract data from the content of your block.

Attribute Types

There are several types of attributes you can add to your block depending on the type of data your block will be using:

  • String attributes
  • Number attributes
  • True/false (boolean) attributes
  • Array attributes

Note: it’s important to select the appropriate attribute type for the type of data you want to work with. Some components only work with certain attribute types. For example, the Image component requires a Number attribute.

String Attributes

String attributes are used for text-based content. This can be things like headlines and labels but can also include rich-text that contains HTML.

Number Attributes

Number attributes are used for numeric data. For example, the Image component uses a Number attribute to track the ID of the selected image.

True/False Attributes

True/false (also known as boolean) attributes are used for data that can only be true or false. For example, a toggle component would use a true/false attribute to track if the toggle is on or off.

Array Attributes

Array attributes are used for working with a collection of data. Unlike the other attribute types, array attributes can have child attributes. Child attributes let you specify the properties that each item in the array will have. For example, if you wanted to create a block that displayed bios for people in your company, you might create an array attribute named “people” with child attributes for “name” and “bio”. This would allow you to track the name and bio for multiple people in your block.

Adding Attributes to Your Block

Click on the Attributes tab in the builder and then click Add Attributes in the sidebar. You can either click or drag an attribute type to add it to your block.

Attribute Settings

Click on an attribute to select it. The attribute’s settings will be displayed in the sidebar.

Attribute Name

This is the name of your attribute and how you’ll refer to it in other areas when building your block.

Important: if you rename an attribute after you’ve already linked it to a component, you’ll need to re-link it. You will also need to update any token references. Renaming attributes can cause your block to break if you forget to update the name somewhere. For this reason, it’s best to plan your block ahead of time to minimize changes.

Attribute Source

The attribute source refers to where the data for the attribute will live. When your block is loaded in the editor, WordPress will populate your block’s attributes based on the attribute’s source.

Block meta

When the block meta source is selected, data for the attribute will be stored in the metadata for the block. For technical users, this means the JSON that is stored in the block’s comment delimiter.

Note: block meta is not the same thing as post meta and is not related to post meta in any way.

Note: always use the block meta source if you are creating a dynamic block.

The block meta source is the easiest to work with because it doesn’t require any additional configuration to work properly. However, this often means that data for your block will be duplicated in the database: once in the block’s metadata and again in the block’s HTML.

For example, imagine you create a simple block with a single attribute named “headline” and a RichText component that lets you type in the headline. If the “headline” attribute’s source is set to block meta, the headline will be stored in the block’s metadata as well as the block’s HTML in the database. Generally speaking this is not something to be worried about. If you’d prefer to avoid this duplication though, you can use one of the other attribute sources that allow you to extract the attribute’s value from the block’s HTML instead.

Attribute

The Attribute source extracts content from an HTML attribute. It might seem a little confusing at first due to its name but “attribute” in the context of a source refers to an HTML attribute, not a block attribute.

An example of when you might use the Attribute option as a source is working with links. Imagine a block that outputs a single link. Now imagine you want to have a text field that lets you enter the URL. To do this, you also need to create an attribute to manage the content of the text field so let’s say you create one named “url”.

As mentioned previously, if you chose the block meta option as the source for your url attribute, the URL will be stored in both the block meta and HTML. It will look something like this in the database:

<!-- wp:wicked-block-builder/sample-link-block 
   {"_wbbBlockId":"kv3wvohu","url":"https://wickedplugins.com"} -->
<div class="wp-block-wicked-block-builder-sample-link-block">
    <a href="https://wickedplugins.com">Visit Wicked Plugins</a>
</div>
<!-- /wp:wicked-block-builder/sample-link-block -->

Notice how the URL (https://wickedplugins.com in this case) exists in two places: in the block meta and inside the href attribute of our link.

To avoid this duplication, you can instead extract the URL from the href attribute of the block’s link. You would do this by entering “a” in the attribute’s Selector field (more about selectors later) and “href” in the Attribute field.

When our block is loaded in the editor, WordPress will “select” the <a> tag and initialize our “url” attribute to the value in the tag’s “href” attribute. Now when we save our block, it will look something like this in the database:

<!-- wp:wicked-block-builder/sample-link-block {"_wbbBlockId":"kv3wvohu"} -->
<div class="wp-block-wicked-block-builder-sample-link-block">
     <a href="https://wickedplugins.com">Visit Wicked Plugins</a>
</div>
<!-- /wp:wicked-block-builder/sample-link-block -->

The block takes up less storage now because the URL isn’t duplicated.

Text and HTML Attribute Sources

The Text and HTML attribute source options work similarly to the Attribute source option. Instead of extracting content from an element’s attribute, the content is extracted from between the element’s opening and closing tags.

Let’s return to our headline block example. If we use block meta as the source for our “headline” attribute, our block will look something like this in the database:

<!-- wp:wicked-block-builder/sample-headline-block
     {"_wbbBlockId":"kv3wvohu","headline":"Hello World!"} -->
<div class="wp-block-wicked-block-builder-sample-headline-block">
    <h2>Hello World!</h2>
</div>
<!-- /wp:wicked-block-builder/sample-headline-block -->

Notice how “Hello World” is stored twice: once in the block meta and again in the <h2> tag.

We can change the source of the headline attribute to Text and set the Selector to h2. When our block loads in the editor, WordPress will select the <h2> element from our block and initialize the headline attribute to the content extracted from between the opening and closing <h2> tags. When we save the block, it will look like this in the database:

<!-- wp:wicked-block-builder/sample-headline-block
     {"_wbbBlockId":"kv3wvohu"} -->
<div class="wp-block-wicked-block-builder-sample-headline-block">
    <h2>Hello World!</h2>
</div>
<!-- /wp:wicked-block-builder/sample-headline-block -->

Both the Text and HTML source options extract content from between opening and closing tags.

Important: use the HTML (or block meta) source option any time your content may contain HTML. Always use the block meta or HTML source option for attributes that will be controlled by a RichText component.

Query

The Query source selects a collection of HTML elements from your block. The query source can only be used with Array attributes.

An example of when you might use a Query source is an image gallery block. You could create an attribute called “images”, set the Attribute Source to Query, and set the selector to “img”. This would select all <img> tags in your block. You could then add child attributes to the “images” attribute to extract various image data such as the URL, alternate text, etc. from your block’s HTML.

Important: if you use the Query source for an array attribute, child attributes must use a source other than block meta.

Selector

The Selector field is used to enter a CSS selector that will select the element(s) from your block that you want to extract data from. For example, imagine your block has a single attribute named “headline” and a RichText component that let’s people enter an H2 headline. You can choose HTML for the Attribute Source and enter “h2” in your “headline” attribute’s Selector field. When your block is loaded in the editor, WordPress will select the h2 (since you entered “h2” as the selector) and extract the content from between its opening and closing tags into your “headline” attribute.

Note: the Selector field does not appear when the Attribute Source is set to block meta.

Attribute

When Attribute is selected in the Attribute Source dropdown, an Attribute field will appear. The Attribute field lets you specify the name of the HTML attribute you want to extract data from. Use the Selector field to control which element the HTML attribute is fetched from.

For example, imagine you want to extract the URL from a link in your block. If your block contains a single link, choose Attribute from the Attribute Source dropdown, enter “a” in the Selector field, and enter “href” in the Attribute field. When your block is loaded in the editor, WordPress will select the <a> element from your block and extract the value from the element’s href attribute into your block’s attribute.

Default Value

The Default Value field lets you specify a default value for your attribute.