CiviCRM Community Forums (archive)

hey rajan

overall a good approach and we need to figure out how to allow people to add content w/o modifying template files. So a good step forward

there is a slight issue with this patch for form elements, since u still need beginHookFormElements etc (since the form is created within body.tpl)

ideally would be great if we can figure out how to inject elements in various areas of the form programmatically. I do think that we should look at Drupal 7's render api and formalize the interface between smarty and our php code

lobo

Hi Xavier,

Yes, most the time it will be really helpful to avoid overriding of template files!

Do you have any thoughts regarding

ideally would be great if we can figure out how to inject elements in various areas of the form programmatically

( Like drupal alter hooks allow us to inject element any where within a form.. )

I think Rajan is getting at this: Drupal Form API uses one element graph to manage form data and to render markup; by contrast, Civicrms implementation of quickforms only uses the element graph to model data-- the heavy lifting for markup requires smarty (or clever jquery)  and it's all very tightly coupled. Drupal requires fewer steps to add a new form element.

Anyway, its a perfectly valid design tradeoff- - if someone could waive a wand and switch civi to a" component" model that satisfies this complaint, then other people would start complaining about how hard it is to understand the final markup.

Fwiw, I ilike the proposal of standardizing some flexible zones for smarty templates and making those zones programmatically manageable - - it sounds pretty cheap and its better than the status quo.

I've got a use-case right now that could benefit from this. (Specifically, I want to manipulate the content that appears at the bottom of civicrm/profile/view for certain profiles.) So I'm looking at this again...

Here are some code-snippets of what I'm thinking of:

== Internal Procederal API ==
CRM_Core_Regions::singleton()->addTemplate('form-footer', 'CRM/foo/bar.tpl');
CRM_Core_Regions::singleton()->addMarkup('form-footer', '<p>HELLO!</p>');
CRM_Core_Regions::singleton()->addCallback('form-footer', 'mymodule_render_something');

== External Procedural API ==
civicrm_api('region','add',array(
    'version' => 3,
    'type' => 'template',
    'file' => 'CRM/foo/bar.tpl',
));
   
== Hook API ==
/**
 * Alter content that is assigned to various regions -- run immediately
 * before final page-rendering
 */
function example_civicrm_regions(&$regions) {
  $regions['form-footer'][] = array(
    'type' => 'template',
    'file' => 'CRM/foo/bar.tpl',
  );
}   
 
== Smarty API ==
{* Render all content that belongs in a given region *}
{crmRegion name="form-footer"}

hey tim:

sounds like a good option and better than what we have currently. Maybe we should come up with a defined set of names that we can implement in vaious pages initially.

Some ideas:

page-header -- at top of page, immediatealy after the crm-container div
page-footer  -- at very bottom of page, above the civicrm footer

form-first / form-last / form-middle / form-third / form-two-thirds - first / last / middle  third / two-third element of form
form-LEGEND-first / form-LEGEND-last - if items are grouped together in a legend the same as above

lobo

yes, you should go ahead and implement it

the page/form header/footer can be added automatically to all pages. I think the non-automatic ones, we should do on demand / when needed

not sure how we'll do a double eval, since we'd want to embed in the template strings with smarty tokens in them that smarty will evaluate. I suspect we'll figure something out

lobo

