Former, un potente form builder per Laravel – Seconda Parte

Di
FrancescoMalatesta
-
0
718

Anatomia di Former

Lo so, ti occorre un pò di pazienza per imparare tutte queste classi. Un buon modo per iniziare può essere quello di elencare specificando di cosa si occupano:

  • Former: è la classe principale e si occupa delle configurazioni e delle interazioni tra le varie componenti di un form
  • FormerServiceProvider: è il Service Provider per Laravel 4
  • Helpers: un set di helpers statici a supporto delle varie librerie
  • Dispatch: intercetta la chiamata che viene fatta alla Former facade rimandandola alla classe di competenza
  • LiveValidation: gestisce la validazione dei campi e la traduzione delle regole negli attributi
  • Populator: è un contenitore di valori che Former sfrutta per fare il get/set degli stessi
  • Traits:
  • Checkable: metodi e proprietà relativi a radiobutton e checkbox
  • Field: metodi e proprietà relativi ai campi
  • FormerObject: oggetto che estende le caratteristiche di cui sopra, gestisce attributi dinamici

  • Framework: metodi e proprietà comuni ai vari framework

  • Interfaces: metodi required dei vari framework
  • FieldInterface
  • FrameworkInterface
  • Framework : queste classi generano il corretto markup in base al framework in uso
  • Nude
  • TwitterBootstrap
  • ZurbFoundation
  • Form: le seguenti classi gestiscono il markup di una form
  • Actions: gestisce le azioni dei pulsanti submit
  • Elements: gestisce i vari elementi del form che non sono azioni (legende, ecc..)
  • Form: gestisce l’apertura e la chiusura dei form e altri metodi correlati
  • Group: si occupa del wrap e dello stato dei campi, del recupero degli errori e altro
  • Fields: una serie di classi ognuna delle quali gestisce un tipo di campo
  • Button
  • Checkbox
  • File
  • Hidden
  • Input
  • Radio
  • Select
  • Textarea

  • Uneditable

  • Facades : Alcuni entry points che facilitano l’esperienza attraverso i vari ambiaenti

  • Agnostic : la facade di base usata da Former al di fuori di ogni framework
  • FormerBuilder :Metodi comuni e blocchi da usare per tutte le facade
  • Illuminate : la facade di Laravel 4, aggancia Former ad alcuni componenti (localizzazione etc)
    LaravelThree : la facade di Laravel 3, aggancia Former ad alcuni componenti (localizzazione etc)
    Legacy : Un set di A set of classi redirector che unificano l’interfaccia tra Laravel 3 e 4
  • Config
  • Redirector
  • Session
  • Translator

Descrizione dei metodi

FormerFormer
E’ la classe principale e costituisce la tua interfaccia per tutto in Former. Chiaramente Former ti da la possibilità di interagire con le sue sottoclassi e quindi non solo puoi usare i suoi metodi ma anche quelli delle sottoclassi.

Option

E’ un set di opzioni utili a modificare il comportamento di Former

Former::config(‘translate_from’, [string]) (‘validation.attributes’)

Di default, Former tenta di tradurre labels, legend e help text. Prima effettua un tentativo di traduzione delle stringhe in automatico poi controlla che il testo sia presente da un’altra parte. Puoi impostare questa variabile che di default è settata a 'validation.attributes.mykey'.

Former::config(‘required_class’, [string]) (‘required’)

Una classe da aggiungere ai campi impostati come obbligatori

Former::config(‘default_form_type’, [horizontal|vertical|inline|search]) (‘horizontal’)

Di default quando chiami Former::open, una fallback form type viene assegnata al form – dice di che tipo è il form. Può essere uno dei valori o null se non vuoi usare le classi di Bootrap per i form.

Former::config(‘fetch_errors’, [boolean]) (true)

Ogni volta che chiamo il metodo open, se è settato a true, Former controllerà nell’array Session la presenza dell’oggetto Message che il metodo ->with_errors() della classe Redirect avrebbe dovuto creare. Ciò significa che se chiami Redirect::to()->with_errors() quando la validazione fallisce, Former assocerà automaticamente gli errori visualizzandoli accanto ai campi corrispondenti senza dover scrivere ulteriore codice.

Former::config(‘automatic_label’, [boolean]) (true)

Permette all’utente di attivare o meno le label automatiche. Quando è attivo, se crei un campo di nome foo senza specificare la label, Former assumerà che foo sia la label per quel campo. In sostanza Former tenterà di tradurla e di usarla come label. Se il campo non è attivo nessuna label verrà assegnata al campo.

