I componenti Yahoo, Astra per Flex

Presentazione e primo uso di Astra per Flex, una serie di piccoli componenti dedicati a Flex da parte di Yahoo

Oltre ai componenti messi a disposizione di default da Flex, si possono trovare online alcune risorse aggiuntive, tra cui proprio dei componenti creati da software house o semplici utenti che vogliono mettere a disposizione di altri il loro lavoro. È il caso, ad esempio, dei componenti Yahoo Astra, una serie di piccoli componenti dedicati a Flex (esiste anche una versione di componenti Astra per Flash, ma differisce da quelli per Flex come contenuti).

Questi componenti sono stati rilasciati da Yahoo, il kit per Flex contiene precisamente i seguenti componenti:

  • AutoCompleteManager, per creare dei suggerimenti alla compilazione dei campi (come avviene sui browser più recenti);
  • ColorPlaneAndSliderPicker, per creare tavolozze da cui ricavare un colore;
  • ColorSliderPicker, per creare degli slider tramite cui è possibile impostare dei colori;
  • DropDownColorPicker, per creare un color picker riducibile (molto diffuso nei software);
  • IPV4AddressInput, per creare campi di testo in grado di controllare che sia stato inserito un indirizzo IP;
  • TimeInput, per far inserire una data come input all’utente;
  • TimeStepper, per creare dei campi di tipo numeric stepper in grado di agire su diverse cifre (come appunto l’orario).

Di questi componenti quello che può ritrovare più spesso riscontro pratico è probabilmente l’AutoCompleteManager, che andremo a trattare in questo articolo analizzandone l’utilizzo.

Tutti i componenti Astra usano sintassi e convenzioni simili o uguali ai componenti “classici” di Flex, per cui la curva d’apprendimento per chi già conosce un po’ Flex risulta nulla.

Download ed installazione dei componenti

Le prime operazioni da fare sono ovviamente il download e l’installazione dei componenti: è possibile scaricare dalla pagina di presentazione dei componenti.

Il file che scaricheremo è un archivio ZIP contenente le seguenti cartelle:

  • Build, da utilizzare nel Flex Builder per sfruttare i componenti Yahoo Astra;
  • Documentation, contenente la documentazione inerente i vari componenti;
  • Examples, che contiene alcuni esempi creati con i componenti Yahoo Astra;
  • Source, contenente i sorgenti Actionscript dei componenti.

C’è poi un file License.txt che riporta le condizioni d’uso di questi componenti; la licenza sotto cui sono rilasciati è la BSD.

Delle cartelle presenti nello ZIP quella che ci interessa al momento è Build, provvediamo quindi ad estrarla (il percorso in cui estrarla è a discrezione dell’utente); all’interno della cartella troveremo un file di tipo SWC, precisamente astra-flex.swc. Questo sarà il file che dovremo utilizzare per rendere attivi i componenti di Yahoo nel nostro progetto Flex.

Per prima cosa creiamo un nuovo progetto Flex, dopo di che abbiamo due possibilità: possiamo copiare il file SWC all’interno della cartella libs del nostro progetto (se abbiamo usato i percorsi di default sarà c:/Documents and Settings/{nome utente}/My Documents/Flex Builder 3/{nome_progetto}/libs), in alternativa scegliamo la voce Properties dal menu Project, dal menu a sinistra selezioniamo Flex Build Path e infine portiamoci sulla scheda Library Path. Notiamo sulla destra il pulsante Add SWC.

Figura 1. Scheda Library path con il pulsante Add SWC Screenshot delle opzioni

Premendo tale pulsante si aprirà un pannello dove dovremo inserire il percorso del file flex-astra.swc.

Figura 2. Inserimento del percorso Screenshot delle opzioni

A questo punto premiamo “OK”, quindi premiamo nuovamente “OK” sulla finestra delle opzioni. Attendiamo qualche istante in cui il Flex Builder aggiornerà le impostazioni, dopo di che i componenti saranno disponibili nel nostro progetto, potremo notarlo in modalità design nel pannello componenti (categoria Custom, dove appariranno ora anche i componenti Astra) oppure in modalità codice, infatti iniziando un tag con y il code hint ci suggerirà i comandi relativi ai componenti Yahoo Astra.

Figura 3. I componenti Yahoo! nel pannello Componenti Screenshot del pannello
Figura 4. I componenti Yahoo! inseribili via codice Screenshot del pannello

