{"id":2644,"date":"2022-07-02T14:18:52","date_gmt":"2022-07-02T14:18:52","guid":{"rendered":"https:\/\/academy.bricksbuilder.io\/?post_type=bricks_article&#038;p=2644"},"modified":"2023-10-09T12:32:45","modified_gmt":"2023-10-09T12:32:45","slug":"nestable-elements","status":"publish","type":"bricks_article","link":"https:\/\/academy.bricksbuilder.io\/article\/nestable-elements\/","title":{"rendered":"Nestable Elements (API)"},"content":{"rendered":"\n<p>Bricks 1.5 introduces <strong>Nestable Elements<\/strong>. Plus an API that allows you to programmatically define your own custom elements that can contain other elements. In exactly the structure you want.<\/p>\n\n\n\n<p>Prior to Bricks 1.5 every element in Bricks was &#8220;flat&#8221;. Meaning even though an element contained a deep HTML structure (like the Slider, etc.) you couldn&#8217;t click on an inner part of this element to edit it directly (e.g. contents of slide 3), or change the inner structure of it to your liking via Drag &amp; Drop, as you could do inside a layout element.<\/p>\n\n\n\n<p>Making it often impossible to properly customise more complex elements like the Icon Box, Pricing Table, List, etc.<\/p>\n\n\n\n<p>Complex elements such as the Accordion, Slider, and Tabs weren&#8217;t properly customisable at all.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">Full Access &amp; Control Over Individual Element Structure<\/h2>\n\n\n\n<p>Starting at version 1.5, Bricks provides three nestable elements:<\/p>\n\n\n\n<ul>\n<li>Accordion (Nestable)<\/li>\n\n\n\n<li>Slider (Nestable)<\/li>\n\n\n\n<li>Tabs (Nestable)<\/li>\n<\/ul>\n\n\n\n<p>Those elements were notoriously hard to properly customise due to their complex structure, and the limits of their &#8220;flat&#8221; element structure.<\/p>\n\n\n\n<p>Now that you can populate every slide with the elements you want, purpose-specific slider-like elements such as the &#8220;Carousel&#8221; &amp; &#8220;Team Members&#8221; are not really needed.<\/p>\n\n\n\n<figure class=\"wp-block-image size-large\"><img loading=\"lazy\" decoding=\"async\" width=\"1024\" height=\"398\" data-lightbox=\"true\"  src=\"https:\/\/academy.bricksbuilder.io\/wp-content\/uploads\/2022\/07\/bricks-1.5-nestable-accordion-1024x398.jpg\" alt=\"\" class=\"wp-image-2664\" srcset=\"https:\/\/academy.bricksbuilder.io\/wp-content\/uploads\/2022\/07\/bricks-1.5-nestable-accordion-1024x398.jpg 1024w, https:\/\/academy.bricksbuilder.io\/wp-content\/uploads\/2022\/07\/bricks-1.5-nestable-accordion-300x117.jpg 300w, https:\/\/academy.bricksbuilder.io\/wp-content\/uploads\/2022\/07\/bricks-1.5-nestable-accordion-768x299.jpg 768w, https:\/\/academy.bricksbuilder.io\/wp-content\/uploads\/2022\/07\/bricks-1.5-nestable-accordion-1536x598.jpg 1536w, https:\/\/academy.bricksbuilder.io\/wp-content\/uploads\/2022\/07\/bricks-1.5-nestable-accordion.jpg 1920w\" sizes=\"(max-width: 1024px) 100vw, 1024px\" \/><figcaption class=\"wp-element-caption\">Accordion &#8211; Nestable<\/figcaption><\/figure>\n\n\n\n<p class=\"callout-blue\">Nestable elements are going to exist alongside their flat origin elements for the foreseeable future until we have collected enough feedback &amp; fixed any major bugs in order to fully make the switch to nestable elements.<\/p>\n\n\n\n<p class=\"callout-blue\">Certain interactive nestable elements that are heavily JavaScript-driven (such as the Accordion, Slider, and Tabs) might prevent the Drag &amp; drop from working 100% on the canvas. If you encounter this behavior you can always add &amp; order elements by using the Structure panel too.<\/p>\n\n\n\n<p class=\"callout-blue\"><strong>Nestable tabs<\/strong>: If you need to change the `display` property of the tab &#8220;pane&#8221;, please do so by adding another &#8220;Block&#8221; element inside the panel and setting the <code>display<\/code> setting there. The pane itself uses <code>display: none<\/code> in order to hide all non-active panes. If you change the display setting there, all tab panes will always be visible.<\/p>\n\n\n\n<p>So you can start playing around with those new nestable elements, and slowly transition away from the old plain elements.<\/p>\n\n\n\n<p>Over time we&#8217;ll convert more and more <code>flat<\/code> elements into nestable elements, so that you&#8217;ll be able to properly customize most elements in Bricks once their nestable equivalent becomes available.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\" id=\"api\">Nestable Elements API<\/h2>\n\n\n\n<p>The rest of this article shows how to programmatically create your own nestable elements.<\/p>\n\n\n\n<p>A good starting point to learn about the new nestable elements syntax is to inspect the Bricks source code of the following nestable element files:<\/p>\n\n\n\n<ul>\n<li>accordion-nested.php<\/li>\n\n\n\n<li>slider-nested.php<\/li>\n\n\n\n<li>tabs-nested.php<\/li>\n<\/ul>\n\n\n\n<h3 class=\"wp-block-heading\">Define Your Custom Element As &#8220;nestable&#8221;<\/h3>\n\n\n\n<p>First make sure to set the <code><a href=\"https:\/\/academy.bricksbuilder.io\/article\/create-your-own-elements\/#builder\" data-type=\"URL\" data-id=\"https:\/\/academy.bricksbuilder.io\/article\/create-your-own-elements\/#builder\">$nestable<\/a><\/code> property of your custom element class to <code>true<\/code>. <\/p>\n\n\n\n<p>This is required so Bricks knows to render this custom element using the nestable render function in the builder, and to enable drag &amp; drop inside the builder for this custom element.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">Nestable Element Template<\/h3>\n\n\n\n<p>You can define the structure of your custom element via the <code>get_nestable_children<\/code> function. It expects to return an array of element definitions. <\/p>\n\n\n\n<p>This is best illustrated by having a look at the Nestable Slider elements&#8217; <code>get_nestable_children<\/code> function:<\/p>\n\n\n\n<pre class=\"wp-block-code prettyprint\"><code>public function get_nestable_children() {\n  return &#91;\n      &#91;\n        'name'     => 'block',\n        'label'    => esc_html__( 'Slide', 'bricks' ) . ' {item_index}',\n        'settings' => &#91;\n          '_hidden' => &#91;\n            '_cssClasses' => 'hidden-class', \/\/ CSS class not visible in builder UI\n          ],\n        ],\n        'children' => &#91;\n            &#91;\n              'name'     => 'heading',\n              'settings' => &#91;\n                'text' => esc_html__( 'Slide', 'bricks' ) . ' {item_index}',\n              ],\n            ],\n            &#91;\n              'name'     => 'button',\n              'settings' => &#91;\n                'text'  => esc_html__( 'I am a button', 'bricks' ),\n                'size'  => 'lg',\n                'style' => 'primary',\n              ],\n            ],\n          ],\n      ],\n  ];\n}<\/code><\/pre>\n\n\n\n<p>The code above adds a &#8220;Slide&#8221; block inside the nestable slider, which then contains a &#8220;Heading&#8221; &amp; &#8220;Button&#8221; element. <\/p>\n\n\n\n<p>The <code>children<\/code> property, if set, accepts an array of further nested elements. Specify the <code>settings<\/code> array to populate individual elements inside your nestable element as needed.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\" id=\"php\">Nestable Render Function (PHP)<\/h3>\n\n\n\n<p>The only new function you need to add to your PHP <code>render()<\/code> function is called <code>render_children<\/code> and it requires the element instance <code>$this<\/code> to be passed as the first parameter:<\/p>\n\n\n\n<pre class=\"wp-block-code prettyprint\"><code>public function render() {\n  $output = \"&lt;div {$this-&gt;render_attributes( '_root' )}&gt;\";\n\n  \/\/ Render children elements (= individual items)\n  $output .= Frontend::render_children( $this );\n\n  $output .= '&lt;\/div&gt;';\n\n  echo $output;\n}<\/code><\/pre>\n\n\n\n<h3 class=\"wp-block-heading\" id=\"x-template\">Nestable Render Function (Vue x-template)<\/h3>\n\n\n\n<p>To render elements inside your nestable element in your custom x-template, simply add the <code>&lt;bricks-element-children&gt;<\/code> component plus <code>element<\/code> props as shown in the following code snippet:<\/p>\n\n\n\n<pre class=\"wp-block-code prettyprint\"><code>public function render_builder() {\n  &lt;script type=\"text\/x-template\" id=\"tmpl-bricks-element-custom-nestable\"&gt;\n    &lt;component :is=\"tag\"&gt;\n      &lt;h2&gt;Title before nestable children&lt;\/h2&gt;\n      &lt;bricks-element-children :element=\"element\"\/&gt;\n      &lt;p&gt;Text node after nestable children&lt;\/p&gt;\n    &lt;\/component&gt;\n  &lt;\/script&gt;\n}<\/code><\/pre>\n\n\n\n<h3 class=\"wp-block-heading\">Nestable Element Items (in panel)<\/h3>\n\n\n\n<p>If your nestable element structure is based on items on the same level (such as our Accordion above), then you can add a Repeater (see builder panel in screenshot above) by adding a <code>repeater<\/code> control with the <code>items<\/code> property set to <code>children<\/code>:<\/p>\n\n\n\n<pre class=\"wp-block-code prettyprint\"><code>public function set_controls() {\n  \/\/ Array of nestable element.children (@since 1.5)\n  $this-&gt;controls&#91;'_children'] = &#91;\n    'type'          =&gt; 'repeater',\n    'titleProperty' =&gt; 'label',\n    'items'         =&gt; 'children',\n  ];\n];<\/code><\/pre>\n\n\n\n<p class=\"callout-blue\">If you are start using and\/or experimenting with the new Nestable Elements API for your custom elements, <a rel=\"noreferrer noopener\" href=\"https:\/\/bricksbuilder.io\/contact\/\" data-type=\"URL\" data-id=\"https:\/\/bricksbuilder.io\/contact\/\" target=\"_blank\">we&#8217;d love to hear your feedback<\/a>. Does this API miss any features, did you encounter any bugs?<\/p>\n","protected":false},"excerpt":{"rendered":"<p>Bricks 1.5 introduces Nestable Elements. Plus an API that allows you to programmatically define your own custom elements that can contain other elements. In exactly the structure you want. Prior to Bricks 1.5 every element in Bricks was &#8220;flat&#8221;. Meaning even though an element contained a deep HTML structure (like the Slider, etc.) you couldn&#8217;t [&hellip;]<\/p>\n","protected":false},"author":1,"featured_media":0,"menu_order":82,"template":"","format":"standard","meta":{"footnotes":""},"_links":{"self":[{"href":"https:\/\/academy.bricksbuilder.io\/api\/wp\/v2\/bricks_article\/2644"}],"collection":[{"href":"https:\/\/academy.bricksbuilder.io\/api\/wp\/v2\/bricks_article"}],"about":[{"href":"https:\/\/academy.bricksbuilder.io\/api\/wp\/v2\/types\/bricks_article"}],"author":[{"embeddable":true,"href":"https:\/\/academy.bricksbuilder.io\/api\/wp\/v2\/users\/1"}],"version-history":[{"count":52,"href":"https:\/\/academy.bricksbuilder.io\/api\/wp\/v2\/bricks_article\/2644\/revisions"}],"predecessor-version":[{"id":5129,"href":"https:\/\/academy.bricksbuilder.io\/api\/wp\/v2\/bricks_article\/2644\/revisions\/5129"}],"wp:attachment":[{"href":"https:\/\/academy.bricksbuilder.io\/api\/wp\/v2\/media?parent=2644"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}