Add-on Development: Variable pairs with parameters

Question

I can't seem to find any documentation or examples of how to give variable pairs parameters in EE add-ons. I have a module working like a charm. Inside the main module tagpair there's a variable pairs like this:

{exp:mod:method}

    <h1>{top_level_var}</h1>
    {var_pair}
        <p>{var_pair_variable}</p>
    {/var_pair}

{/exp:mod:method}

Boom, that's awesome. But sometimes I want to limit the output of the {var_pair} tag via params like this:

{exp:mod:method}

    <h1>{top_level_var}</h1>
    {var_pair limit="7" number="42"}
        <p>{var_pair_variable}</p>
    {/var_pair}

{/exp:mod:method}

What's the best way to accomplish this? Does EE natively support such params?

Answer 1

This is not natively supported in ExpressionEngine. The "official" was to do something similar to this would be to simply use additional module tags. Is there a reason you would not want to do that?

{exp:mod:method}

    <h1>{top_level_var}</h1>
    {exp:mod:var_pair limit="7" number="42"}
        <p>{var_pair_variable}</p>
    {/exp:mod:var_pair}

{/exp:mod:method}

You can use the session cache trick to keep track of shared values between the two module tags when doing this. Place this in your module's constructor:

$this->EE = &get_instance();
if(!isset($this->EE->session->cache[__CLASS__]))
{
    $this->EE->session->cache[__CLASS__] = array();
}
$this->cache = &$this->EE->session->cache[__CLASS__];

You can then use $this->cache as an array anywhere in your tags to keep track of shared data, such as the recordset initially loaded by the outer {exp:mod:method} module tag.

Answer 2

You can also take a look in the EE source code or a module like Playa to see how they are doing it...

Apart from having a separate adding a tag to your module, you can manually search and parse those tags yourself. If you check the sourcecode for the channel module, you can find the following snippet of code used for the categories tag:

if (strpos($this->EE->TMPL->tagdata, LD.'/categories'.RD) !== FALSE)
{
  if (preg_match_all("/".LD."categories(.*?)".RD."(.*?)".LD.'\/'.'categories'.RD."/s", $this->EE->TMPL->tagdata, $matches))
  {
    for ($j = 0; $j < count($matches[0]); $j++)
    {
      $cat_chunk[] = array($matches[2][$j], $this->EE->functions->assign_parameters($matches[1][$j]), $matches[0][$j]);
    }
  }
}

Instead of assigning the result to $cat_chunk you can do you own parsing and replacement of that tag.

This does however add a lot of extra code because you wouldn't be able to use the $this->EE->TMPL->parse_variables method anymore since you will have to parse everything manually (not just the var_pairs).

Something like this:

//  Parse single variables
foreach ($this->EE->TMPL->var_single as $key => $val)
{
  $value = isset($data[$key]) ? isset($data[$key]) : '';
  $tagdata = $this->EE->TMPL->swap_var_single($key, $data[$key], $tagdata);
}

//  Parse variable pairs
foreach ($this->EE->TMPL->var_pairs as $key => $val)
{
  //  parse categories
  if (strpos($key, 'your_var_pair') !== FALSE)
  {
    // do something with the tag pair
  }
}

In this case the $val variable should hold your custom parameters.

That being said... the question you should be asking: "Is it all worth the trouble?". Will people (or you) ever use those parameters, because it does add a lot of overhead in the code. There are other tags you will need to parse manually like {switch=''}, {count} and {total_results}.

My answer got a bit longer than I intended, but it IS a complex matter.

– Wouter