hanakin wrote: ↑
Wed Feb 01, 2017 11:35 am
can you please elaborate what/why and maybe provide examples for those in the community on exactly this is doing in plain english as a lot of our community are not programers but more board admins/theme authors. May help get more inputs on the benefits to them.
Sure. And the answer is easy: this provides NOTHING to board admins and theme/style developers. They will not notice any change whatsoever.
The target of these changes are others: developers, both team members and extension writers.
Advantages for these groups:
- Better long term supportability: as code is not duplicate across the different methods, it is easier to maintain and changes will be applied consistently (one change "fixes" all the methods in the class at once; in general, no need to replicate the change in multiple places in the file)
- Consistency: without this change, different methods in the template class support different "blockname" specifications; with the change, ALL share the same block naming convention
- Added functionality: besides "blockname" (string), it is possible to select blocks by "block selector" (array) that allows far more complex possibilities such as key matching at multiple levels
- Added functionality: extra operations on blocks, such as multi-insertion (insert several blocks NOT at the end of an existing block), deletion of specific sub-blocks (not complete blocks)
- Added functionality: variable retrieval, both at root level and at block level
And more... And I am open to suggestions and "audience requests"
Of course, this is 100% backwards compatible: all interfaces that used to work, continue working in exactly the same way. But they also accept more possibilities now. And there are new methods, or new options to existing methods.
Some examples for comparison (old vs new):
Code: Select all
// Simple assign_block_vars(_array): Works now, NO changes in new implementation
// Complex assign_block_vars(_array), specifying intermediate block: Does not work now, works in new implementation
// Simple AND complex alter_block_array insertion (single block): works on both implementations
$template->alter_block_array("outer.inner", $vars, true, 'insert');
// Simple AND complex alter_block_array change: works on both implementations
$template->alter_block_array("outer.inner", $vars, 2, 'change');
// Using search key to find the LAST block (insert or change) in alter_block_array: Works on both implementations
$template->alter_block_array("outer.inner", $vars, array('NAME' => $val), 'change');
// Simple destroy_block_vars: Works now, no changes in new implementation
// Complex destroy_block_vars: Does not work now, works in new implementation
Some examples of new functionality:
Code: Select all
// Retrieve var
$val = $template->retrieve_var('VARNAME');
// Retrieve block vars
$result = $template->retrieve_block_vars("outer.inner", array('VAR1', 'VAR2', 'NONEXISTENT'));
// $result = array('VAR1' => $val1, 'VAR2' => $val2, 'NONEXISTENT' => null);
// Block index searching at last level
$index = $template->find_key_index("outer.inner", array('S_ROW_INDEX' => 1)); // $index === 1
// PR submitted for current template implementation
// otherwise, cannot use "outer.inner": how would you know the value of '2'?
// Ideally, with new implementation, this would not be needed any longer
// Multi-level block selection in ALL calls (assign_, destroy_, retrieve_block_vars, alter_block_array...)
$template->assign_block_vars(array('outer' => true, 'middle' => array('NAME', 'myname'), 'inner' => 2), $vars);
// Multi-insertion with assign_block_vars_array and alter_block_array
$template->assign_block_vars_array(array('outer' => true, 'inner' => false), $block_vars_array);
// Inserts all blocks at the beginning of inner
// Selectively deleting with destroy_block_vars and alter_block_array
$template->alter_block_array(array('outer' => 1, 'inner' => null), array(), array('NAME' => 'to delete'), 'delete');
// Vararray is ignored, and key in parameter list takes precedence over last block selector key, to keep BC
// Ideally, with new implementation, this should not be used, better use the block selector array
Surely I am forgetting something... If you are interested, just ask.