Yahoo User Interface Blog (YUIBlog)

De "MakeNode" Widget Extension

In mijn vorige artikel, een recept voor een YUI 3 Toepassing , liet ik een manier om te gebruiken Y.substitute als een zeer basistemplate processor. Het idee nam het leven van daar, met suggesties van de mensen in het # Yui IRC kanaal, en ik maakte er een Widget-extensie die beschikbaar is op mijn site, genaamd MakeNode . MakeNode is niet een generieke template processor en het is niet bedoeld als een. Aan de andere kant is het nauw geïntegreerd met de YUI Widget stichting klasse, met inbegrip className en event helpers en internationalisering. In dit artikel zal ik de Spinner voorbeeld en aanpassen aan de richtlijnen van mijn vorige artikel te volgen en te MakeNode gebruiken. De gewijzigde Spinner component ( JS , CSS , sprites ) als een voorbeeld zijn beschikbaar vanaf mijn site. Links naar extra middelen kan gevonden worden op het einde van dit artikel.

Uitbreiding van uw component

Zodra MakeNode is geladen, moet u de module in uw bevatten YUI().use() verklaring onder de naam 'makenode' . Dan, uit te breiden uw widget, je lijst van het in het derde argument om Y.Base.create() , zoals deze:

  Y. Spinner = Y.Base.create (
      'Spinner',
      Y. Widget,
      [Y. MakeNode],
      {
         / / Instance leden ...
      },
      {
          / / Statische leden
      }
 ); 

U kunt MakeNode toevoegen langs een aantal geschikte extensies voor Widget, zoals WidgetParent, WidgetChild, WidgetStdMode, etc. MakeNode voegt twee beschermde methoden, _makeNode en _locateNodes, en het zal lezen uit verschillende statische eigenschappen, indien gevonden.

Alle leden van deze uitbreiding zijn, beschermd of prive, omdat ze zijn bedoeld om gebruikt te worden door de component ontwikkelaar en niet door de uitvoerder gebruik van deze componenten, die niet moet worden lastig gevallen met hen.

Het definiëren van de Template

Het eerste wat je normaal doen, is om de sjabloon te definiëren voor uw component. Voor de Spinner, zullen onze template zijn:

  _TEMPLATE: [
     '<input Type="text" title="{s input}" class="{c input}">',
     '<BUTTON Type="button" title="{s up}" class="{c up}"> </ knop>',
     '<BUTTON Type="button" title="{s down}" class="{c down}"> </ knop>'
 ]. Join ('\ n'), 

De standaard template zal meestal de naam _TEMPLATE en verklaarde langs de andere statische eigenschappen van de klasse, zoals ATTRS . MakeNode zal gebruik maken van dit sjabloon als geen ander is uitdrukkelijk voorzien. De sjabloon is gemaakt van eenvoudige HTML plus een reeks van tijdelijke aanduidingen tussen accolades, elk gemaakt van een enkel teken (de verwerking code) en gevolgd door een of meer argumenten. De tijdelijke aanduidingen en wat ze produceren zijn:

• {@ attributeName} configuratie attribuutwaarde

• {p propertyName} bijvoorbeeld waarde van de eigenschap

• {m methodName arg1 arg2 ….} return waarde van de gegeven methode. De verwerking code wordt gevolgd door de methode naam en een willekeurig aantal argumenten gescheiden door spaties. Strings moeten tussen dubbele aanhalingstekens. Getallen, Booleans en null zal worden omgezet van string naar de juiste data types

• {c classNameKey} CSS className gegenereerd uit de _CLASS_NAMES statische eigenschap

• {s key} koord uit de strings attribuut, met behulp van key als het sub-attribuut.

• {? other placeholder } Geeft de string checked als het resultaat van de verwerking van de rest van de tijdelijke aanduiding is waar.

• {} een andere waarde zullen worden behandeld, net als Y.substitute doet.

Bijvoorbeeld: {@ value} zal leiden tot een this.get('value') , terwijl {p value} vertaalt naar this['value'] .

