Purpose of the Seed¶
Agile UI relies on wide variety of objects. For example Button
relies on
Icon
object for its rendering. As a developer can create Icon object first,
then pass it to the button:
$icon = new Iron('book');
$button = new Button('Hello');
$button->icon = $icon;
or you can divert icon creation until later by using Array / String for Button::$icon
property:
$button = new Button('Hello');
$button->icon = 'book';
When you don’t provide an object - string/array value is called “Seed” and will be used to locate and load class dynamically just when it’s needed.
Seed has many advantages:
- more readable and shorter syntax
- easier concept for new developers and non-developers
- can be namespace-specific
- can improve performance - not all seeds are initialized
- recursive syntax with property and constructor argument injection
- allow App logic to further enhance mechanics
Growing Seed¶
To grow a seed you need a factory. Factory is a trait implemented in atk4/core and used by all ATK UI classes:
$object = Factory::factory($seed);
In most cases you don’t need to call factory yourself, methods which accept object/seed combinations will do it for you:
Button::addTo($app);
// app will create instance of class \Atk4\Ui\Button
Seed, Object and Render Tree¶
When calling View::add()
not only your seed becomes an object, but it is also added to
the render tree.
Seed Components¶
For more information about seeds, merging seeds, factories and namespaces, see https://agile-core.readthedocs.io/.
The most important points of a seed such as this one:
$seed = [Button::class, 'hello', 'class.big red' => true, 'icon' => ['book', 'red']];
are:
- Element with index 0 is name of the class mapped into namespace Atk4Ui (by default).
- Elements with numeric indexes ‘hello’ and ‘big red’ are passed to constructor of Button
- Elements with named arguments are assigned to properties after invocation of constructor
Alternative ways to use Seed¶
Some constructors may accept array as the first argument. It is also treated as a seed but without class (because class is already set):
$button = new Button(['hello', 'class.big red' => true, 'icon' => ['book', 'class.red' => true]]);
It is alternatively possible to pass object as index 0 of the seed. In this case constructor is already invoked, so passing numeric values is not possible, but you still can pass some property values:
$seed = [new Button('hello', 'class.big red' => true), 'icon' => ['book', 'class.red' => true]];
Additional cases¶
An individual object may add more ways to deal with seed. For example, when adding columns
to your Table you can specify seed for the decorator: Atk4\Ui\Table\Column
:
$table->addColumn('salary', [\Atk4\Ui\Table\Column\Money::class]);
// or
$table->addColumn('salary', [\Atk4\Ui\Table\Column\Money::class]);
// or
$table->addColumn('salary', new \Atk4\Ui\Table\Column\Money());
// or
$table->addColumn('salary', [new \Atk4\Ui\Table\Column\Money()]);
Note that addColumn uses default namespace of \Atk4\Ui\Table\Column when seeding objects. Some other methods that use seeds are: