Deprecation of the section used as a container

Since the version 1.4-10, the usage of a section with a macro becomes the only supported way to use a section, as follow:

{section {id: "sectionId", macro: "mySectionContent"} /}

{macro mySectionContent}
  // Section content
{/macro}

Or, with some parameters:

{section {
  id: "sectionId",
  macro: {
    name: "mySectionContent",
    args: [1, 2, 3]
  }
} /}
{macro mySectionContent(a, b, c)}
  // Section content
{/macro}

A section used as a container has been deprecated, which means that soon, this kind of code will be no longer valid:

{section "sectionId"}
  // Deprecated usage
{/section}

At the same time, the parameters filterSection and outputSection in the $refresh method are deprecated as well in favor of the unique “section” usage:

this.$refresh({section: "sectionId"});

Behind the scene

The reason behind this is to provide a unique way to code a section and its related $refresh, to improve the global performances and to avoid some typical “hard to find” mistakes.

For example, let’s consider the following code:

{macro displayPage}
  {section "sectionId"}
    // section content
  {/section}
{/macro}

then we want to achieve a partial refresh, this way:

this.$refresh({filterSection: "sectionId", macro: "displaySection"});

in order to refresh only the section content. To perform this filter internally, the displaySection macro is completely re-run, and performs these tasks:

  • Before the macro execution, the output is turned off so that the corresponding markup is not generated,
  • Once the section is met, the output is turned on, and the markup is captured,
  • At the section end, the markup replace the old one for the dom section container,
  • The output is turned off again, and the macro continues till the end.

As we see in this example, a lot of code is run for nothing, just to generate the section content in the right context.

This example can also lead to weird and more complex issues, as all the functional code of the macro is run again. Let’s imagine that, in the displayPage macro, you have a global counter. Using $refresh with filterSection will automatically increase the counter, which is not necessarily the expected behavior !

If we now consider the new way:

{macro displayPage}
  {section {id: "sectionId", macro: "sectionContent"} /}
{/macro}
{macro sectionContent}
  // section content
{/macro}
this.$refresh({section: "sectionId"});

Here, as the section is used with a container, the corresponding macro is directly executed, the old markup being replaced by the new one without the need to run unnecessary code. And compared to the previous issue, a global counter will not be changed.

Another tricky example would be this one:

{macro main()}
  {section {
    bindRefreshTo : [{
      to : "myProperty",
      inside : data
    }]
  }}
    // Section content here
  {/section}

{/macro}

Trying to update the section by an aria.utils.Json.setValue fails, as the section has no id and the $refresh is not able to find where to output the section markup. The same example with a macro will work, as the binding is directly associated to the current section container and its macro.

Usual use cases

These are the usual “old” ways an existing application will have to change when upgrading to the new Aria templates release.

filterSection and outputSection replacements

// old way
this.$refresh({filterSection: "sectionId", macro:"macroContainingTheSection"});
// new way
this.$refresh({section: "sectionId"});

// old way
this.$refresh({outputSection: "sectionId"});
// new way
this.$refresh({section: "sectionId"});

Simple container

// old way
{macro displaySection()}
  {section {
    id : "sectionId"
  }}
    // Section content
  {/section}
{/macro}

// new way
{macro displaySection()}
  {section {
    id : "sectionId",
    macro: "sectionContent"
  }/}
{/macro}
{macro sectionContent()}
  // Section content
{/macro}

Sections used with the id string

// old way
{macro displaySection()}
  {section "sectionId"}
    // Section content
  {/section}
{/macro}

// new way
{macro displaySection()}
  {section {
    id : "sectionId",
    macro: "sectionContent"
  }/}
{/macro}
{macro sectionContent()}
  // Section content
{/macro}

Sections generated through a macro call

// old way
{macro displaySection()}
  {for var i = 0; i < 15; i++}
    {displayContent(i)}
  {/for}
{/macro}
{macro displayContent(i)}
  {section "section"+i}
    ${i}
  {/section}
{/macro}

// new way
{macro displaySection()}
  {for var i = 0; i < 15; i++}
    {section {
      id: "section"+i,
      macro: {
        name: displayContent,
        args: [i]
      }
    }/}
  {/for}
{/macro}
{macro displayContent(i)}
  ${i}
{/macro}

Impacted widgets

Some widgets use sections internally, and have the same drawbacks than the sections, when used as a container. So for the same reasons, this usage is deprecated too for them. It’s the case for the Tooltip, the Tabpanel and the Dialog. For these ones, the container style must be replaced by their “macro” equivalents.

 

2 responses on “Deprecation of the section used as a container

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>