De {m} tijdelijke aanduiding is een beetje complexer. Het eerste argument na het m verwerking code is de naam van de methode en de rest van de argumenten, alle van elkaar gescheiden door witruimte, die zullen worden doorgegeven aan de gegeven methode. Die argumenten kunnen getallen, null , true , false of strings tussen dubbele aanhalingstekens. MakeNode zullen ontleden ze en ze converteren naar hun juiste types, dus {m myMethod 123.45 true “this is a string”} zal resulteren in het roepen this.myMethod(123.45, true, “this is a string”) zodat de eerste twee argumenten worden omgezet in de juiste data types en de string kan spaties bevatten. Om een dubbel aanhalingsteken, gebruik \\" , de dubbele backslash is vereist omdat JavaScript zal een enkele interpreteren en ontdoet voordat het wordt MakeNode aan. Alleen dubbele aanhalingstekens zijn toegestaan, MakeNode maakt geen gebruik van eval() , zodat de parser is beperkt maar veilig is. Alles, maar getallen, null , Booleans en dubbele aanhalingstekens worden genegeerd.

De {?} tijdelijke aanduiding is handig te gebruiken met selectievakjes en keuzerondjes. Het zal produceren de string “checked” , afhankelijk van de waarheidswaarde van de verwerking instructie code die volgt. Zo <input type=”checkbox” {? m getLength}/> <input type=”checkbox” {? m getLength}/> zal een duidelijke checkbox te produceren als de getLength methode retourneert allesbehalve nul. {?} accepteert een van de andere tijdelijke aanduidingen, al is het alleen zin bij de eerste drie.

Voor de {c} tijdelijke aanduiding, moeten we beschikken over een _CLASS_NAMES woning gedefinieerd.

Verdere placeholders kunnen worden toegevoegd aan MakeNode door het toevoegen van hen in de _templateHandlers hash.

De _CLASS_NAMES woning

Samen met de ATTRS en _TEMPLATE statische attributen kunnen definiëren we een _CLASS_NAMES eigenschap die wijst naar een array van strings. Elk van deze strings zal gebruikt worden om een ​​className genereren. Zo _CLASS_NAMES: ['input'] zal de className produceren “yui3-spinner-input” . Die classNames worden opgeslagen in een instantie eigendom this._classNames . De {c input} in de template bovenstaande zal worden vervangen door “yui3-spinner-input” .

U kunt gebruik maken van de _CLASS_NAMES eigenschap een aantal classNames genereren, of je ze kunt gebruiken in de sjabloon of niet. U kunt nog steeds te bereiken die extra classNames van binnenuit this._classNames . De className wordt gegenereerd met behulp van de yui3 prefix, gevolgd door de waarde van het NAME statische eigenschap draaide kleine letters, en vervolgens de string die in _CLASS_NAMES (deze laatste zal niet worden ingeschakeld kleine letters), alle gescheiden door koppeltekens. De _classNames hash bevat ook de classNames voor de boundingBox en de contentBox , de eerste onder de "." toets en de tweede onder de “content” te drukken. Widget toekent aan de boundingBox de classNames afgeleid van de waarden van de NAME eigendom van elk van de klassen in de erfenis keten, te beginnen met yui3-widget . MakeNode winkels naar this._classNames alleen de bovenste className voor de boundingBox .

Als een onderdeel verschillende niveaus uit de buurt van Widget, zoals SuperSpecialSpinner overneemt van SuperSpinner die erft van Spinner , die erft van Widget, en als enige of alle van hen hebben _CLASS_NAMES eigenschappen die zijn gedefinieerd, MakeNode zal classNames produceren voor hen allemaal en ze opslaan in this._classNames . U hoeft niet op te nemen op elk niveau van de namen die reeds verklaard in de vorige levels. In feite is het beter dat je niet doen, omdat de classNames geproduceerd op elk niveau zal de waarde van het gebruik NAME eigendom van dat niveau. Dus in SuperSpecialSpinner , {c input} zal nog resulteren in “yui3-spinner-input” en niet “yui3-superspecialspinner-input” en zo zal uw CSS-bestand nog geldig is.

