Mags
Mags bieten einen sehr einfachen Weg, schnell und dynamisch Formulare zusammenzustellen. Mags kümmern sich sowohl um die Validierung als auch um die Darstellung. Dieses Konzept wird häufig für Konfigurationen von Erweiterungen verwendet.
MagCollection
Mags werden in einer n2n\dispatch\mag\MagCollection
zusammengefasst. Eine Mag entspricht einer Eigenschaft im Form Model. Ein Form Model, das Mags unterstützt, muss n2n\dispatch\mag\DispatchableMagCollection
implementieren. In den meisten Fällen reicht es, dafür das Form Model n2n\dispatch\mag\MagForm
zu nutzen, welchem du einfach eine MagCollection
übergeben kannst:
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 diesem Beispiel erzeugen wir eine MagCollection
und fügen ihr zwei Mags mit den Eigenschafts-Namen "foo" und "bar" hinzu. "foo" ist vom Typ string
und "bar" vom Typ boolean
. Als zweiten Parameter von StringMag
und BooleanMag
übergibst du das Label für die View. n2n stellt standardmässig folgende Mags zur Verfügung:
n2n\impl\web\dispatch\mag\model\
n2n\impl\web\dispatch\mag\model\BooleanMag
n2n\impl\web\dispatch\mag\model\EnumArrayMag
n2n\impl\web\dispatch\mag\model\EnumMag
n2n\impl\web\dispatch\mag\model\N2nLocaleMag
n2n\impl\web\dispatch\mag\model\ManagedFileMag
n2n\impl\web\dispatch\mag\model\MultiSelectMag
n2n\impl\web\dispatch\mag\model\NumericMag
n2n\impl\web\dispatch\mag\model\MagArrayMag
n2n\impl\web\dispatch\mag\model\MagCollectionArrayMag
n2n\impl\web\dispatch\mag\model\MagCollectionMag
n2n\impl\web\dispatch\mag\model\ClassNameMag
n2n\impl\web\dispatch\mag\model\SecretStringMag
n2n\impl\web\dispatch\mag\model\StaticMagCollectionArrayMag
n2n\impl\web\dispatch\mag\model\StringArrayMag
n2n\impl\web\dispatch\mag\model\StringMag
n2n\impl\web\dispatch\mag\model\UrlMag
Weitere Informationen kannst du der PHPDoc jener Klassen entnehmen.
Nutze MagCollection::writeAttributeValues()
, um die Eigenschaften mit Werten zu initialisieren. Nach erfolgreichem "Dispatch" kannst du mit MagCollection::readAttributeValues()
die Werte der Eigenschaften wieder auslesen.
Wie bereits erwähnt, kümmern sich Mags selbst um ihre Darstellung. Du musst sie in der View allerdings platzieren. Hierzu definierst du für jede Mag mit $formHtml->magOpen()
und $formHtml->magClose()
einen Bereich, in welchem du mit $formHtml->magLabel()
das Label und $formHtml->magField()
das Form-Element dieser Mag platzieren kannst:
<?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() ?>
Ähnlich wie bei $formHtml->meta()->arrayProps()
kannst du mit $formHtml->meta()->objectProps()
über alle Eigenschaften von Form Models iterieren:
<?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() ?>
Alternativ kannst du auch die View n2n\dispatch\mag\view\magForm.html
einbinden, die das Mag-Formular für dich darstellt.
<?php $formHtml->open($magForm) ?> <?php $view->import('\n2n\dispatch\mag\view\magForm.html') ?> <input type="submit" /> <?php $formHtml->close() ?>
Du kannst magForm.html
auch ein PropertyPath
zum darzustellenden MagForm
übergeben. Damit könntest du zum Beispiel das Form Model einer Objekt-Eigenschaft darstellen. Hättest du zum Beispiel eine Objekt-Eigenschaft config
, die mit einem MagForm
initialisiert wurde, könntest du magForm.html
folgendermassen einbinden:
<?php $view->import('\n2n\dispatch\mag\view\magForm.html', array('propertyPath' => $formHtml->meta()->createPropertyPath('config'))) ?>
Mags selbst erstellen
Für deine Mag musst du eine Klasse erstellen, die n2n\dispatch\mag\Mag
implementiert oder einfach von n2n\dispatch\mag\impl\MagAdapter
erbt. Weitere Informationen kannst du der PHPDoc entnehmen. Lass dich auch vom Source-Code von n2n\dispatch\mag\impl\StringMag
inspirieren.