Former::config(‘live_validation’, [boolean]) (true)

In questo caso Former cercherà di usare le regole del Validator di Laravel come attributi con l’opzione live_validation.

Former::config(‘push_checkboxes’, [boolean]) (true)

In questo caso i checkboxes devono essere sempre presenti nei dati in POST: sia se checked o no.

Helpers

Former::populate([array|Eloquent])

Popola i campi con un array di valori o con un oggetto Eloquent

Former::withErrors([Validator])

Dopo il fallimento di una validazione Former effettua il fetch della variabile $errors dalla Session e imposta come non corretti i campi corrispondenti visualizzando l’errore. Se ti trovi all’interno del controller puoi passare l’oggetto $validator a Former per ottenere lo stesso comportamento.

Former::withRules([array])

Consente di passare una serie di regole Laravel a Former, provando ad applicarle su attributi HTML come pattern, maxlength, ecc..

Former::framework([bootstrap|zurb|null])

Seleziona il tipo di framework CSS Former deve usare per la sua sintassi dandoti più o meno accesso ai metodi disponibili: ad esempio non puoi usare il metodo Bootstrap ->blockHelp se stai usando Zurb, ecc…

$error = Former::getErrors([string])

E’ l’equivalente di $error = isset($errors) ? $errors->first('field') : null.

Form builders

Former::legend([string])

Apre un tag Bootstrap di tipo `

` nel form – la stringa passata potrebbe essere un indice di traduzione e Former tenterà di tradurla.

Former::open()

Il metodo `open` è praticamente identico a quello di Laravel e per questo puoi controllare nella documentazione di Laravel. In aggiunta supporta dei magic methods per la retrocompatibilità:

Former::horizontal_open()
Former::secure_open()
Former::open_for_files()
Former::secure_vertical_open_for_files()

Puoi disporli a tuo piacimento poiché il loro comportamento è indipendente (non fare cose come `secure_files_open_for_vertical` poiché non avrebbe alcun senso)

Former::close()

Semplicemente stampa il tag di chiusura del form: `

`

Former::actions([string, …])

Crea un tag `

` per fare un wrap dei tuoi buttons (submit, back, reset, ecc…). Per fare l’output di più buttons non devi far altro che specificare più argomenti

// Button class from Bootstrapper
Former::actions( Button::submit(‘Submit’), Button::reset(‘Reset’) )

**Field builders**

La classe che userai per i due terzi del tuo tempo:

Former::[classes]_[field]

Questo metodo effettuerà un’analisi ogni volta che chiami un metodo sconosciuto e tenterà di creare un campo con esso. Lo decompone come `[classes]_[field]` o solo come `[field]`. Puoi chiamare tutte le classi Bootstrap che operano sui campi da span1 a span12 e da mini a xxlarge.

**Form/Field**

Questa classe è quella che entra in azione quando crei un campo. Il metodo sotto sarà accessibile solo dopo la creazione di un campo. Ecco un esempio per chiarire:

// Qui usi Former
Former::populate($project)
// Qui usi la classe Field in Former
Former::text(‘foo’)

Una classe smette di essere un campo quando quel campo viene stampato a video. Ciò significa che puoi fare questo:

$textField = Former::text(‘foo’);
$textField->class(‘myclass’)

Ma non questo:

echo Former::text(‘foo’)
Former::class(‘myclass’)

Perché i campi sono come piccoli uccelli e una volta che volano via non puoi più occuparti di loro.

**Interazione con gli attributi**

Former::text(‘foo’)->addClass([string])

Aggiunge una classe al campo corrente senza sovrascriverla diversamente da `->class()` che sovrascrive ogni attributo esistente – come ogni attributo setter.

Former::text(‘foo’)->forceValue([string])

Setta il valore del campo. Sarà sovrascritto dal dato in POST ma sovrascriverà chiamate da `Former::populate`.

Former::text(‘foo’)->value([string])

Setta il valore degli attributi. Gli attributi che contendono trattini verranno sostituiti da underscore. Quindi dovrai chiamare `data_foo(‘bar’)` per avere `data-foo=”bar”`.

Former::text(‘text’)->setAttribute([string], [string])

Puoi usarla come fallback per i magic method se vuoi impostare un attributo con un underscore

Former::text(‘foo’)->setAttributes([associative array])