A questo punto vediamo come utilizzare l’AutoCompleteManager.

Cos’è l’AutoCompleteManager?

L’AutoCompleteManager, in pratica, è utile per simulare nelle proprie applicazioni Flex il comportamento abitualmente assunto dai form all’interno dei browser: quando compiliamo un campo, il dato rimane nella memoria del browser in modo che in future compilazioni per dei campi che abbiano quello stesso nome ci vengano proposte le alternative utilizzate in precedenza, così da velocizzare l’operazione di inserimento dei dati.

Gli aspetti principalmente interessanti dell’AutoCompleteManager sono la possibilità di decidere se condividere o meno le compilazioni eseguite in un’applicazione con le altre (ad esempio potremmo avere due applicazioni con degli input con lo stesso nome, entrambe con l’AutoCompleteManager, ma non volere che le compilazioni inserite nell’applicazione A vengano suggerite nell’applicazione B), la possibilità di impostare dopo quante lettere suggerire le compilazioni e la possibilità di salvare i dati automaticamente oppure su richiesta dell’utente.

Come usare l’AutoCompleteManager

La semplicità di utilizzo di questo componente è altissima, nonostante offra diverse opzioni e inserisca di fatto dei nuovi elementi all’interno di un form o di una serie di campi input, poiché utilizzerà un’apposita sezione per mostrare i suggerimenti che apparirà proprio sotto alla sezione che stiamo compilando, proprio come accade normalmente nelle pagine HTML.

Caratteristica molto interessante di questo componente è che non richiede l’utilizzo di un campo di testo apposito, per cui per inserirlo in un’applicazione già in corso d’opera non sarà necessario sostituire alcun tag, basterà aggiungere quello relativo all’autoCompleteManager e impostare i dovuti parametri.

Vediamo un esempio molto semplice di utilizzo, sfruttando solo dei campi di tipo TextInput. Il codice è molto semplice:

<?xml version=”1.0″ encoding=”utf-8″?>
<mx:Application xmlns:mx=”http://www.adobe.com/2006/mxml” layout=”absolute” xmlns:yahoo=”com.yahoo.astra.mx.managers.*” width=”300″ height=”300″>
  <yahoo:AutoCompleteManager
  id=”autoCompleteMgr”
  targets=”{[textInput1, textInput2, textInput3]}”
  shareData=”true” autoSave=”true” />
  
  <mx:Label x=”40″ y=”37″ text=”Nome”/>
  <mx:TextInput id=”textInput1″ left=”40″ top=”53″/>
  <mx:Label x=”40″ y=”103″ text=”Telefono”/>
  <mx:TextInput id=”textInput2″ left=”40″ top=”120″/>
  <mx:Label x=”40″ y=”170″ text=”Email”/>
  <mx:TextInput id=”textInput3″ left=”40″ top=”187″/>
</mx:Application>

Possiamo notare la dichiarazione nel namespace yahoo all’interno del tag Application e l’uso del tag <yahoo:AutoCompleteManager> per istanziare il componente.

Il resto, molto banalmente, sono i parametri del componente (li vedremo meglio a breve) e i tre campi di testo che utilizzeremo per testare il componente. Possiamo sperimentare l’AutoCompleteManager nel filmato che segue:

Uso dell’AutoCompleteManager con salvataggio automatico

Come abbiamo visto i dati in questo caso vengono salvati ogni volta che cambiamo campo di testo: questo perchè il parametro autoSave era impostato su true.

La proprietà target, come è facilmente intuibile, permette di specificare gli elementi per cui attivare i suggerimenti di compilazione: in questo caso abbiamo usato tre text input separati, ma potremmo rendere le cose più comode racchiudendo ad esempio i campi in un form e impostando poi quest’ultimo come target: automaticamente l’autoCompleteManager verrà applicato a tutti gli input presenti in quel form.

Vediamo allora questo secondo esempio, dove oltre a racchiudere gli input in un form impostiamo anche un salvataggio manuale e non più automatico dei suggerimenti per la compilazione.

