Skip to content

Instantly share code, notes, and snippets.

@atanas-dev

atanas-dev/theme-builder-docs.md

Last active February 5, 2021 17:12
Show Gist options
  • Save atanas-dev/692be85eb77b9a7ca6b7ab6b266facf6 to your computer and use it in GitHub Desktop.
Save atanas-dev/692be85eb77b9a7ca6b7ab6b266facf6 to your computer and use it in GitHub Desktop.
Download ZIP
Raw
theme-builder-docs.md

Theme Builder Hooks

The Theme Builder provides a number of hooks allowing you to add wrapper HTML tags or fill in your custom theme's header or footer if necessary, when Theme Builder is active for the current page.

The Theme Builder and custom themes

When used in a custom theme, the Theme Builder may replace the header, body, footer or some combination of the previous depending on how the user configures their templates. Due to the nature of headers and footers in custom themes the Theme Builder will always treat them as a pair meaning that if you use a layout for either, both will be overridden.

As a custom theme developer, you may wish to add support for the Theme Builder so that when only the header is replaced your custom footer is still shown or when the footer is replaced your custom header is still shown. To achieve this you should use the provided layout hooks.

Layout Hooks

et_theme_builder_template_head

Fires inside <head></head> immediately before wp_head() when the header is replaced.

Type: Action
Since: 4.0

et_theme_builder_template_before_page_wrappers

Fires before Theme Builder page wrappers are rendered.

Type: Action
Since: 4.0

Param Type Description
$layout_id integer ID of the layout that is about to be rendered. Will be 0 if no layout is going to be rendered.
$layout_enabled boolean Flag whether the layout area is enabled.
$template_id integer ID of the template currently being loaded for the page

Tips:

  • Use this hook combined with et_theme_builder_template_after_page_wrappers to add a global top-level page wrapper div that you need for your site: 
    function my_theme_builder_open_page_wrapper( $layout_id, $layout_enabled, $template_id ) {
  echo '<div class="my-page-wrapper">';
}
add_action( 'et_theme_builder_template_before_page_wrappers', 'my_theme_builder_open_page_wrapper', 10, 3 );

function my_theme_builder_close_page_wrapper( $layout_id, $layout_enabled, $template_id ) {
  echo '</div><!-- .my-page-wrapper -->';
}
add_action( 'et_theme_builder_template_after_page_wrappers', 'my_theme_builder_close_page_wrapper', 10, 3 );

et_theme_builder_template_after_page_wrappers

Fires after Theme Builder page wrappers are rendered.

Type: Action
Since: 4.0

Param Type Description
$layout_id integer ID of the layout that is about to be rendered. Will be 0 if no layout is going to be rendered.
$layout_enabled boolean Flag whether the layout area is enabled.
$template_id integer ID of the template currently being loaded for the page

et_theme_builder_template_before_header

Fires before the header Theme Builder layout is rendered.

Type: Action
Since: 4.0

Param Type Description
$layout_id integer ID of the layout that is about to be rendered. Will be 0 if no layout is going to be rendered.
$layout_enabled boolean Flag whether the layout area is enabled.
$template_id integer ID of the template currently being loaded for the page

Tips:

  • Use this hook combined with et_theme_builder_template_after_header to add a header wrapper div: 
    function my_theme_builder_open_header_wrapper( $layout_id, $layout_enabled, $template_id ) {
  echo '<div class="my-header-wrapper">';
}
add_action( 'et_theme_builder_template_before_header', 'my_theme_builder_open_header_wrapper', 9, 3 );

function my_theme_builder_close_header_wrapper( $layout_id, $layout_enabled, $template_id ) {
  echo '</div><!-- .my-header-wrapper -->';
}
add_action( 'et_theme_builder_template_after_header', 'my_theme_builder_close_header_wrapper', 11, 3 );
  • Use this hook to add your custom header back in cases where the user has added a Theme Builder footer layout but no header layout: 
    function my_theme_builder_custom_header( $layout_id, $layout_enabled, $template_id ) {
  // Only add the custom header if there is no Theme Builder header
  // being rendered and the header layout area is not disabled.
  if ( 0 === $layout_id && $layout_enabled ) {
    // Render our custom header, for example:
    echo '<div class="my-custom-header"></div>';
  }
}
add_action( 'et_theme_builder_template_before_header', 'my_theme_builder_custom_header', 10, 3 );

et_theme_builder_template_after_header

Fires after the header Theme Builder layout is rendered.