So I implemented CRM_Core_Region (with Smarty tags and OO API) and held off on the hooks and civircm_api.  (There isn't a strong enough case; there's some inertia in civicrm_api framework; and we've got bigger fish to fry.) The diff file attached provides the implementation as well as a unit-test, example module, and example {crmRegion} inserts.  As one example, an extensible data table can be written as:

{crmRegion name="mytable"}
<table>
  <thead>
    <tr>
      {crmRegion name="mytable-header"}
        <th>Foo</th>
        <th>Bar</th>
        <th>Whiz</th>
      {/crmRegion}
    </tr>
  </thead>
  <tbody>
    {foreach var=row ...}
      <tr>
        {crmRegion name="mytable-row"}
          <td>{$row.foo}</td>
          <td>{$row.bar}</td>
          <td>{$row.whiz}</td>
        {/crmRegion}
      </tr>
    {/foreach}
  </tbody>
</table>
{/crmRegion}

To display an extra column, a module could say:

CRM_Core_Region::instance('mytable-header')->add(array(
  'markup' => '<th>Extra</th>',
));
CRM_Core_Region::instance('mytable-row')->add(array(
  'template' => 'string:<td>{$row.extra}</td>',
  // Note: This would normally be a file name; "string:" designates an inline template
));

This is an improvement. Note that you get some weak positioning abilities -- by setting a 'weight' property on the new snippet, you can put it before or after the main content and do some other tricks.  (See unit-tests for examples.) But Xavier's point still stands -- you can't position things arbitrarily, unless you (a) write complex, brittle regex or (b) write less-complex, somewhat-brittle jQuery for execution on the client.  To do something more robust, we would need a design in which each <tr>, each <th>, and each <td> could be queried/manipulated via PHP (something like DOM, Form API, or JSF).

What we've basically done here is introduce a rudimentary component model, but we've only "componentized" a few select bits of markup (i.e.  the {crmRegion}s), so we only get programmatic access to few select things. If we wanted, we could follow in the footsteps of many other platforms and slide down the slippery-slope towards a more thorough component model, e.g.

      <tr>
        {widget name="mytable-row"}
          {widget}<td>{$row.foo}</td>{/widget}
          {widget}<td>{$row.bar}</td>{/widget}
          {widget}<td>{$row.whiz}</td>{/widget}
        {/widget}
      </tr>

or equivalently

      {widget tag="tr" name="mytable-row"}
        {widget tag="td"}{$row.foo}{/widget}
        {widget tag="td"}{$row.bar}{/widget}
        {widget tag="td"}{$row.whiz}{/widget}
      {/widget}

or equivalently

      {tr name="mytable-row"}
        {td}{$row.foo}{/td}
        {td}{$row.bar}{/td}
        {td}{$row.whiz}{/td}
      {/tr}

Any instance of {crmRegion}/{widget}/{tr}/{td} would be a component that could be located, extended, or overriden via PHP -- building on the approach of {crmRegion}. This, of course, raises a few questions:

 * What does performance look like when half the tags get reprocessed on the off-chance that some component has opted to extend them? Aren't we going to add an extra 150ms to every page request?
 * What should all those component-types be? Do they have nuances (e.g. {tbody} behaves like {ol} but not like {p})?) Does it really make sense to invent a new list of component types when we've already got HTML/DOM?
 * How are we going to transition all the markup in all the .tpl files?
 * What does debugging look like when any tag is subject to runtime manipulation?
 * How does a developer know that his changes are upgrade-safe?

To address these questions, I'm thinking about a design based on "compile-time selectors". It works like this:

 1. The downstream developer makes a delcaration that he wants programmatic access to certain parts of a template, e.g. (pseudocode)
    function example_civicrm_injection() {
      return array(
        array(
          'file' => 'CRM/Contact/Form/Selector.tpl',
          'selector' => 'table td:nth-child(3)', // note: CSS selector expression
          'name' => 'my-injection-point',
          'append' => 'string:<td>{$row.extra}</td>',
        )
      );
    }
2. As part of the Smarty compilation process for Selector.tpl, we parse the .tpl file as an HTML document, search DOM for elements which match the selector, and convert them into extensible components. (http://simplehtmldom.sourceforge.net/ does a lot of the hard parsing/searching work)
 3. Optionally, we provide a validation utility which downstream developers can run as part of an upgrade/migration. This utility iterates through all the declared templates/selectors, compiles them, and reports invalid selectors. Unlike standard jQuery, this validation only requires compiling the .tpl files -- you don't need to go through the harder problem of producing final HTML (which requires loading sample data and running business logic). Bonus points can be awarded if the validation utility tracks compares the content of the selector in different revisions of CiviCRM.

In theory, this comes with a few caveats -- the developer has to declare the injection points somewhere separate from their PHP business logic, and it only works with .tpl files that are well-formed XML/HTML. However, it can be implemented generically; it provides a measure of maintainability/verifiability; and it makes the overhead proportionate to "#actual extension points" rather than "#potential extension points".

Anyway, that's an idea.