Mags

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.