Markup and attributes

The Beans HTML API contains a powerful set of functions to create flexible and easily overwritable HTML markup, attributes and content output.

In most WordPress themes and plugins, it is required to overwrite an entire template file to make changes even if it is just to add or modify an attribute. The Beans HTML API address this issue and gives you full control of your markup and attributes.

All markup and attributes added using Beans are registered using a unique ID which can then be used to manipulate it. Markup ID’s may contain useful sub-filters. Read the Beans Filters documentation for more information.

Let’s first take a look how it can be used before moving on to a practical example.

Adding your own markup and attributes

Important: adding HTML using Beans HTML API is only necessary if you want make it extendable and overridable, you may use normal HTML in your own projects.

Markup and attributes are added using beans_open_markup_e() and beans_close_markup_e().

beans_open_markup_e( 'markup_id', 'html_tag',  array( 'attribute' => 'attribute-value' ) );

  echo '<!-- some content -->';

beans_close_markup_e( 'markup_id', 'html_tag' );

Self-closed markup, such as images or inputs, are added using beans_selfclose_markup_e().

beans_selfclose_markup_e( 'markup_id', 'html_tag', array( 'attribute' => 'attribute-value' ) );

Modifying markup and attributes

Once the markup and attributes are added, Beans HTML functions can be used to manipulate it.

It is important that you know how to find your Markup ID in order to manipulate it. To do so, you’ll need to first enable Beans development mode in your WordPress Admin->Appearance->Settings.

Once the development mode is enabled, the Markup ID’s are output in a data-markup-id tag in the front-end. This makes it super easy to find each markup id using your browser inspector tool as explained in the practical example further down.

Markup hooks

All markup added using Beans have dynamic action hooks firing around it.

  • {$markup_id}_before_markup, fires before the opening markup.
  • {$markup_id}_prepend_markup, fires after the opening markup (not available for selfclosed markup).
  • {$markup_id}_append_markup, fires before the closing markup (not available for selfclosed markup).
  • {$markup_id}_after_markup, fires after the closing markup.

This means pretty much anything can be added anywhere on a page by adding actions to the available hooks.

Example

For this example, some HTML is added using the Beans markup.

Important: adding HTML using Beans HTML API is only necessary if you want make it extendable and overridable which is what Beans Core uses, you may use normal HTML in your own projects.

// Open main html markup and add class and role attributes.
beans_open_markup_e( 'theme_main', 'main', array( 'class' => 'tm-main', 'role' => 'main' ) );
  
  // Open div html markup.
  beans_open_markup_e( 'theme_content', 'div' );
    
    // Open article html markup.
    beans_open_markup_e( 'theme_article', 'article' );
    
      echo '<!-- article content -->';
    
    // Close article.
   beans_close_markup_e( 'theme_article', 'article' );
 
  // Close div.
 beans_close_markup_e( 'theme_content', 'div' );

// Close main.
beans_close_markup_e( 'theme_main', 'main' );

Below is what you would see when inspecting your page using the browser inspector tool (if dev mode is enable).

<main class="tm-main" role="main" data-markup-id="theme_main">
 <div data-markup-id="theme_content">
    <article data-markup-id="theme_article">
      <!-- article content -->
    </article>
  </div>
</main>

Note how the Markup ID’s are added to the source output in a data-markup-id tag. From there, markup and attributes can easily be manipulated via a child-theme or plugin.

The content div could be removed using beans_remove_markup().

beans_remove_markup( 'theme_content' );

A tm-article class could be added to the article markup using beans_add_attribute().

beans_add_attribute( 'theme_article', 'class', 'tm-article' );

The main markup could be changed to a section using beans_modify_markup() and replace the class to tm-section using beans_replace_attribute().

beans_modify_markup( 'theme_main', 'section' );
beans_replace_attribute( 'theme_main', 'class', 'tm-main', 'tm-section' );

Finally, a title could be prepended to the article markup.

add_action( 'theme_article_prepend_markup', 'my_function_name' );

function my_function_name() {

  echo '<!-- added title content -->';
  
}

Below is what it would looks like after modifying the markup, attributes and appending the title.

<section class="tm-section" role="main" data-markup-id="theme_main">
  <article class="tm-article" data-markup-id="theme_article">
   <!-- added title content -->
    <!-- article content -->
  </article>
</section>

Once the development mode is disabled, the output will be nice and clean as below.

<section class="tm-section" role="main">
  <article class="tm-article">
    <!-- added title content -->
    <!-- article content -->
  </article>
</section>

Note how the data-markup-id tags are removed from the HTML.