Ti permette di fare un setting massivo di coppie di attributi usando un array. Di seguito degli esempi per fare la stessa cosa:

Former::text(‘foo’)->class(‘foo’)->foo(‘bar’)
Former::text(‘foo’)->setAttributes(array( ‘class’ => ‘foo’, ‘foo’ => ‘bar’ ))

Il secondo non è il metodo più pulito ma è utile se vuoi impostare lo stesso attributo per un gruppo di campi creando un array con gli attributi.

Former::text(‘foo’)->label([string])

Imposta l’etichetta di un campo come stringa. Se stai usando Bootstrap questo ha un significato specifico in quanto all’etichetta creata verrà assegnata la classe control-label in automatico.

Former::text(‘foo’)->addGroupClass(‘bar’)

Aggiunge una classe specifica al control-group di livello superiore

**Helpers**

$textField = Former::text(‘foo’)->require()
$textField = $textField->isRequired() // Ritorna “true”

Controlla se un campo è stato impostato come required.

**FormerCheckable**

Checkable è un subset di Field e quindi ogni metodo disponibile per Field sarà disponibile anche per Checkable che in più offre un paio di metodi relativi a radio button e checkbox.

Former::radios(‘foo’)->inline()
Former::checkboxes(‘foo’)->stacked()

Imposta i radio button e/o checkbox in line oppure in verticale (stacked).

Former::checkbox(‘foo’)->text(‘bar’)

Se vuoi mostrare solo un checkbox/radio con il relativo testo

Former::checkbox(‘foo’)->check()
Former::radio(‘foo’)->check()

Former::checkboxes(‘foo’)->checkboxes(‘foo’, ‘bar’)->check(‘foo_0’)

Former::radios(‘foo’)->checkboxes(‘foo’, ‘bar’)->check(0)

Il metodo check ti consente di verificare un elemento singolo oppure un elemento in una lista di elementi. Per un singolo elemento puoi chiamare il metodo `chec()` senza argomenti mentre invece, quando lo chiami per un elemento all’interno di un gruppo, dovrai specificare nell’argomento di quale elemento si tratta. Il comportamento sarà diverso tra radio e checkbox. Il perché è semplice: i checkbox possono essere differenziati per il loro nome mentre i radio possono essere differenziati solo per il loro valore. Quindi per un checkbox dovrai specificare il nome mentre per un radio dovrai specificare il valore.

**FormerControlGroup**

Metodi ed Helper relativi al gruppo dei controlli di Bootstrap. Se imposti da subito l’opzione `$useBootstrap` a false, questa classe e i relativi metodi non saranno accessibili.

Former::text(‘foo’)->state([error|warning|info|success])

Imposta lo stato del gruppo di controlli ad una particolare classe Bootstrap.

Former::text(‘foo’)->inlineHelp([string])
Former::text(‘foo’)->blockHelp([string])

Aggiunge al campo un testo di help di tipo inline/block. Per un campo potrai chiamarli entrambi ma ognuno potrà essere chiamato una sola volta: se chiami due volte `inlineHelp`, l’ultima chiamata sovrascriverà la precedente.

Former::text(‘foo’)->append([string, …])
Former::text(‘foo’)->prepend([string, …])

Antepone al campo corrente un elemento icons/text/buttons. Queste funzioni usano `func_get_args()` e quindi puoi ad esempio fare questo:

Former::text(‘foo’)->prepend(‘@’, ‘$’)

**FormerFieldsInput**

Tutte le classi relative agli input-type.

Former::text(‘foo’)->useDatalist([array])
Former::text(‘foo’)->useDatalist([Query], [string], [string (id)])
Crea un tag `` e lo collega al campo in modo da creare un mix select/text.

**FormerFieldsSelect**

Tutte le classi relative alle select. (select, multiselect, etc)

Former::select(‘foo’)->options([array], [selected])

Popola un campo `Molto semplicemente: selezioni il nome di un cliente e avrai come valore il suo ID. Il secondo parametro serve a preselezionare un elemento: se nell’esempio precedente avessimo aggiunto `->options($clients, 3)` avremmo ottenuto come preselezionato ‘Clémence’.

Former::select(‘foo’)->select(3)

Alias per il metodo `->value()`, seleziona un option

Former::select(‘foo’)->fromQuery([array], [string], [string (id)])

Popola una `

ARTICOLI CORRELATIALTRO DALL'AUTORE