Using the stack attribute follows the same procedures as any other attribute. "Stack Select" will appear as an attribute type. You can create an attribute to be used in your add-ons or themes.
Please note, no attributes are created when installing this package - only the attribute type is installed. At the moment, the attribute only allows a single stack to be selected.
It's important to note that these helper functions only allow the selection of a stack or stacks - sample code is giving to add to your save() function when using the multi_stack helper. However, it is up to you as an add-on developer to implement your own protections when working with the values returned by the helper. Please make note of the "preventing infinite loops" section below.
To use the stack select options in a block interface do the following:
Declare the helper:
In a form:
$sh = Loader::helper('form/stack_selector','stack_selector_attribute');
Or, in a controller (where $sh will be available in the view):
$this->set('sh',Loader::helper('form/stack_selector','stack_selector_attribute'));
To call the single stack select field:
In a form:
$sh->select_stack('my_stack',$my_stack); // $sh->select_stack($fieldName, $value)
Where my_stack matches a database column.
Nothing special needs to be done in your controller's save() function. The field will return 0 (zero) when empty, when a stack is selected, the collection ID of the stack will be saved to the database column that matches the field name.
To call the multiple stack select field:
In a form:
$sh->select_multi_stack('my_stack',$my_stack); // $sh->select_multi_stack($fieldName, $value)
Where my_stack matches a database column.
When using the select_multi_stack form helper, you must include the following in your controller's save() function:
$args[' my_stack '] = (empty($args[' my_stack '])) ? 0 : implode(',',$args[' my_stack ']);
The field will return 0 (zero) when no stacks are selected. When a stack or mutliple stacks are selected, the collection IDs of the stacks will be returned in a comma-separated list. Such as (116,126,201) - where each number represents the collection ID of a separate stack.
Note: It is possible to select the same stack multiple times in when using the multiple stack select field.
Preventing infinite loops
When working in views, it is important to test if the referenced stack(s) are going to create infinite loops - for example, if you display a stack in a stack, it's possible for someone to create an infinite loop (the stack is referencing itself).
You can prevent this by inserting the following before displaying stack contents: ($stack is a stack object using a value returned by the helper)
=================
// Make sure the referenced stack is actually valid.
if(is_object($stack)) {
// This compares the area ID of the stack being loaded to the Area ID of the block's collection object
if(Area::get($stack,STACKS_AREA_NAME)->getAreaID() != Area::get(Block::getByID($this->bID)->getBlockCollectionObject(),STACKS_AREA_NAME)->getAreaID()) {
// the referenced block is not referencing a stack that contains itself.
// You can perform your view functions. such as:
$this->set('stack',$stack->display());
}
}
=============================
For further details, please reference the controller of the "stack_randomizer" add-on.
----------------------------------------------------------------
Support: This is a fairly complex add-on, so if you need assistance getting a stack selection helper working feel free to get in touch via Private Message.
License: This package is under the Creative Commons Attribution-ShareAlike 3.0 Unported License. You are free to use this package on personal and commercial sites.
Attention developers: If you would like to include the helper functions in your own add-on you have two options - first you can make this package a requirement for yours (requiring it to be installed for yours to work) or you can duplicate the helpers and tools folders and include them in your own package. If you choose the latter, you'll need to modify the "tools/stack_search_selector.php" file to specify your package's handle. If you plan on submitting your add-on to the marketplace, please grant me a license for it.