Type: Action
Since: 4.0

Param Type Description
$layout_id integer ID of the layout that was just rendered. Will be 0 if no layout was rendered.
$layout_enabled boolean Flag whether the layout area is enabled.
$template_id integer ID of the template currently being loaded for the page

Tips:

  • Use this hook combined with et_theme_builder_template_before_footer to add a content wrapper div when the header and footer are replaced by Theme Builder: 
    function my_theme_builder_open_content_wrapper( $layout_id, $layout_enabled, $template_id ) {
  echo '<div class="my-content-wrapper">';
}
add_action( 'et_theme_builder_template_after_header', 'my_theme_builder_open_content_wrapper', 15, 3 );

function my_theme_builder_close_content_wrapper( $layout_id, $layout_enabled, $template_id ) {
  echo '</div><!-- .my-content-wrapper -->';
}
add_action( 'et_theme_builder_template_before_footer', 'my_theme_builder_close_content_wrapper', 5, 3 );

et_theme_builder_template_before_body

Fires before the body Theme Builder layout is rendered.

Type: Action
Since: 4.0

Param Type Description
$layout_id integer ID of the layout that is about to be rendered. Will be 0 if no layout is going to be rendered.
$layout_enabled boolean Flag whether the layout area is enabled.
$template_id integer ID of the template currently being loaded for the page

Tips:

  • Use this hook combined with et_theme_builder_template_after_body to add a content wrapper div when the body is replaced by Theme Builder: 
    function my_theme_builder_open_inner_content_wrapper( $layout_id, $layout_enabled, $template_id ) {
  echo '<div class="my-inner-content-wrapper">';
}
add_action( 'et_theme_builder_template_before_body', 'my_theme_builder_open_inner_content_wrapper', 9, 3 );

function my_theme_builder_close_inner_content_wrapper( $layout_id, $layout_enabled, $template_id ) {
  echo '</div><!-- .my-inner-content-wrapper -->';
}
add_action( 'et_theme_builder_template_after_body', 'my_theme_builder_close_inner_content_wrapper', 11, 3 );

et_theme_builder_template_after_body

Fires after the body Theme Builder layout is rendered.

Type: Action
Since: 4.0

Param Type Description
$layout_id integer ID of the layout that was just rendered. Will be 0 if no layout was rendered.
$layout_enabled boolean Flag whether the layout area is enabled.
$template_id integer ID of the template currently being loaded for the page

et_theme_builder_template_before_footer

Fires before the footer Theme Builder layout is rendered.

Type: Action
Since: 4.0

Param Type Description
$layout_id integer ID of the layout that is about to be rendered. Will be 0 if no layout is going to be rendered.
$layout_enabled boolean Flag whether the layout area is enabled.
$template_id integer ID of the template currently being loaded for the page

Tips:

  • Use this hook combined with et_theme_builder_template_after_footer to add a footer wrapper div: 
    function my_theme_builder_open_footer_wrapper( $layout_id, $layout_enabled, $template_id ) {
  echo '<div class="my-footer-wrapper">';
}
add_action( 'et_theme_builder_template_before_footer', 'my_theme_builder_open_footer_wrapper', 9, 3 );

function my_theme_builder_close_footer_wrapper( $layout_id, $layout_enabled, $template_id ) {
  echo '</div><!-- .my-footer-wrapper -->';
}
add_action( 'et_theme_builder_template_after_footer', 'my_theme_builder_close_footer_wrapper', 11, 3 );

et_theme_builder_template_after_footer

Fires after the footer Theme Builder layout is rendered.

Type: Action
Since: 4.0

Param Type Description
$layout_id integer ID of the layout that was just rendered. Will be 0 if no layout was rendered.
$layout_enabled boolean Flag whether the layout area is enabled.
$template_id integer ID of the template currently being loaded for the page

Tips:

  • Use this hook to add your custom footer back in cases where the user has added a Theme Builder header layout but no footer layout: 
    function my_theme_builder_custom_footer( $layout_id, $layout_enabled, $template_id ) {
  // Only add the custom footer if there is no Theme Builder footer
  // being rendered and the footer layout area is not disabled.
  if ( 0 === $layout_id && $layout_enabled ) {
    // Render our custom footer, for example:
    echo '<div class="my-custom-footer"></div>';
  }
}
add_action( 'et_theme_builder_template_after_footer', 'my_theme_builder_custom_footer', 10, 3 );
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment