Mags
Mags offer a very simple way to assemble forms quickly and dynamically. Mags take care of both the validation and the presentation. This concept is often used for configurations of extensions.
MagCollection
Mags are grouped in a n2n\dispatch\mag\MagCollection. A Mag corresponds to a property in the form model. A form model that supports Mags has to implement n2n\dispatch\mag\DispatchableMagCollection. In most cases it is sufficient to use the form model n2n\dispatch\mag\MagForm for this, to which you can simply pass a MagCollection:
class ExampleController extends ControllerAdapter {
public function index() {
$magCollection = new MagCollection();
$magCollection->addMag(new StringMag('foo', 'Foo'));
$magCollection->addMag(new BoolMag('bar', 'Bar'));
$magCollection->writeValues(array('foo' => 'default value', 'bar' => false));
$magForm = new MagForm($magCollection);
if ($this->dispatch($magForm)) {
var_dump($magCollection->readFormValues());
}
$this->forward('view\magForm.html', array('magForm' => $magForm));
}
}
In this example we create a MagCollection and add two Mags with the property names "foo" and "bar" to it. "foo" is of type string and "bar" of type boolean. As second parameter of StringMag and BooleanMag you pass the label for the view. n2n provides the following Mags by default (in the namespace n2n\impl\web\dispatch\mag\model):
n2n\impl\web\dispatch\mag\model\BooleanMagn2n\impl\web\dispatch\mag\model\EnumArrayMagn2n\impl\web\dispatch\mag\model\EnumMagn2n\impl\web\dispatch\mag\model\N2nLocaleMagn2n\impl\web\dispatch\mag\model\ManagedFileMagn2n\impl\web\dispatch\mag\model\MultiSelectMagn2n\impl\web\dispatch\mag\model\NumericMagn2n\impl\web\dispatch\mag\model\MagArrayMagn2n\impl\web\dispatch\mag\model\MagCollectionArrayMagn2n\impl\web\dispatch\mag\model\MagCollectionMagn2n\impl\web\dispatch\mag\model\ClassNameMagn2n\impl\web\dispatch\mag\model\SecretStringMagn2n\impl\web\dispatch\mag\model\StaticMagCollectionArrayMagn2n\impl\web\dispatch\mag\model\StringArrayMagn2n\impl\web\dispatch\mag\model\StringMagn2n\impl\web\dispatch\mag\model\UrlMag
Further information can be found in the PHPDoc of those classes.
Use MagCollection::writeAttributeValues() to initialize the properties with values. After a successful "dispatch" you can read the values of the properties again with MagCollection::readAttributeValues().
As already mentioned, Mags take care of their presentation themselves. However, you have to place them in the view. For this, you define for every Mag an area with $formHtml->magOpen() and $formHtml->magClose(), in which you can place the label of this Mag with $formHtml->magLabel() and the form element with $formHtml->magField():
<?php
use n2n\dispatch\mag\impl\MagForm;
$magForm = $view->getParam('magForm');
$view->assert($magForm instanceof MagForm);
?>
<?php $formHtml->open($magForm) ?>
<?php $formHtml->magOpen('div', 'foo') ?>
<?php $formHtml->magLabel() ?>
<div>
<?php $formHtml->magField() ?>
</div>
<?php $formHtml->magClose()?>
<?php $formHtml->magOpen('div', 'bar') ?>
<?php $formHtml->magLabel() ?>
<div>
<?php $formHtml->magField() ?>
</div>
<?php $formHtml->magClose()?>
<input type="submit" />
<?php $formHtml->close() ?>
Similar to $formHtml->meta()->arrayProps() you can iterate over all properties of form models with $formHtml->meta()->objectProps():
<?php $formHtml->open($magForm) ?>
<?php $formHtml->meta()->objectProps(null, function () use ($formHtml) { ?>
<?php $formHtml->magOpen('div') ?>
<?php $formHtml->magLabel() ?>
<div>
<?php $formHtml->magField() ?>
</div>
<?php $formHtml->magClose() ?>
<?php }) ?>
<input type="submit" />
<?php $formHtml->close() ?>
Alternatively you can also include the view n2n\dispatch\mag\view\magForm.html, which renders the Mag form for you.
<?php $formHtml->open($magForm) ?>
<?php $view->import('\n2n\dispatch\mag\view\magForm.html') ?>
<input type="submit" />
<?php $formHtml->close() ?>
You can also pass a PropertyPath to magForm.html that points to the MagForm to render. With this you could for example render the form model of an object property. If for example you had an object property config that was initialized with a MagForm, you could include magForm.html as follows:
<?php $view->import('\n2n\dispatch\mag\view\magForm.html',
array('propertyPath' => $formHtml->meta()->createPropertyPath('config'))) ?>
Creating Your Own Mags
For your Mag you have to create a class that implements n2n\dispatch\mag\Mag or simply inherits from n2n\dispatch\mag\impl\MagAdapter. Further information can be found in the PHPDoc. Also let yourself be inspired by the source code of n2n\dispatch\mag\impl\StringMag.