<?xml version=”1.0″ encoding=”utf-8″?>
<mx:Application xmlns:mx=”http://www.adobe.com/2006/mxml” layout=”absolute” applicationComplete=”setUp(event)” xmlns:yahoo=”com.yahoo.astra.mx.managers.*”>
  <mx:Script>
    <![CDATA[
      import mx.events.FlexEvent;
      import mx.controls.Alert;
      // Imposta l’evento per il salvataggio dei dati
      public function setUp(event:FlexEvent):void{
        autoCompleteMgr.addEventListener(“entriesSaved”, onEntriesSaved);
      }
      // Richiama il metodo per il salvataggio dei dati
      public function salva():void{
        autoCompleteMgr.saveEntries();
      }
      // Funzione richiamata una volta completato il salvataggio
      public function onEntriesSaved(event:Event):void{
        Alert.show(“Input salvati con successo”, “Form inviato correttamente”);
      }
    ]]>
  </mx:Script>
  <yahoo:AutoCompleteManager id=”autoCompleteMgr”
  target=”{form_dati}”
  />
  <mx:Form id=”form_dati” defaultButton=”{submitButton}” left=”20″ top=”20″>
    <mx:FormItem label=”Nome:”>
      <mx:TextInput id=”textInput1″ left=”26″ top=”56″/>
    </mx:FormItem>
    <mx:FormItem label=”Telefono:”>
      <mx:TextInput id=”textInput2″ left=”26″ top=”86″/>
    </mx:FormItem>
    <mx:FormItem label=”Email:”>
      <mx:TextInput id=”textInput3″ left=”26″ top=”116″/>
    </mx:FormItem>
    <mx:FormItem>
      <mx:Button id=”submitButton” x=”121″ y=”164″ label=”Salva” click=”salva()”/>
    </mx:FormItem>
  </mx:Form>
</mx:Application>

La parte racchiusa tra i tag <mx:Script> si occupa di impostare il salvataggio dei dati alla pressione del pulsante “Salva”: per prima cosa viene associato il listener per l’evento entriesSaved alla funzione onEntriesSaved, quindi impostiamo la funzione da eseguire alla pressione del pulsante salva e la funzione di risposta all’evento, che nel nostro caso mostrerà semplicemente un Alert informando l’utente dell’avvenuto salvataggio dei dati.