De {s} placeholder

Widget heeft een strings gedefinieerde configuratie attribuut, maar het is niet geïnitialiseerd met een waarde. Dit attribuut is bedoeld om strings die zichtbaar zijn (of, via schermlezers, lezen) van de gebruiker vast te houden. Het is belangrijk dat u nooit zichtbaar strings direct in de template op te nemen. Dit is niet een vereiste van MakeNode - het is nooit een goed idee. Alle strings die moeten worden bekeken door lezen of om de gebruiker moet altijd worden geplaatst in de strings attribuut. De strings attribuut bevat een hash waar elke individuele tekst bevindt zich bij de belangrijkste. De Spinner component heeft de volgende snaren, die je kunt zien vooral gebruikt in de sjabloon.

  strings: {
     waarde: {
         ingang: ". Druk op de pijl omhoog / omlaag toetsen voor kleine stappen, up / down voor de grote stappen van pagina",
         up: "Increment",
         naar beneden: "Afname"
     }
 }, 

Het beste deel van dit te doen is dat je component kan worden gelokaliseerd in andere talen heel gemakkelijk door de ontwikkelaars met behulp van uw component. Bij het maken van een exemplaar van Spinner, zou je doen:

  var mySpinner = new Spinner ({strings: Y.Intl.get ("spinner')}); 

Het instellen van de configuratie attribuut strings op deze manier vervangt de standaard strings waarden met die van de taal bronbestand met behulp van de taal vooraf gedefinieerd. De {s} tijdelijke aanduiding toegang tot de strings zijn opgeslagen in de strings attribuut, ofwel de standaard instellingen of de vertaalde die, indien ingesteld. De {s xxxx} tijdelijke aanduiding is in feite niets meer dan een snelkoppeling naar de {@ strings.xxxx} tijdelijke aanduiding. Echter, kan de eerste alleen toegang tot strings op het hoogste niveau, terwijl, bijvoorbeeld, {@ strings.xxxx.yyyy.zzzz} laat je toe om een snaar toegang dieper naar beneden.

Met behulp van _makeNode in renderUI

We maken gebruik van het sjabloon om de opmaak voor onze component te creëren. Om dit te doen, kunnen we noemen MakeNode's _makeNode methode, zoals deze:

  renderUI: function () {
     . this.get ('contentBox ") append (this._makeNode ());
 }, 

Dit zal invullen van de contentBox van onze widget met de opmaak van het verwerken van de sjabloon. De _makeNode methode geeft een voorbeeld van Y.Node , die kunnen worden toegevoegd of waar dan ook of gewoon geplaatst aangehouden voor later gebruik. Het maakt niet terug een string, produceert het een Node instantie.

De _makeNode methode neemt twee optionele argumenten: een verwijzing naar een sjabloon en een object in te vullen tijdelijke aanduidingen, zoals Y.substitute doet. In ons eenvoudige Spinner Zo is er een sjabloon voor het hele widget maar ook andere widgets zou kunnen vereisen stukjes en beetjes uit verschillende sjablonen gemaakt. In dat geval zou je meestal noemen _makeNode zonder argumenten voor het grootste deel en noem het opnieuw met verschillende sjablonen te vullen in de extra onderdelen. Het voorbeeld bevat deze renderUI methode:

  renderUI: function () {
     var fieldset = this._makeNode ();
     this.each (function (item) {
         fieldset.appendChild (this._makeNode (MultipleTemplates.RADIO_TEMPLATE, item));
     }, This);
     . this.get ('contentBox ") append (fieldset);
 } 

De eerste oproep tot _makeNode geeft een Node instantie opgeslagen in de variabele fieldset . Het monster component is ook uitgebreid met Y.ArrayList , zodat de RADIO_TEMPLATE zal worden gevuld met de waarden uit de items in de array lijst en de daaruit voortvloeiende Nodes toegevoegd aan de fieldset voordat het wordt uiteindelijk toegevoegd aan de contentBox . De speciale tijdelijke aanduidingen, zoals {@} of {p} nog steeds verwijzen naar attributen of eigenschappen in het hoofddoel. De geneste items zal worden verwerkt net zo Y.substitute zou doen.

De _locateNodes methode

MakeNode verschaft verder een _locateNodes methode die zal proberen om alle elementen met de classNames verklaard lokaliseren _CLASS_NAMES . Te vinden op specifieke elementen kun je een willekeurig aantal className sleutels passeren, anders _locateNodes probeert ze allemaal. Voor elk element gevonden van elke className, _locateNodes zal produceren een prive-instantie woning met behulp van de underscore prefix gevolgd door de toets naam en het “Node” achtervoegsel. Dus in ons voorbeeld Spinner, _locateNodes genereert de eigenschappen _inputNode , _upNode en _downNode . Als meerdere elementen hebben dezelfde className, _locateNodes terug een verwijzing naar de eerste van hen. Als een element niet wordt gevonden, wordt geen variabele worden gecreëerd.

In de Spinner component die we gebruiken _locateNodes na het maken van de opmaak:

  renderUI: function () {
     . this.get (CBX) toevoegen (this._makeNode ());
     this._locateNodes ();
 }, 

De _EVENTS statische eigenschap

Nog een eigenschap kan gedefinieerd worden langs de lijnen van _TEMPLATE en _CLASS_NAMES en dat is _EVENTS . _EVENTS wordt een hash gemaakt van eersteklas naam toetsen, elk met een hash van event types en methoden om te gaan bevatten. Het is beter uitgelegd met een voorbeeld:

  _EVENTS: {
     '.': {
         sleutel: {
             fn: '_onDirectionKey',
             args: ((Y.UA.opera) "naar beneden:":? "pers:") + "38, 40, 33, 34"
         },
         mouseDown: '_onMouseDown'
     },
     '..': {
         mouseUp: '_onDocMouseUp'
     },
     ingang: {
         verandering: '_onInputChange'
     }
 }, 

_EVENTS is een object (een hash) met een willekeurig aantal eigenschappen. De namen van de eigenschappen, dat wil zeggen de sleutels van de hash, identificeren van de elementen waarvan de evenementen die we zullen luisteren. Het zijn dezelfde id's gebruikt in de _CLASS_NAMES . Er zijn twee extra speciale sleutels "." en ".." . Terwijl de className sleutels verwijzen naar elementen genest in de contentBox , de "." sleutel verwijst naar de boundingBox zelf, terwijl ".." verwijst naar het document met deze widget. Denk aan hen als het doen van een chdir opdracht wanneer gelegen aan de boundingBox niveau. De _EVENTS woning is verwerkt nadat de renderUI , bindUI en syncUI methoden zijn genoemd, zodat de widget is naar verwachting al worden ingevoegd in het document lichaam, anders wordt de ".." zal mislukken.

Elk van de items in _EVENTS is een ander doel dat de aard van de gebeurtenis gebruikt als de belangrijkste en de naam van een instantie methode om te gaan. _EVENTS , als een statische variabele, heeft geen toegang tot this dus het kan geen werkelijke functie referenties, alleen de naam van het event listener-methode. Sommige soorten gebeurtenissen behoefte aan extra argumenten, zoals de key gebeurtenis. In dat geval, in plaats van de naam van het event handler kun je zorgen voor een object met eigenschappen die fn en args om de functie naam en het extra argumenten, houdt u wanneer dat nodig is.

MakeNode zal gebruik maken van Node.delegate om te luisteren naar de gebeurtenissen van de geneste elementen, terwijl zij zal gebruiken Y.on om te luisteren naar gebeurtenissen uit de boundingBox en het document lichaam. (Opmerking: luisteren naar de key gebeurtenis op een geneste element werkt alleen met versie 3.4.0pr1 en hoger, omdat delegatie van de key .. evenement was niet beschikbaar voor alle andere functies werken met vorige versies ook)

De _EVENTS verklaringen zijn cumulatief wanneer componenten erven van elkaar. Elke klasse in de erfenis keten zal zijn eigen _EVENTS verklaring apart verwerkt.

De _ATTRS_2_UI statische eigenschap

Evenementen gaan in beide richtingen, van de gebruikersinterface om de component en van de component aan de UI. De eerste worden afgehandeld door de _EVENTS eigendom. Dan zijn er de gebeurtenissen die afgevuurd door attribuutwaarde veranderingen die moeten worden weerspiegeld in de gebruikersinterface. Zoals ik al zei in het vorige artikel, wanneer er sprake is van secundaire gevolgen van het veranderen van een configuratie attribuut, moeten ze worden behandeld door verandering gebeurtenislisteners, niet door de optionele setter methode van het attribuut, die alleen zou moeten gaan met het normaliseren van de waarde wordt ingesteld. De UI moet een weerspiegeling zijn van de toestand van de configuratie van attributen, eerst in syncUI , wanneer zij worden geïnitialiseerd en dan op elk attribuut te wijzigen evenement. Voor deze laatste, moeten we een event listener die we doen hechten bindUI . Widget biedt reeds een mechanisme om die eenvoudige, die ik beschreef in het commentaar op het vorige artikel te maken.

Widget maakt gebruik van de instantie eigenschap _UI_ATTRS dat een object met twee andere eigenschappen, bevat SYNC en BIND . Elk van deze is een array met de namen van de configuratie attributen in eerste instantie worden gesynchroniseerd en vervolgens om de UI beantwoordend aan de huidige waarden te houden geluisterd. Widget verwacht dat elk van deze items een methode te hebben gekoppeld, vernoemd naar het attribuut naam voorafgegaan door _uiSet met de eerste letter van het attribuut naam omgezet in hoofdletters om de methode naam hebben in de juiste camel geval. Dus, als "value" werd vermeld in een van de _UI_ATTRS arrays (in beide SYNC of BIND ), zou Widget verwachten een vondst _uiSetValue methode. Deze methode zal twee argumenten te ontvangen, de value wordt ingesteld en de src van de verandering. Dit is de code voor onze Spinner _uiSetValue methode:

  _uiSetValue: function (value, src) {
     if (src === UI) {
         terug te keren;
     }
     this._inputNode.set (waarde, this.get (FORMATTER) (waarde));
 }, 

Alle hoofdletters id's die u ziet in dit stuk van de code komen overeen met string constanten verklaard elders, zodat de YUI compressor zijn werk beter te doen. De methode, in principe, stelt de value HTML-attribuut in de <input> vak om de nieuwe waarde in te stellen, na te zijn geformatteerd. De verwijzing naar het tekstveld werd verstrekt door _locateNodes . De src argument is in eerste instantie gecontroleerd of ingesteld op de tekenreekswaarde 'ui' . Als dit zo is, zal geen actie worden ondernomen. Dit is om te voorkomen dat eindeloze loops. Als de gebruiker iets in de input box, zou de waarde gaan in de value configuratie eigenschap die dan een brand valueChange gebeurtenis, die zou krijgen _uiSetValue genoemd die, indien aangevinkt, dan zou gaan en verander de waarde van de input box, die zou leiden tot het hele proces opnieuw. Dus in _uiSetValue , als we weten de verandering komt van de UI, doen we niets en dat breekt de lus. Dit vereist echter een ander stukje code elders. In de luisteraar voor de DOM event, als we de configuratie is ingesteld, gebruiken we de derde optionele argument om, zoals in dit voorbeeld:

  _afterValueChange: functie (ev) {
     this.set (waarde, ev.newVal, {src: UI});
 } 

Het is aan ons om ervoor te zorgen dat veranderingen vanuit de UI zijn dus gemarkeerd en controleer vervolgens of dezelfde vlag om loops te vermijden.

Met al dit gezegd had, heb ik nog niet genoemd de statische eigenschap _ATTRS_2_UI vermeld in de titel van deze paragraaf. Als de opmerkingen in mijn vorige artikel laat zien (via de blunders maakte ik in hen), en zorg ervoor dat alle attributen die de UI correct zijn vermeld is een beetje rommelig. U moet nooit initialiseren _UI_ATTRS vanuit het niets, omdat Widget bevat al een heleboel attributen en die verloren zouden gaan. Je moet nieuwe attribuut namen samen te voegen in de bestaande, dat enigszins is moeilijk om te onthouden hoe je het goed doet. Om het simpel, MakeNode lezen van de statische eigenschap _ATTRS_2_UI en doen dat aaneenschakeling voor je. Het zal aaneenschakelen al die lijsten van elke klasse in de erfenis keten, zodat op ieder niveau iedere klasse kan zijn eigen attributen verwerken. In Spinner, hebben we:

  _ATTRS_2_UI: {
     BIND: VALUE,
     SYNC: VALUE
 }, 

MakeNode accepteert zowel een reeks van namen of van een enkel attribuut naam, zoals in dit geval.

De vraag rijst natuurlijk, waarom twee lijsten, een voor het binden van de andere voor het synchroniseren? Heel vaak de SYNC array minder vermeldingen dan de BIND lijst en dit is omdat het sjabloon voor het onderdeel misschien al precies dezelfde standaard waarde als de configuratie attribuut, en er is geen noodzaak om een eerste synchronisatie te doen. Dus, als de standaardwaarde voor de value configuratie attribuut is een lege string en de <input> element in de sjabloon heeft geen value toekennen, dan is er geen noodzaak om ze te synchroniseren op de initialisatie.

MakeNode zal controleren op dubbele items in een van deze arrays. Als er verschijnen, dan betekent dit dat een klasse onze component erft van al verwerkt dit attribuut en elke nieuwe verklaring zou zeer waarschijnlijk over de schreef gaan _uiSetXxxx handler voor. Overigens, MakeNode controleert ook op dubbele vermeldingen in _CLASS_NAMES , die ook conflicten veroorzaken in sommige, maar niet alle, omstandigheden. MakeNode zullen schrijven een boodschap aan de log voor dergelijke fouten.

Conclusie

MakeNode biedt een zeer eenvoudige template-processor, met eenvoudige functionaliteit die in hoge mate geïntegreerd met de Widget Foundation Class. Het biedt ook helper methoden om classNames te creëren om te worden gebruikt in de sjabloon en die namen te gebruiken om creëerde de knooppunten te vinden. Het biedt ook de middelen om haak in de gebeurtenissen gegenereerd door zowel de gebruikersinterface en de component zelf en associëren met elk een methode. Het doet al deze dingen, en tegelijkertijd zorgen voor de erfenis keten respect rechtstreeks naar Widget en elk niveau van de klassen kunt u definiëren.

Zij voorziet niet in voor absoluut alle mogelijkheden, maar bestrijkt een goede spreiding van hen. Toch hoeft het niet dat je van het toevoegen van extra functionaliteit. Je zou kunnen hebben zelden een schrijven bindUI of syncUI methode als u gebruik maken van de lijm door MakeNode, maar u kunt dit doen, omdat MakeNode ze niet gebruikt.

Als een bonus aan degenen die het geduld ver dit leest, heb ik ook aangepast Anthony Pipkin's Button set van galerie componenten:

• button.js
• button.css
• button-group.js
• button-group.css
• background.png
• achtergrond-active.png
• icon-sprite.gif
• voorbeeld

De API docs kan worden gevonden hier .

Zoek gesprekken: Bloglines | technorati

Delen en uit te breiden: Bookmark met del.icio.us | digg it! | reddit!