Notiamo che in questo caso per l’autoCompleteManager abbiamo specificato solo i parametri id (usato per assegnare il listener) e target (impostato sull’intero form, che ha appunto identificativo form_dati.

La capacità del componente di ricavare automaticamente i campi all’interno di un contenitore facilita molto la stesura del codice, specialmente per quei form composti da molti campi e per cui associare singolarmente ogni textInput all’autoCompleteManager potrebbe richiedere diverso tempo.

Uso dell’AutoCompleteManager con salvataggio manuale

Finora abbiamo utilizzato come suggerimenti dei dati inseriti dall’utente, ma è anche possibile impostare una lista di dati predefiniti impostati in formato XML. Il seguente esempio utilizza come sorgente dei dati la lista di alcuni tra i principali aeroporti mondiali e fornisce i suggerimenti in base ad essa, inoltre i suggerimenti appaiono solo quando l’utente ha inserito almeno 3 lettere.

Uso dell’AutoCompleteManager con una fonte di dati predefinita

Il codice dell’esempio appena visto è il seguente:

<?xml version=”1.0″ encoding=”utf-8″?>
<mx:Application xmlns:mx=”http://www.adobe.com/2006/mxml” layout=”absolute” xmlns:yahoo=”com.yahoo.astra.mx.managers.*” width=”300″ height=”200″>
  <mx:Script>
    <![CDATA[
      private function airportFilterFunction(element:*, text:String):Boolean{
        var regExp:RegExp = new RegExp(text,autoCompleteMgr.caseSensitive?””:”i”);
        
        var b:Boolean = regExp.test(element.city.toString()) ||
        regExp.test(element.name.toString()) ||
        regExp.test(element.code.toString());
        
        return b;
      }
    ]]>
  </mx:Script>
  <yahoos:AutoCompleteManager
  id=”autoCompleteMgr”
  target=”{textInput1}”
  dataProvider=”{airports.airport}”
  labelField=”name”
  filterFunction=”{airportFilterFunction}”
  minCharsForCompletion=”3″ />
  <mx:XML id=”airports”>
    <airports>
      <airport>
        <city>Atlanta</city>
        <name>Hartsfield-Jackson Atlanta Int’l</name>
        <code>ATL</code>
        <country>USA</country>
        </airport><airport>
        <city>Chicago</city>
        <name>Chicago O’Hare International</name>
        <code>ORD</code>
        <country>USA</country>
      </airport>
      ….
    </airports>
  </mx:XML>
  <mx:Label x=”26.5″ y=”51″ text=”Try an airport or airport code:” fontWeight=”bold”/>
  <mx:Label x=”26.5″ y=”68″ text=”example: "ORD", "Chicago", or "O’Hare"” fontWeight=”normal” fontStyle=”italic”/>
  <mx:TextInput id=”textInput1″ left=”26.5″ top=”94″ width=”247″/>
</mx:Application>

Da notare in particolare l’uso dei parametri dataProvider (impostato sulla lista XML degli aeroporti) e filterFunction (impostato sulla funzione che tramite espressioni regolari controlla la corrispondenza tra gli aeroporti presenti e le lettere inserite dall’utente), oltre all’uso del parametro minCharsForCompletion impostato su 3 che fa sì che i suggerimenti appaiano all’utente solo nel caso abbia digitato almeno tre caratteri.

Ovviamente la lista degli aeroporti che abbiamo specificato come XML nel codice potrebbe essere passata da un file esterno.

Parametri disponibili per il componente

Ora che abbiamo visto come sia semplice impostare il componente AutoCompleteManager e quali siano i suoi principali metodi di utilizzo, vediamo qual è la lista completa dei parametri utilizzabili e il relativo utilizzo:

  • id: specifica l’identificativo del componente, utile per interfacciarlo con altri elementi o per assegnargli degli eventi;
  • autoSave (true o false): specifica se salvare automaticamente i dati inseriti dall’utente (quando il campo di testo interessato perde il focus) o manualmente (richiamando l’evento saveEntries);
  • caseSensitive (true o false): stabilisce se differenziare i suggerimenti in base alle maiuscole/minuscole (case sensitive) o no (case insensitive);
  • dataProvider: specifica l’eventuale lista da utilizzare come sorgente per i suggerimenti da offrire;
  • enabled (true o false): abilita o disabilita il componente; se il componente è disabilitato i suggerimenti non verranno mostrati e nessun nuovo input sarà aggiunto ad essi;
  • filterFunction: imposta la funzione da utilizzare per stabilire se mostrare o meno un suggerimento del DataProvider;
  • loopSelection (true o false): specifica se l’utente, navigando tra i suggerimenti con le freccie da tastiera, può passare in loop dal primo all’ultimo suggerimento (o viceversa);
  • maxRowCount (numerico): specifica il numero massimo di righe di altezza del settore dei suggerimenti;
  • minCharsForCompletion (numerico): specifica il numero minimo di caratteri che l’utente deve inserire per vedere i suggerimenti;
  • minDiskSpace (numerico): lo spazio minimo da dedicare al salvataggio dei suggerimenti;
  • popUpEnabled (true o false): specifica se mostrare la lista dei suggerimenti sotto al campo di testo oppure no;
  • shareData (true o false): specifica se condividere i suggerimenti tra le varie applicazioni;
  • sharedObjectPath (stringa): permette di impostare il nome dello sharedObject da usare per salvare i suggerimenti;
  • target: specifica il campo o contenitore per cui rendere attivo il componente;
  • targets: specifica i campi o contenitori per cui rendere attivo il componente;
  • wordWrap (true o false): specifica se i suggerimenti più lunghi dello spazio disponibile debbano andare a capo o essere tagliati.

È possibile usare il metodo removeAll() per ripulire completamente lo sharedObject contenente i suggerimenti, mentre per salvare i dati abbiamo già visto il metodo saveEntries().

Il componente prevede anche alcuni eventi:

  • open: si verifica quando il box con i suggerimenti viene aperto;
  • close: si verifica quando il box con i suggerimenti viene chiuso;
  • entriesSaved: si verifica quando i dati vengono salvati con successo;
  • change: si verifica quando viene selezionato un suggerimento.

In concluione, si tratta di un componente che seppur piuttosto “semplice” a livello visivo per l’utente finale racchiude un discreto numero di potenzialità: la sua facilità di utilizzo e la semplice implementazione anche in applicazioni pre-esistenti rendono questo componente decisamente interessante per offrire ai propri utenti suggerimenti durante la compilazione di form.