angular 2 cookbook - programmer booksdowngrading angular 2 components to angular 1 directives with...

Angular2Cookbook

TableofContents

Angular2CookbookCreditsAbouttheAuthorAbouttheReviewerwww.PacktPub.com

Whysubscribe?CustomerFeedbackDedicationPreface

WhatthisbookcoversWhatyouneedforthisbookWhothisbookisforConventionsReaderfeedbackCustomersupport

DownloadingtheexamplecodeErrataPiracyQuestions

1.StrategiesforUpgradingtoAngular2IntroductionComponentizingdirectivesusingcontrollerAsencapsulation

GettingreadyHowtodoit...Howitworks...There'smore...Seealso

MigratinganapplicationtocomponentdirectivesGettingreadyHowtodoit...Howitworks...There'smore...Seealso

ImplementingabasiccomponentinAngularJS1.5GettingreadyHowtodoit...Howitworks...There'smore...Seealso

NormalizingservicetypesGettingreadyHowtodoit...Howitworks...There'smore...Seealso

ConnectingAngular1andAngular2withUpgradeModuleGettingreadyHowtodoit...

ConnectingAngular1toAngular2Howitworks...There'smore...Seealso

DowngradingAngular2componentstoAngular1directiveswithdowngradeComponentGettingreadyHowtodoit...Howitworks...Seealso

DowngradeAngular2providerstoAngular1serviceswithdowngradeInjectableGettingreadyHowtodoit...Seealso

2.ConqueringComponentsandDirectivesIntroductionUsingdecoratorstobuildandstyleasimplecomponent

GettingreadyHowtodoit...

WritingtheclassdefinitionWritingthecomponentclassdecorator

Howitworks...There'smore...Seealso

PassingmembersfromaparentcomponentintoachildcomponentGettingreadyHowtodoit...

ConnectingthecomponentsDeclaringinputs

Howitworks...There'smore...

AngularexpressionsUnidirectionaldatabindingMembermethods

SeealsoBindingtonativeelementattributes

Howtodoit...Howitworks...Seealso

RegisteringhandlersonnativebrowsereventsGettingreadyHowtodoit...Howitworks...There'smore...Seealso

GeneratingandcapturingcustomeventsusingEventEmitterGettingreadyHowtodoit...

CapturingtheeventdataEmittingacustomeventListeningforcustomevents


AttachingbehaviortoDOMelementswithdirectivesGettingreadyHowtodoit...

AttachingtoeventswithHostListenersHowitworks...There'smore...Seealso

ProjectingnestedcontentusingngContentGettingreadyHowtodoit...Howitworks...There'smore...Seealso

UsingngForandngIfstructuraldirectivesformodel-basedDOMcontrolGettingreadyHowtodoit...Howitworks...There'smore...Seealso

ReferencingelementsusingtemplatevariablesGettingreadyHowtodoit...

There'smore...Seealso

AttributepropertybindingGettingreadyHowtodoit...Howitworks...There'smore...Seealso

UtilizingcomponentlifecyclehooksGettingreadyHowtodoit...Howitworks...There'smore...Seealso

ReferencingaparentcomponentfromachildcomponentGettingreadyHowtodoit...Howitworks...There'smore...Seealso

Configuringmutualparent-childawarenesswithViewChildandforwardRefGettingreadyHowtodoit...

ConfiguringaViewChildreferenceCorrectingthedependencycyclewithforwardRefAddingthedisablebehavior


ViewChildrenSeealso

Configuringmutualparent-childawarenesswithContentChildandforwardRefGettingreadyHowtodoit...

ConvertingtoContentChildCorrectingdatabinding


ContentChildrenSeealso

3.BuildingTemplate-DrivenandReactiveFormsIntroductionImplementingsimpletwo-waydatabindingwithngModel

Howtodoit...Howitworks...There'smore...Seealso

ImplementingbasicfieldvalidationwithaFormControlGettingreadyHowtodoit...Howitworks...There'smore...

ValidatorsandattributedualityTaglesscontrols

SeealsoBundlingcontrolswithaFormGroup

GettingreadyHowtodoit...Howitworks...There'smore...

FormGroupvalidatorsErrorpropagation

SeealsoBundlingFormControlswithaFormArray


ImplementingbasicformswithNgFormGettingreadyHowtodoit...

DeclaringformfieldswithngModelHowitworks...There'smore...Seealso

ImplementingbasicformswithFormBuilderandformControlNameGettingreadyHowtodoit...Howitworks...There'smore...Seealso

CreatingandusingacustomvalidatorGettingreadyHowtodoit...


RefactoringintovalidatorattributesSeealso

CreatingandusingacustomasynchronousvalidatorwithPromisesGettingreadyHowtodoit...Howitworks...There'smore...

ValidatorexecutionSeealso

4.MasteringPromisesIntroductionUnderstandingandimplementingbasicPromises


DecoupledandduplicatedPromisecontrolResolvingaPromisetoavalueDelayedhandlerdefinitionMultiplehandlerdefinitionPrivatePromisemembers

SeealsoChainingPromisesandPromisehandlers

Howtodoit...Chainedhandlers'datahandoffRejectingachainedhandler


Promisehandlertreescatch()

SeealsoCreatingPromisewrapperswithPromise.resolve()andPromise.reject()

Howtodoit...Promisenormalization


ImplementingPromisebarrierswithPromise.all()Howtodoit...Howitworks...


CancelingasynchronousactionswithPromise.race()GettingreadyHowtodoit...Howitworks...Seealso

ConvertingaPromiseintoanObservableHowtodoit...Howitworks...There'smore...Seealso

ConvertinganHTTPserviceObservableintoaZoneAwarePromiseGettingreadyHowtodoit...Howitworks...Seealso

5.ReactiveXObservablesIntroduction

TheObserverPatternReactiveXandRxJSObservablesinAngular2ObservablesandPromises

BasicutilizationofObservableswithHTTPGettingreadyHowtodoit...Howitworks...

Observable<Response>TheRxJSmap()operatorSubscribe

There'smore...HotandcoldObservables

SeealsoImplementingaPublish-SubscribemodelusingSubjects


NativeRxJSimplementationSeealso

CreatinganObservableauthenticationserviceusingBehaviorSubjectsGettingready

Howtodoit...InjectingtheauthenticationserviceAddingBehaviorSubjecttotheauthenticationserviceAddingAPImethodstotheauthenticationserviceWiringtheservicemethodsintothecomponent


BuildingageneralizedPublish-Subscribeservicetoreplace$broadcast,$emit,and$onGettingreadyHowtodoit...

IntroducingchannelabstractionHookingcomponentsintotheserviceUnsubscribingfromchannels


ConsiderationsofanObservable'scompositionandmanipulationSeealso

UsingQueryListsandObservablestofollowchangesinViewChildrenGettingreadyHowtodoit...

DealingwithQueryListsCorrectingtheexpressionchangederror

Howitworks...Hatetheplayer,notthegame

SeealsoBuildingafullyfeaturedAutoCompletewithObservables


UsingtheFormControlvalueChangesObservableDebouncingtheinputIgnoringserialduplicatesFlatteningObservablesHandlingunorderedresponses

Howitworks...Seealso

6.TheComponentRouterIntroductionSettingupanapplicationtosupportsimpleroutes


SettingthebaseURL

DefiningroutesProvidingroutestotheapplicationRenderingroutecomponentswithRouterOutlet


InitialpageloadSeealso

NavigatingwithrouterLinksGettingreadyHowtodoit...Howitworks...There'smore...

RouteorderconsiderationsSeealso

NavigatingwiththeRouterserviceGettingreadyHowtodoit...Howitworks...There'smore...Seealso

SelectingaLocationStrategyforpathconstructionHowtodoit...There'smore...

ConfiguringyourapplicationserverforPathLocationStrategyBuildingstatefulroutebehaviorwithRouterLinkActive


ImplementingnestedviewswithrouteparametersandchildroutesGettingreadyHowtodoit...

AddingaroutingtargettotheparentcomponentDefiningnestedchildviewsDefiningthechildroutesDefiningchildviewlinksExtractingrouteparameters


RefactoringwithasyncpipesSeealso

WorkingwithmatrixURLparametersandroutingarraysGettingreadyHowtodoit...Howitworks...There'smore...Seealso

AddingrouteauthenticationcontrolswithrouteguardsGettingreadyHowtodoit...

ImplementingtheAuthserviceWiringuptheprofileviewRestrictingrouteaccesswithrouteguardsAddingloginbehaviorAddingthelogoutbehavior


TheactualauthenticationSecuredataandviews

Seealso7.Services,DependencyInjection,andNgModule

IntroductionInjectingasimpleserviceintoacomponent


ControllingserviceinstancecreationandinjectionwithNgModuleGettingreadyHowtodoit...

SplittinguptherootmoduleHowitworks...There'smore...

InjectingdifferentserviceinstancesintodifferentcomponentsServiceinstantiation

SeealsoServiceinjectionaliasingwithuseClassanduseExisting

GettingreadyDualservicesAunifiedcomponent

Howtodoit...Howitworks...

There'smore...Refactoringwithdirectiveproviders

SeealsoInjectingavalueasaservicewithuseValueandOpaqueTokens


Buildingaprovider-configuredservicewithuseFactoryGettingreadyHowtodoit...

DefiningthefactoryInjectingOpaqueTokenCreatingproviderdirectiveswithuseFactory


8.ApplicationOrganizationandManagementIntroductionComposingpackage.jsonforaminimumviableAngular2application


package.jsondependenciespackage.jsondevDependenciespackage.jsonscripts

SeealsoConfiguringTypeScriptforaminimumviableAngular2application


Declarationfilestsconfig.json

Howitworks...Compilation

There'smore...SourcemapgenerationSinglefilecompilation

SeealsoPerformingin-browsertranspilationwithSystemJS

GettingreadyHowtodoit...Howitworks...


ComposingapplicationfilesforaminimumviableAngular2applicationGettingreadyHowtodoit...

app.component.tsapp.module.tsmain.tsindex.htmlConfiguringSystemJS

SeealsoMigratingtheminimumviableapplicationtoWebpackbundling


webpack.config.jsSeealso

IncorporatingshimsandpolyfillsintoWebpackGettingreadyHowtodoit...Howitworks...Seealso

HTMLgenerationwithhtml-webpack-pluginGettingreadyHowtodoit...Howitworks...Seealso

SettingupanapplicationwithAngularCLIGettingreadyHowtodoit...

RunningtheapplicationlocallyTestingtheapplication

Howitworks...ProjectconfigurationfilesTypeScriptconfigurationfilesTestconfigurationfilesCoreapplicationfilesEnvironmentfilesAppComponentfilesAppComponenttestfiles


9.Angular2Testing

IntroductionCreatingaminimumviableunittestsuitewithKarma,Jasmine,andTypeScript


WritingaunittestConfiguringKarmaandJasmineConfiguringPhantomJSCompilingfilesandtestswithTypeScriptIncorporatingWebpackintoKarmaWritingthetestscript


WritingaminimumviableunittestsuiteforasimplecomponentGettingreadyHowtodoit...

UsingTestBedandasyncCreatingaComponentFixture

Howitworks...Seealso

Writingaminimumviableend-to-endtestsuiteforasimpleapplicationGettingreadyHowtodoit...

GettingProtractorupandrunningMakingProtractorcompatiblewithJasmineandTypeScriptBuildingapageobjectWritingthee2etestScriptingthee2etests


UnittestingasynchronousserviceGettingreadyHowtodoit...Howitworks...There'smore...

TestingwithoutinjectionSeealso

UnittestingacomponentwithaservicedependencyusingstubsGettingreadyHowtodoit...

Stubbingaservicedependency

TriggeringeventsinsidethecomponentfixtureHowitworks...Seealso

UnittestingacomponentwithaservicedependencyusingspiesGettingreadyHowtodoit...

SettingaspyontheinjectedserviceHowitworks...There'smore...Seealso

10.PerformanceandAdvancedConceptsIntroductionUnderstandingandproperlyutilizingenableProdModewithpureandimpurepipes


GeneratingaconsistencyerrorIntroducingchangedetectioncomplianceSwitchingonenableProdMode


WorkingwithzonesoutsideAngularGettingreadyHowtodoit...

ForkingazoneOverridingzoneeventswithZoneSpec


Understandingzone.run()Microtasksandmacrotasks

SeealsoListeningforNgZoneevents

zone.jsNgZoneGettingreadyHowtodoit...

DemonstratingthezonelifecycleHowitworks...

Theutilityofzone.jsSeealso

ExecutionoutsidetheAngularzoneHowtodoit...


ConfiguringcomponentstouseexplicitchangedetectionwithOnPushGettingreadyHowtodoit...

ConfiguringtheChangeDetectionStrategyRequestingexplicitchangedetection


ConfiguringViewEncapsulationformaximumefficiencyGettingreadyHowtodoit...

EmulatedstylingencapsulationNostylingencapsulationNativestylingencapsulation


ConfiguringtheAngular2RenderertousewebworkersGettingreadyHowtodoit...Howitworks...There'smore...

OptimizingforperformancegainsCompatibilityconsiderations

SeealsoConfiguringapplicationstouseahead-of-timecompilation


InstallingAOTdependenciesConfiguringngcAligningcomponentdefinitionswithAOTrequirementsCompilingwithngcBootstrappingwithAOT


GoingfurtherwithTreeShakingSeealso

ConfiguringanapplicationtouselazyloadingGettingready

Howtodoit...Howitworks...There'smore...

AccountingforsharedmodulesSeealso

Angular2Cookbook

Angular2CookbookCopyright©2017PacktPublishing

Allrightsreserved.Nopartofthisbookmaybereproduced,storedinaretrievalsystem,ortransmittedinanyformorbyanymeans,withoutthepriorwrittenpermissionofthepublisher,exceptinthecaseofbriefquotationsembeddedincriticalarticlesorreviews.

Everyefforthasbeenmadeinthepreparationofthisbooktoensuretheaccuracyoftheinformationpresented.However,theinformationcontainedinthisbookissoldwithoutwarranty,eitherexpressorimplied.Neithertheauthor,norPacktPublishing,anditsdealersanddistributorswillbeheldliableforanydamagescausedorallegedtobecauseddirectlyorindirectlybythisbook.

PacktPublishinghasendeavoredtoprovidetrademarkinformationaboutallofthecompaniesandproductsmentionedinthisbookbytheappropriateuseofcapitals.However,PacktPublishingcannotguaranteetheaccuracyofthisinformation.

Firstpublished:January2017

Productionreference:1160117

PublishedbyPacktPublishingLtd.

LiveryPlace

35LiveryStreet

Birmingham

B32PB,UK.

ISBN978-1-78588-192-3

www.packtpub.com

http://www.packtpub.com

CreditsAuthor

MattFrisbie

ProjectCoordinator

RitikaManoj

Reviewer

PatrickGillespie

Proofreader

SafisEditing

AcquisitionEditor

VinayArgekar

Indexer

FrancyPuthiry

ContentDevelopmentEditor

ArunNadar

Graphics

KirkD'Penha

TechnicalEditor

VivekArora

ProductionCoordinator

DeepikaNaik

CopyEditor

GladsonMonteiro

CoverWork

DeepikaNaik

AbouttheAuthorMattFrisbieiscurrentlyasoftwareengineeratGoogle.HewastheauthorofthePacktPublishingbestsellerAngularJSWebApplicationDevelopmentCookbookandalsohaspublishedseveralvideoseriesthroughO'Reilly.HeisactiveintheAngularcommunity,givingpresentationsatmeetupsanddoingwebcasts.

WritingabookonAngular2whiletheframeworkitselfwasunfinishedwasanimmenselychallengingendeavor.Fragmentedexamples,incompletedocumentation,andanascentdevelopercommunitywerejustahandfulofthemanyroadblocksIencounteredonthejourneytofinishingthistitle,anditwasonlybecauseofalegionofsupportersthatthisbookwasfinishedandwasabletodojusticetotheframework.

ThisbookwouldnothavebeenpossiblewithoutthetirelessworkofallthePacktstaffinvolved.I'dspecificallyliketothankArunNadar,VivekArora,MerwynD'Souza,andVinayArgekarfortheireditorialoversightandexpertise,aswellasPatrickGillespieforhisworkascontentreviewer.I'dalsoliketothankJordan,Zoey,Scott,andmyfamilyandfriendsforcheeringmeon.

AbouttheReviewerPatrickGillespiehasbeenintosoftwaredevelopmentsince1996.Hehasbothabachelor'sandamaster'sdegreeincomputerscience.Inhissparetime,heenjoysphotography,spendingtimewithhisfamily,andworkingonvarioussideprojectsforhiswebsite(http://patorjk.com/).

http://patorjk.com/

www.PacktPub.comForsupportfilesanddownloadsrelatedtoyourbook,pleasevisitwww.PacktPub.com.

DidyouknowthatPacktofferseBookversionsofeverybookpublished,withPDFandePubfilesavailable?YoucanupgradetotheeBookversionatwww.PacktPub.comandasaprintbookcustomer,youareentitledtoadiscountontheeBookcopy.Getintouchwithusatservice@packtpub.comformoredetails.

Atwww.PacktPub.com,youcanalsoreadacollectionoffreetechnicalarticles,signupforarangeoffreenewslettersandreceiveexclusivediscountsandoffersonPacktbooksandeBooks.

https://www.packtpub.com/mapt

Getthemostin-demandsoftwareskillswithMapt.MaptgivesyoufullaccesstoallPacktbooksandvideocourses,aswellasindustry-leadingtoolstohelpyouplanyourpersonaldevelopmentandadvanceyourcareer.

http://www.PacktPub.com



https://www.packtpub.com/mapt

Whysubscribe?FullysearchableacrosseverybookpublishedbyPacktCopyandpaste,print,andbookmarkcontentOndemandandaccessibleviaawebbrowser

CustomerFeedbackThankyouforpurchasingthisPacktbook.Wetakeourcommitmenttoimprovingourcontentandproductstomeetyourneedsseriously—that'swhyyourfeedbackissovaluable.Whateveryourfeelingsaboutyourpurchase,pleaseconsiderleavingareviewonthisbook'sAmazonpage.Notonlywillthishelpus,moreimportantlyitwillalsohelpothersinthecommunitytomakeaninformeddecisionabouttheresourcesthattheyinvestintolearn.

Youcanalsoreviewforusonaregularbasisbyjoiningourreviewers'club.Ifyou'reinterestedinjoining,orwouldliketolearnmoreaboutthebenefitsweoffer,pleasecontactus:[email protected].

DedicationTomygrandparents,RichardandMargery.Here'stoupholdingthefamilyhonor.

Preface"Everybodyhasaplanuntiltheygetpunchedinthemouth."-MikeTyson,undisputedheavyweightchampionboxer

Soonafteritscreationin2009,AngularJSgrewintoawidelypopularfoundationaltoolforbuildingfrontendapplications.Asyearsandreleaseswentby,andtheJavaScriptcommunitymatured,theworldofclient-sideprogrammingbroadenedbeyondwhatAngularwasoriginallydesignedfor.Itscaretakerstookstockanddecidedthatasweepingoverhauloftheframeworkwasinorder.

AngularJS,nowAngular1,stillexistsandwillbesupportedfortheyearstocome,butinitswakeliesAngular2—awhollydifferentanimalbuiltforthefutureofclient-sidecomputing.Angular2abandonsantipatternsbythefistfuland,instead,isreshapedintoapreciseandelegantsoftwareinstrument.Itembracestheimpendingrenaissanceofwebtechnologies,buildingatopES6,webcomponents,webworkers,TypeScript,andreactiveprogramming,tonameafew.Itbringsframeworkmodularitytonewheights,buildingitselfaroundtheconceptthatanymodularpieceofAngular2shouldbeeasilydiscardedorreplaced.Bestofall,Angular2offersabountifulcollectionofconfigurationandtoolingthatwillmakeyourapplicationsrunatbreakneckspeed.

Tomanydevelopers,Angular2isfrighteningbecausesomuchofitisnewandunfamiliar.ThisbookexiststoofferyouanapproachablepathtoafullunderstandingofAngular2,whatitoffers,andhowbesttouseit.Youwillfindbothsimpleexamplestosetafoundationalunderstanding,andcomplexdemonstrationstohintattheframework'spower.Thebookisorganizedintorecipesthatareindependentofeachother,soyouareabletojumpinatanypointandimmediatelybeginlearning.

WhatthisbookcoversThisbookisuptodateforthe2.4releaseandiscompatiblethroughthe4.0releaseaswell,anditdoesnothaveanycodebasedonthebetaorreleasecandidates.

Chapter1,StrategiesforUpgradingtoAngular2,isanoverviewofanumberofwaystomigrateanAngular1applicationtoAngular2.Althoughthereisnoone-size-fits-allupgradestrategy,youwillfindthattheserecipesdemonstratesomewaysthatwillallowyoutopreservealargeamountofyourexistingAngular1codebase.

Chapter2,ConqueringComponentsandDirectives,givesabroadanddeepsetofexamplesinvolvingwhatAngular2componentsareandhowtousethem.Angular2applicationsarebuiltentirelyofcomponents,andthischapteroffersyouatotalrundownoftheirrole.

Chapter3,BuildingTemplate-DrivenandReactiveForms,coversthereworkedAngular2formmodules.Angular2offersyoutwoprimarystylesoferectingformfeatures,andthischaptercoversbothofthemindepth.

Chapter4,MasteringPromises,showshowthePromiseobjecthasaroleinAngular2.AlthoughRxJShassubsumedsomeoftheusefulnessofPromises,theyarestillfirst-classcitizensinES6andstillplayacrucialrole.

Chapter5,ReactiveXObservables,givesyouacrashcourseinhowAngular2hasembracedreactiveprogramming.ItincludesrecipesthatdemonstratethebasicsofObservablesandSubjects,aswellasadvancedimplementationsthattakeRxJStoitslimits.

Chapter6,TheComponentRouter,takesyouthroughthetotallyreworkedroutingmoduleinAngular2.ItcoversbothroutingbasicsaswellasanarrayofadvancedroutingconceptsuniquetoAngular2.

Chapter7,Services,DependencyInjection,andNgModule,describesthenewandimproveddependencyinjectionandmodulestrategiesofAngular2.Itgivesyouallthepiecesyouneedtobreakyourapplicationintoindependentservicesandmodules,aswellasidealstrategiesforconnectingthosepiecestogether.

Chapter8,ApplicationOrganizationandManagement,isabroadoverviewofhowyoucanmanageyourAngular2applicationinsideandoutsidetheclient.Angular2introducesanumberoflayersofcomplexitythatrequireadvancedtooling,andthischapterwillguideyouthroughhowtoapproachthem.

Chapter9,Angular2Testing,willguideyouthroughbothhowtosetuptestsuitesforAngular2aswellashowtowritevarioustypesoftestsforthesesuites.Manydevelopersavoidtestingwhenlearningaframeworkanew,andthischaptergentlyguidesyouthroughAngular2'sexcellent

testinfrastructure.

Chapter10,PerformanceandAdvancedConcepts,isacrashcourseonthedizzyingarrayofcomplexconceptsthatAngular2comeswithoutofthebox.Thischaptercoversprogramorganizationandarchitecture,frameworkfeaturesandtooling,aswellascompile-timeoptimizations.

WhatyouneedforthisbookEveryrecipeinthisbookisaccompaniedbyalinktothebook'scompanionsite,http://ngcookbook.herokuapp.com/.RecipesthatinvolvecodeexampleswillincludealinktoaliveexampleonPlunker.Thiswillallowyoutoinspectandtestcodeinrealtimewithouthavingtoworryaboutcompilation,localservers,oranythingofthatilk.Itmustbenoted,however,thatthissetupisonlyappropriateforexperimentationandshouldnotbeusedforuser-facingorproductionapplications.

Angular2comesinbothJavaScriptandTypeScriptflavors,butthisbookaimsdirectlyattheTypeScriptedition,sinceitissyntacticallysuperior(asyouwillsoonrealize).Forproperproductionapplications,TypeScriptwillbecompiledintoJavaScriptbeforeitisservedtothebrowser.Thewaythisbookaccomplishesthis(andmanyothercodepreparationtasks)isinsideaNode.jsinstallonyourlocalmachine.Node.jsincludestheNodePackageManager(npm),whichletsyouinstallandrunopensourceJavaScriptsoftwarefromthecommandline.

SomechaptersinthisbookwillrequirethatyouhaveNode.jsinstalledbeforerunningcommandsandlaunchingalocalserverortestsuite.Furthermore,itisrecommended(butnotrequired)thatyouinstalltheNodeVersionManagerontopofNode.js,whichwillmakemanagingyourinstalledpackagesmucheasier.

http://ngcookbook.herokuapp.com/

WhothisbookisforTheuniverseofAngular2learningmaterialsiscurrentlyfragmentedandgross.Thisbookisforbothbeginnerdeveloperslookingtosinktheirteethintoanewframework,aswellasadvanceddevelopersinterestedinroundingouttheirknowledgeofaframeworkthatembracesthecomingworldofwebtech.

Fornewerdevelopers,ingestingallthesenewtechnologiesatoncemayseemoverwhelming.Theorganizationandpaceofthisbookisdesignedsothattopicsaregraduallyintroduced,anddesigndecisionsandrationalesareexplained.Don'tworry,thisbookisstillforyou.

ConventionsInthisbook,youwillfindanumberoftextstylesthatdistinguishbetweendifferentkindsofinformation.Herearesomeexamplesofthesestylesandanexplanationoftheirmeaning.

Codewordsintext,databasetablenames,foldernames,filenames,fileextensions,pathnames,dummyURLs,userinput,andTwitterhandlesareshownasfollows:"Karmareadsitsconfigurationoutofakarma.conf.jsfile."

Ablockofcodeissetasfollows:

<p>{{date}}</p>

<h1>{{title}}</h1>

<h3>Writtenby:{{author}}</h3>

Whenwewishtodrawyourattentiontoaparticularpartofacodeblock,therelevantlinesoritemsaresetinbold:

@Component({

selector:'article',

template:`

<p>{{currentDate|date}}</p>

<h1>{{title}}</h1>


`

})

Anycommand-lineinputoroutputiswrittenasfollows:

npminstallkarmajasmine-corekarma-jasmine--save-dev

npminstallkarma-cli-g

Newtermsandimportantwordsareshowninbold.

Note

Warningsorimportantnotesappearinaboxlikethis.

Tip

Tipsandtricksappearlikethis.

ReaderfeedbackFeedbackfromourreadersisalwayswelcome.Letusknowwhatyouthinkaboutthisbook-whatyoulikedordisliked.Readerfeedbackisimportantforusasithelpsusdeveloptitlesthatyouwillreallygetthemostoutof.Tosendusgeneralfeedback,[email protected],andmentionthebook'stitleinthesubjectofyourmessage.Ifthereisatopicthatyouhaveexpertiseinandyouareinterestedineitherwritingorcontributingtoabook,seeourauthorguideatwww.packtpub.com/authors.

http://www.packtpub.com/authors

CustomersupportNowthatyouaretheproudownerofaPacktbook,wehaveanumberofthingstohelpyoutogetthemostfromyourpurchase.

DownloadingtheexamplecodeYoucandownloadtheexamplecodefilesforthisbookfromyouraccountathttp://www.packtpub.com.Ifyoupurchasedthisbookelsewhere,youcanvisithttp://www.packtpub.com/supportandregistertohavethefilese-maileddirectlytoyou.

Youcandownloadthecodefilesbyfollowingthesesteps:

1. Loginorregistertoourwebsiteusingyoure-mailaddressandpassword.2. HoverthemousepointerontheSUPPORTtabatthetop.3. ClickonCodeDownloads&Errata.4. EnterthenameofthebookintheSearchbox.5. Selectthebookforwhichyou'relookingtodownloadthecodefiles.6. Choosefromthedrop-downmenuwhereyoupurchasedthisbookfrom.7. ClickonCodeDownload.

Oncethefileisdownloaded,pleasemakesurethatyouunziporextractthefolderusingthelatestversionof:

WinRAR/7-ZipforWindowsZipeg/iZip/UnRarXforMac7-Zip/PeaZipforLinux

ThecodebundleforthebookisalsohostedonGitHubathttps://github.com/PacktPublishing/Angular-2-Cookbook.Wealsohaveothercodebundlesfromourrichcatalogofbooksandvideosavailableathttps://github.com/PacktPublishing/.Checkthemout!

http://www.packtpub.com

http://www.packtpub.com/support

https://github.com/PacktPublishing/Angular-2-Cookbook

https://github.com/PacktPublishing/

ErrataAlthoughwehavetakeneverycaretoensuretheaccuracyofourcontent,mistakesdohappen.Ifyoufindamistakeinoneofourbooks-maybeamistakeinthetextorthecode-wewouldbegratefulifyoucouldreportthistous.Bydoingso,youcansaveotherreadersfromfrustrationandhelpusimprovesubsequentversionsofthisbook.Ifyoufindanyerrata,pleasereportthembyvisitinghttp://www.packtpub.com/submit-errata,selectingyourbook,clickingontheErrataSubmissionFormlink,andenteringthedetailsofyourerrata.Onceyourerrataareverified,yoursubmissionwillbeacceptedandtheerratawillbeuploadedtoourwebsiteoraddedtoanylistofexistingerrataundertheErratasectionofthattitle.

Toviewthepreviouslysubmittederrata,gotohttps://www.packtpub.com/books/content/supportandenterthenameofthebookinthesearchfield.TherequiredinformationwillappearundertheErratasection.

http://www.packtpub.com/submit-errata

https://www.packtpub.com/books/content/support

PiracyPiracyofcopyrightedmaterialontheInternetisanongoingproblemacrossallmedia.AtPackt,wetaketheprotectionofourcopyrightandlicensesveryseriously.IfyoucomeacrossanyillegalcopiesofourworksinanyformontheInternet,pleaseprovideuswiththelocationaddressorwebsitenameimmediatelysothatwecanpursuearemedy.

Pleasecontactusatcopyright@packtpub.comwithalinktothesuspectedpiratedmaterial.

Weappreciateyourhelpinprotectingourauthorsandourabilitytobringyouvaluablecontent.

QuestionsIfyouhaveaproblemwithanyaspectofthisbook,[email protected],andwewilldoourbesttoaddresstheproblem.

Chapter1.StrategiesforUpgradingtoAngular2Thischapterwillcoverthefollowingrecipes:

ComponentizingdirectivesusingthecontrollerAsencapsulationMigratinganapplicationtocomponentdirectivesImplementingabasiccomponentinAngularJS1.5NormalizingservicetypesConnectingAngular1andAngular2withUpgradeModuleDowngradingAngular2componentstoAngular1directiveswithdowngradeComponentDowngradingAngular2providerstoAngular1serviceswithdowngradeInjectable

IntroductionTheintroductionofAngular2intotheAngularecosystemwillsurelybeinterpretedandhandleddifferentlyforalldevelopers.SomewillsticktotheirexistingAngular1codebases,somewillstartbrandnewAngular2codebases,andsomewilldoagradualorpartialtransition.

ItisrecommendedthatyoubecomefamiliarwiththebehaviorofAngular2componentsbeforeyoudiveintotheserecipes.ThiswillhelpyouframementalmodelsasyouadaptyourexistingapplicationstobemorecompliantwiththeAngular2style.

ComponentizingdirectivesusingcontrollerAsencapsulationOneoftheunusualconventionsintroducedinAngular1wastherelationshipbetweendirectivesandthedatatheyconsumed.Bydefault,directivesusedaninheritedscope,whichsuitedtheneedsofmostdevelopersjustfine.Whilethiswaseasytouse,ithadtheeffectofintroducingextradependenciesinthedirectives,andalsotheconventionthatdirectivesoftendidnotownthedatatheywereconsuming.Additionally,thedatainterpolatedinthetemplatewasunclearinrelationtowhereitwasbeingassignedorowned.

Angular2utilizescomponentsasthebuildingblocksoftheentireapplication.Thesecomponentsareclass-basedandarethereforeinsomewaysatoddswiththescopemechanismsofAngular1.Transitioningtoacontroller-centricdirectivemodelisalargesteptowardscompliancewiththeAngular2standards.

Note

Thecode,links,andaliveexamplerelatedtothisrecipeareavailableathttp://ngcookbook.herokuapp.com/8194.

http://ngcookbook.herokuapp.com/8194

GettingreadySupposeyourapplicationcontainsthefollowingsetupthatinvolvesthenesteddirectivesthatsharedatausinganisolatescope:

[index.html]

<divng-app="articleApp">

<article></article>

</div>

[app.js]

angular.module('articleApp',[])

.directive('article',function(){

return{

controller:function($scope){

$scope.articleData={

person:{firstName:'Jake'},

title:'LesothoYachtClubMembershipBooms'

};

},

template:`

<h1>{{articleData.title}}</h1>

<attributionauthor="articleData.person.firstName">

</attribution>

`

};

})

.directive('attribution',function(){

return{

scope:{author:'='},

template:`<p>Writtenby:{{author}}</p>`

};

});

Howtodoit...Thegoalistorefactorthissetupsothattemplatescanbeexplicitaboutwherethedataiscomingfromandsothatthedirectiveshaveownershipofthisdata:

[app.js]



return{

controller:function(){

this.person={firstName:'Jake'};

this.title='LesothoYachtClubMembershipBooms';

},

controllerAs:'articleCtrl',

template:`

<h1>{{articleCtrl.title}}</h1>

<attribution></attribution>

`

};

})


return{

template:`<p>Writtenby:{{articleCtrl.author}}</p>`

};

});

Inthissecondimplementation,anywhereyouusethearticledata,youarecertainofitsorigin.Thisisbetter,butthechilddirectiveisstillreferencingtheparentcontroller,whichisn'tidealsinceitisintroducinganunneededdependency.Theattributiondirectiveinstanceshouldbeprovidedwiththedata,anditshouldinsteadinterpolatefromitsowncontrollerinstance:

[app.js]



return{




},


template:`


<attributionauthor="articleCtrl.person.firstName">

</attribution>

`

};

})


return{

controller:function(){},

controllerAs:'attributionCtrl',

bindToController:{author:'='},

template:`<p>Writtenby:{{attributionCtrl.author}}</p>`

};

});

Muchbetter!Youprovidethechilddirectivewithastand-incontrollerandgiveitanaliasintheattributionCtrltemplate.ItisimplicitlyboundtothecontrollerinstanceviabindToControllerinthesamewayyouwouldaccomplisharegularisolatescope;however,thebindingisdirectlyattributedtothecontrollerobjectinsteadofthescope.

Nowthatyouhaveintroducedthenotionofdataownership,supposeyouwanttomodifyyourapplicationdata.What'smore,youwantdifferentpartsofyourapplicationtobeabletomodifyit.Anaïveimplementationofthiswouldbesomethingasfollows:

[app.js]



return{


this.capitalize=function(){

this.author=this.author.toUpperCase();

}

},


bindToController:{author:'='},

template:`

<png-click="attributionCtrl.capitalize()">

Writtenby:{{attributionCtrl.author}}

</p>`

};

});

Thedesiredbehaviorisforyoutoclickontheauthor,anditwillbecomecapitalized.However,inthisimplementation,thearticlecontroller'sdataismodifiedintheattributioncontroller,whichdoesnotownit.Itispreferableforthecontrollerthatownsthedatatoperformtheactualmodificationandinsteadsupplyaninterfacethatanoutsideentity—here,theattributiondirective—coulduse:

[app.js]



return{





this.person.firstName=

this.person.firstName.toUpperCase();

};

},


template:`


<attributionauthor="articleCtrl.person.firstName"

upper-case-author="articleCtrl.capitalize()">

</attribution>

`

};

})


return{



bindToController:{

author:'=',

upperCaseAuthor:'&'

},

template:`

<png-click="attributionCtrl.upperCaseAuthor()">


</p>`

};

});

Vastlysuperior!Youarestillabletonamespacewithintheclickbinding,buttheowningdirectivecontrollerisprovidingamethodtooutsideentitiesinsteadofjustgivingthemdirectdataaccess.

Howitworks...Whenacontrollerisspecifiedinthedirectivedefinitionobject,onewillbeexplicitlyinstantiatedforeachdirectiveinstancethatiscreated.Thus,itisnaturalforthiscontrollerobjecttoencapsulatethedatathatitownsandforittobedelegatedtheresponsibilityofpassingitsdatatothemembersthatrequireit.

Thefinalimplementationaccomplishesseveralthings:

Improvedtemplatenamespacing:Whenyouusethe$scopepropertiesthatspanmultipledirectivesornestings,youarecreatingascenariowheremultipleentitiescanmanipulateandreaddatawithoutbeingabletoconcretelyreasonaboutwhereitiscomingfromorwhatiscontrollingit.Improvedtestability:Ifyoulookateachofthedirectivesinthefinalimplementation,you'llfindtheyarenottoodifficulttotest.Theattributiondirectivehasnodependenciesotherthanwhatareexplicitlypassedtoit.Encapsulation:Introducingthenotionofdataownershipinyourapplicationaffordsyouamuchmorerobuststructure,betterreusability,andadditionalinsightandcontrolinvolvingpiecesofyourapplicationinteracting.Angular2style:Angular2usesthe@Inputand@Outputannotationsoncomponentdefinitions.Mirroringthisstylewillmaketheprocessoftransitioningtoanapplicationeasier.

There'smore...Youwillnoticethat$scopehasbeenmadetotallyirrelevantintheseexamples.Thisisgoodasthereisnonotionof$scopeinAngular2,whichmeansyouareheadingtowardshavinganupgradeableapplication.Thisisnottosaythat$scopedoesnotstillhaveutilityinanAngular1application,andsurely,therearescenarioswherethisisunavoidable,likewith$scope.$apply().

However,thinkingabouttheapplicationpiecesinthiscomponentstylewillallowyoutobemoreadequatelypreparedtoadoptAngular2conventions.

SeealsoMigratinganapplicationtocomponentdirectivesdemonstrateshowtorefactorAngular1toacomponentstyleImplementingabasiccomponentinAngularJS1.5detailshowtowriteanAngular1componentNormalizingservicetypesgivesinstructiononhowtoalignyourAngular1servicetypesforAngular2compatibility

MigratinganapplicationtocomponentdirectivesInAngular1,thereareseveralbuilt-indirectives,includingngControllerandngInclude,thatdeveloperstendtoleanonwhenbuildingapplications.Whilenotanti-patterns,usingthesefeaturesmovesawayfromhavingacomponent-centricapplication.

Allthesedirectivesareactuallysubsetsofcomponentfunctionality,andtheycanbeentirelyrefactoredout.

Note

Thecode,links,andaliveexamplerelatedtothisrecipeareavailableathttp://ngcookbook.herokuapp.com/1008/.

http://ngcookbook.herokuapp.com/1008/

GettingreadySupposeyourinitialapplicationisasfollows:

[index.html]


<ng-includesrc="'/press_header.html'"></ng-include>

<divng-controller="articleCtrlasarticle">

<h1>{{article.title}}</h1>

<p>Writtenby:{{article.author}}</p>

</div>

<scripttype="text/ng-template"

id="/press_header.html">

<divng-controller="headerCtrlasheader">

<strong>

AngularChronicle-{{header.currentDate|date}}

</strong>

<hr/>

</div>

</script>

</div>

[app.js]


.controller('articleCtrl',function(){

this.title='FoodFightEruptsDuringDiplomaticLuncheon';

this.author='Jake';

})

.controller('headerCtrl',function(){

this.currentDate=newDate();

});

Note

NotethatthisexampleapplicationcontainsalargenumberofverycommonAngular1patterns;youcanseethengControllerdirectivessprinkledthroughout.Also,itusesanngIncludedirectivetoincorporateaheader.Keepinmindthatthesedirectivesarenotinappropriateforawell-formedAngular1application.However,youcandobetter,andthisinvolvesrefactoringtoacomponent-drivendesign.

Howtodoit...Component-drivenpatternsdon'tneedtobefrighteninginappearance.Inthisexample(andforessentiallyallAngular1applications),youcandoacomponentrefactorwhileleavingtheexistingtemplatelargelyintact.

BeginwiththengIncludedirective.Movingthistoacomponentdirectiveissimple—itbecomesadirectivewithtemplateUrlsettothetemplatepath:

[index.html]


<header></header>

<divng-controller="articleCtrlasarticle">



</div>

<scripttype="text/ng-template"

id="/press_header.html">

<divng-controller="headerCtrlasheader">

<strong>


</strong>

<hr/>

</div>

</script>

</div>

[app.js]


.controller('articleCtrl',function(){


this.author='Jake';

})

.controller('headerCtrl',function(){


})

.directive('header',function(){

return{

templateUrl:'/press_header.html'

};

});

Next,youcanalsorefactorngControllereverywhereitappears.Inthisexample,youfindtwoextremelycommonappearancesofngController.Thefirstisattheheadofthepress_header.htmltemplate,actingasthetop-levelcontrollerforthattemplate.Often,thisresultsinneedingasuperfluouswrapperelementjusttohousetheng-controllerattribute.ThesecondisngControllernestedinsideyourprimaryapplicationtemplate,controllingsomearbitraryportionoftheDOM.Bothofthesecanberefactoredtocomponentdirectivesby

reassigningngControllertoadirectivecontroller:

[index.html]


<header></header>

<article></article>

</div>

[app.js]


.directive('header',function(){

return{



},

controllerAs:'header',

template:`

<strong>


</strong>

<hr/>

`

};

})


return{



this.author='Jake';

},

controllerAs:'article',

template:`



`

};

});

Tip

Notethattemplateshereareincludedinthedirectiveforvisualcongruity.Forlargeapplications,itispreferredthatyouusetemplateUrlandlocatethetemplatemarkupinitsownfile.

Howitworks...Generallyspeaking,anapplicationcanberepresentedbyahierarchyofnestedMVCcomponents.ngIncludeandngControlleractassubsetsofacomponentfunctionality,andsoitmakessensethatyouareabletoexpandthemintofullcomponentdirectives.

Intheprecedingexample,theultimateapplicationstructureiscomprisedofonlycomponents.Eachcomponentisdelegateditsowntemplate,controller,andmodel(byvirtueofthecontrollerobjectitself).SticklerswilldisputewhetherornotAngularbelongstotrueMVCstyle,butinthecontextofcomponentrefactoring,thisisirrelevant.Here,youhavedefinedastructurethatiscompletelymodular,reusable,testable,abstractable,andeasilymaintainable.ThisisthestyleofAngular2,andthevalueofthisshouldbeimmediatelyapparent.

There'smore...Analertdeveloperwillnoticethatnoattentionispaidtoscopeinheritance.Thisisadifficultproblemtoapproach,mostlybecausemanyofthepatternsinAngular1aredesignedforamishmashbetweenascopeandcontrollerAs.Angular2isbuiltaroundstrictinputandoutputbetweennestedcomponents;however,inAngular1,scopeisinheritedbydefault,andnesteddirectives,bydefault,haveaccesstotheirencompassingcontrollerobjects.

Thus,totrulyemulateanAngular2style,onemustconfiguretheirapplicationtoexplicitlypassdataandmethodstochildren,similartothecontrollerAsencapsulationrecipe.However,thisdoesnotprecludedirectdataaccesstoancestralcomponentdirectivecontrollers;itmerelywagsafingeratitsinceitaddsadditionaldependencies.

SeealsoComponentizingdirectivesusingcontrollerAsencapsulationshowsyouasuperiormethodoforganizingAngular1directivesImplementingabasiccomponentinAngularJS1.5detailshowtowriteanAngular1componentNormalizingservicetypesgivesinstructiononhowtoalignyourAngular1servicetypesforAngular2compatibility

ImplementingabasiccomponentinAngularJS1.5The1.5releaseofAngularJSintroducedanewtool:thecomponent.Whileitisn'texactlysimilartotheconceptoftheAngular2component,itdoesallowyoutobuilddirective-stylepiecesinanexplicitlycomponentizedfashion.

Note



GettingreadySupposeyourapplicationhadadirectivedefinedasfollows:

[index.html]


<article></article>

</div>

[app.js]



return{



this.title='PoliceBustIllegalSnailRacingRing';




};

},


template:`




</attribution>

`

};

})


return{



bindToController:{

author:'=',

upperCaseAuthor:'&'

},

template:`



</p>`

};

});

Howtodoit...SincethisapplicationisalreadyorganizedaroundthecontrollerAsencapsulation,youcanmigrateittousethecomponent()definitionintroducedintheAngular1.5release.

Componentsacceptanobjectdefinitionsimilartoadirective,buttheobjectdoesnotdemandtobereturnedbyafunction—anobjectliteralisallthatisneeded.ComponentsutilizethebindingspropertyinthisobjectdefinitionobjectinthesamewaythatbindToControllerworksfordirectives.Withthis,youcaneasilyintroducecomponentsinthisapplicationinsteadofdirectives:

[index.html]


<article></article>

</div>

[app.js]


.component('article',{







};

},


template:`




</attribution>`

})

.component('attribution',{



bindings:{

author:'=',

upperCaseAuthor:'&'

},

template:`



</p>

`

});

Howitworks...Noticethatsinceyourcontroller-centricdataorganizationmatcheswhatacomponentdefinitionexpects,notemplatemodificationsarenecessary.Components,bydefault,willutilizeanisolatescope.What'smore,theywillnothaveaccesstothealiasofthesurroundingcontrollerobjects,somethingthatcannotbesaidforcomponent-styledirectives.Thisencapsulationisanimportantofferingofthenewcomponentfeature,asithasdirectparitytohowcomponentsoperateinAngular2.

There'smore...Sinceyouhavenowentirelyisolatedeachindividualcomponent,thereisonlyasinglecontrollerobjecttodealwithineachtemplate.Thus,Angular1.5automaticallyprovidesaconvenientaliasforthecomponent'scontrollerobject,namely—$ctrl.ThisisprovidedwhetherornotacontrollerAsaliasisspecified.Therefore,afurtherrefactoringyieldsthefollowing:

[index.html]


<article></article>

</div>

[app.js]









};

},

template:`

<h1>{{$ctrl.title}}</h1>

<attributionauthor="$ctrl.person.firstName"

upper-case-author="$ctrl.capitalize()">

</attribution>

`

})

.component('attribution',{


bindings:{

author:'=',

upperCaseAuthor:'&'

},

template:`

<png-click="$ctrl.upperCaseAuthor()">

Writtenby:{{$ctrl.author}}

</p>

`

});

SeealsoComponentizingdirectivesusingcontrollerAsencapsulationshowsyouasuperiormethodoforganizingAngular1directivesMigratinganapplicationtocomponentdirectivesdemonstrateshowtorefactorAngular1toacomponentstyleNormalizingservicetypesgivesinstructiononhowtoalignyourAngular1servicetypesforAngular2compatibility

NormalizingservicetypesAngular1developerswillbequitefamiliarwiththefactory/service/providertrifecta.Inmanyways,thishasgonelargelyunalteredinAngular2conceptually.However,intheinterestofupgradinganexistingapplication,thereisonethingthatshouldbedonetomakethemigrationaseasyaspossible:eliminatefactoriesandreplacethemwithservices.

Note



GettingreadySupposeyouhadasimpleapplicationasfollows:

[index.html]


<article></article>

</div>

[app.js]


.factory('ArticleData',function(){

vartitle='IncumbentSenatorOustedbyStalkofBroccoli';

return{

getTitle:function(){

returntitle;

},

author:'Jake'

};

})


controller:function(ArticleData){

this.title=ArticleData.getTitle();

this.author=ArticleData.author;

},

template:`


<p>Writtenby:{{$ctrl.author}}</p>

`

});

Howtodoit...Angular2isclass-based,anditincludesitsservicetypesaswell.Theexampleheredoesnothaveaservicetypethatiscompatiblewithaclassstructure.Soitmustbeconverted.Thankfully,thisisquiteeasytodo:

[index.html]


<article></article>

</div>

[app.js]


.service('ArticleData',function(){

vartitle='IncumbentSenatorOustedbyStalkofBroccoli';

this.getTitle=function(){

returntitle;

};

this.author='Jake';

})


controller:function(ArticleData){

this.title=ArticleData.getTitle();

this.author=ArticleData.author;

},

template:`


<p>Writtenby:{{$ctrl.author}}</p>

`

});

Howitworks...Youstillwanttokeepthenotionoftitleprivate,butyoualsowanttomaintaintheAPIthattheinjectedservicetypeisproviding.Servicesaredefinedbyafunctionthatactsasaconstructor,andaninstancecreatedfromthisconstructoriswhatisultimatelyinjected.Here,youaresimplymovinggetTitle()andauthortobedefinedonthethiskeyword,whichtherebymakesitapropertyonallinstances.Notethattheuseinthecomponentandtemplatedoesnotchangeinanyway,anditshouldn't.

There'smore...Thesimplesttoimplementservicetypes,Angular1factorieswereoftenusedfirstbymanydevelopers,includingmyself.Somedevelopersmighttakeoffenseatthefollowingclaim,butIdon'tthinktherewaseveragoodreasonforbothfactoriesandservicestoexist.Bothhaveahighdegreeofredundancy,andifyoudigdownintotheAngularsourcecode,youwillseethattheyessentiallyconvergetothesamemethods.

Whyservicesoverfactoriesthen?ThenewworldofJavaScript,ES6,andTypeScriptisbeingbuiltaroundclasses.Theyareafarmoreelegantwayofexpressingandorganizinglogic.Angular1servicesareanimplementationofprototype-basedclasses,whichwhenusedcorrectlyfunctioninessentiallythesamewayasformalES6/TypeScriptclasses.Ifyoustophere,youwillhavemodifiedyourservicestobemoreextensibleandcomprehensible.Ifyouintendtoupgrade,youwillfindthatAngular1serviceswillcleanlyupgradetoAngular2services.

SeealsoComponentizingdirectivesusingcontrollerAsencapsulationshowsyouasuperiormethodfororganizingAngular1directivesMigratinganapplicationtocomponentdirectivesdemonstrateshowtorefactorAngular1toacomponentstyleImplementingabasiccomponentinAngularJS1.5detailshowtowriteanAngular1component

ConnectingAngular1andAngular2withUpgradeModuleAngular2comeswiththeabilitytoconnectittoanexistingAngular1application.ThisisobviouslyadvantageoussincethiswillallowyoutoutilizeexistingcomponentsandservicesinAngular1intandemwithAngular2'scomponentsandservices.UpgradeModuleisthetoolthatissupportedbyAngularteamstoaccomplishsuchafeat.

Note

Thecode,links,andaliveexampleinrelationtothisrecipeareavailableathttp://ngcookbook.herokuapp.com/4137/.


GettingreadySupposeyouhadaverysimpleAngular1applicationasfollows:

[index.html]

<!DOCTYPEhtml>

<html>

<head>



<scriptsrc="angular.js"></script>

</head>

<body>

<divng-app="hybridApp"

ng-init="val='Angular1bootstrappedsuccessfully!'">

{{val}}

</div>

</body>

</html>

ThisapplicationinterpolatesavaluesetinanAngularexpressionsoyoucanvisuallyconfirmthattheapplicationhasbootstrappedandisworking.

Howtodoit...Beginbydeclaringthetop-levelangularmoduleinsideitsownfile.Insteadofusingascripttagtofetchtheangularmodule,requireAngular1,importit,andcreatetherootAngular1module:

[ng1.module.ts]

import'angular'

exportconstNg1AppModule=angular.module('Ng1AppModule',[]);

Angular2shipswithanupgrademoduleoutofthebox,whichisprovidedinsideupgrade.js.ThetwoframeworkscanbeconnectedwithUpgradeModule.

Note

ThisrecipeutilizesSystemJSandTypeScript,thespecificationsforwhichlieinsideaverycomplicatedconfigfile.Thisisdiscussedinalaterchapter,sodon'tworryaboutthespecifics.Fornow,youarefreetoassumethefollowing:

SystemJSisconfiguredtocompileTypeScript(.ts)filesontheflySystemJSisabletoresolvetheimportandexportstatementsinTypeScriptfilesSystemJSisabletoresolveAngular1and2libraryimports

Angular2requiresatop-levelmoduledefinitionaspartofitsbaseconfiguration:

[app/ng2.module.ts]

import{NgModule}from'@angular/core';

import{BrowserModule}from'@angular/platform-browser';

import{UpgradeModule}from'@angular/upgrade/static';

import{RootComponent}from'./root.component';

@NgModule({

imports:[

BrowserModule,

UpgradeModule,

],

bootstrap:[

RootComponent

],

declarations:[

RootComponent

]

})

exportclassNg2AppModule{

constructor(publicupgrade:UpgradeModule){}

}

exportclassAppModule{}

Tip

Thereasonwhythismoduledefinitionexiststhiswayisn'tcriticalforunderstandingthisrecipe.Angular2modulesarecoveredinChapter7,Services,DependencyInjection,andNgModule.

CreatetherootcomponentoftheAngular2application:

[app/root.component.ts]

import{Component}from'@angular/core';

@Component({

selector:'root',

template:`

<p>Angular2bootstrappedsuccessfully!</p>

`

})

exportclassRootComponent{}

SinceAngular2willoftenbootstrapfromatop-levelfile,createthisfileasmain.tsandbootstraptheAngular2module:

[main.ts]

import{platformBrowserDynamic}

from'@angular/platform-browser-dynamic';

import{Ng1AppModule}from'./app/ng1.module';


platformBrowserDynamic()

.bootstrapModule(Ng2AppModule);

ConnectingAngular1toAngular2

Don'tuseanng-apptobootstraptheAngular1application;instead,dothisafteryoubootstrapAngular2:

[main.ts]





platformBrowserDynamic()

.bootstrapModule(Ng2AppModule)

.then(ref=>{

ref.instance.upgrade

.bootstrap(document.body,[Ng1AppModule.name]);

});

Withthis,you'llbeabletoremoveAngular1'sJSscript,theng-appdirective,andaddintherootelementoftheAngular2app:

[index.html]

<!DOCTYPEhtml>

<html>

<head>


<scriptsrc="zone.js"></script>

<scriptsrc="reflect-metadata.js"></script>

<scriptsrc="system.js"></script>

<scriptsrc="system-config.js"></script>

</head>

<body>

<divng-init="val='Angular1bootstrappedsuccessfully!'">

{{val}}

</div>

<root></root>

</body>

</html>

Note

ThenewscriptslistedherearedependenciesofanAngular2application,butunderstandingwhatthey'redoingisn'tcriticalforunderstandingthisrecipe.Thisisexplainedlaterinthebook.

Withallthis,youshouldseeyourAngular1applicationtemplatecompileandtheAngular2componentrenderproperlyagain.ThismeansthatyouaresuccessfullyrunningAngular1andAngular2frameworkssidebyside.

Howitworks...Makenomistake,whenyouuseUpgradeModule,youcreateanAngular1andAngular2apponthesamepageandconnectthemtogether.Thisadapterinstancewillallowyoutoconnectpiecesfromeachframeworkandusetheminharmony.

Morespecifically,thiscreatesanAngular1applicationatthetoplevelandallowsyoutousespiecesofanAngular2applicationinsideit.

There'smore...Whileusefulforexperimentationandupgradingpurposes,thisshouldnotbeasolutionthatanyapplicationshouldrelyoninaproductioncontext.Youhaveeffectivelydoubledtheframeworkpayloadsizeandintroducedadditionalcomplexityinanexistingapplication.AlthoughAngular2isafarmoreperformantframework,donotexpecttohavethesamepristineresultswiththeUpgradeModulecross-pollination.

Thatsaid,asyouwillseeinsubsequentrecipes,youcannowuseAngular2componentsinanAngular1applicationusingtheadaptertranslationmethods.

SeealsoDowngradingAngular2componentstoAngular1directiveswithdowngradeComponentdemonstrateshowtouseanAngular2componentinsideanAngular1applicationDowngradeAngular2providerstoAngular1serviceswithdowngradeInjectable,whichdemonstrateshowtouseanAngular2serviceinsideanAngular1application

DowngradingAngular2componentstoAngular1directiveswithdowngradeComponentIfyouhavefollowedthestepsinConnectingAngular1andAngular2withUpgradeModule,youshouldnowhaveahybridapplicationthatiscapableofsharingdifferentelementswiththeopposingframework.

Tip

IfyouareunfamiliarwithAngular2components,itisrecommendedthatyougothroughthecomponentschapterbeforeyouproceed.

ThisrecipewillallowyoutofullyutilizeAngular2componentsinsideanAngular1template.

Note



GettingreadySupposeyouhadthefollowingAngular2componentthatyouwantedtouseinanAngular1application:

[app/article.component.ts]

import{Component,Input}from'@angular/core';

@Component({

selector:'ng2-article',

template:`

<h1>{{title}}</h1>

<p>Writtenby:{{author}}</p>

`

})

exportclassArticleComponent{

@Input()author:string

title:string='UnicycleJoustingRecognizedasOlympicSport';

}

BeginbycompletingtheConnectingAngular1andAngular2withUpgradeModulerecipe.

Howtodoit...Angular1hasnocomprehensionofhowtoutilizeAngular2components.TheexistingAngular2frameworkwilldutifullyrenderitifgiventheopportunity,butthedefinitionitselfmustbeconnectedtotheAngular1frameworksothatitmayberequestedwhenneeded.

Beginbyaddingthecomponentdeclarationstothemoduledefinition;thisisusedtolinkthetwoframeworks:

[app/app.module.ts]





import{ArticleComponent}from'./article.component';

@NgModule({

imports:[

BrowserModule,

UpgradeModule,

],

declarations:[

RootComponent,

ArticleComponent

],

bootstrap:[

RootComponent

]

})



}

ThisconnectsthecomponentdeclarationtotheAngular2context,butAngular1stillhasnoconceptofhowtointerfacewithit.Forthis,you'llneedtousedowngradeComponent()todefinetheAngular2componentasanAngular1directive.GivetheAngular1directiveadifferentHTMLtagtorenderinsidesoyoucanbecertainthatit'sAngular1doingtherenderingandnotAngular2:

[main.ts]


import{downgradeComponent}from'@angular/upgrade/static';

import{Ng1AppModule}from'./ng1.module';

@Component({


template:`

<h1>{{title}}</h1>


`

})




}

Ng1AppModule.directive(

'ng1Article',

downgradeComponent({component:ArticleComponent}));

Finally,sincethiscomponenthasaninput,you'llneedtopassthisvalueviaabindingattribute.EventhoughthecomponentisstillbeingdeclaredasanAngular1directive,you'llusetheAngular2bindingsyntax:

[index.html]

<!DOCTYPEhtml>

<html>

<head>




<scriptsrc="system.js"></script>


</head>

<body>

<divng-init="authorName='JakeHsu'">

<ng1-article[author]="authorName"></ng1-article>

</div>

<root></root>

</body>

</html>

Theinputandoutputmustbeexplicitlydeclaredatthetimeofconversion:



import{downgradeComponent}from'@angular/upgrade/static';

import{Ng1AppModule}from'./ng1.module';

@Component({


template:`

<h1>{{title}}</h1>


`

})




}

Ng1AppModule.directive(

'ng1Article',

downgradeComponent({

component:ArticleComponent,

inputs:['author']

}));

Theseareallthestepsrequired.Ifdoneproperly,youshouldseethecomponentrenderalongwiththeauthor'snamebeinginterpolatedinsidetheAngular2componentthroughAngular1'sng-initdefinition.

Howitworks...YouaregivingAngular1theabilitytodirectAngular2toacertainelementintheDOMandsay,"Ineedyoutorenderhere."Angular2stillcontrolsthecomponentviewandoperation,andineverysense,themainthingwereallycareaboutisafullAngular2componentadaptedforuseinanAngular1template.

Tip

downgradeComponent()takesanobjectspecifyingthecomponentasanargumentandreturnsthefunctionthatAngular1isexpectingforthedirectivedefinition.

SeealsoConnectingAngular1andAngular2withUpgradeModuleshowsyouhowtorunAngular1and2frameworkstogetherDowngradeAngular2providerstoAngular1serviceswithdowngradeInjectabledemonstrateshowtouseanAngular2serviceinsideanAngular1application

DowngradeAngular2providerstoAngular1serviceswithdowngradeInjectableIfyouhavefollowedthestepsinConnectingAngular1andAngular2withUpgradeModule,youshouldnowhaveahybridapplicationthatiscapableofsharingdifferentelementswiththeopposingframework.IfyouareunfamiliarwithAngular2providers,itisrecommendedthatyougothroughthedependencyinjectionchapterbeforeyouproceed.

Likewithtemplatedcomponents,interchangeabilityisalsoofferedtoservicetypes.ItispossibletodefineaservicetypeinAngular2andtheninjectitintoanAngular1context.

Note



GettingreadyBeginwiththecodewritteninConnectingAngular1andAngular2withUpgradeModule.

Howtodoit...First,definetheserviceyouwouldliketoinjectintoanAngular1component:

[app/article.service.ts]

import{Injectable}from'@angular/core';

@Injectable()

exportclassArticleService{

article:Object={

title:'ResearchShowsMoonNotActuallyMadeofCheese',

author:'JakeHsu'

};

}

Next,definetheAngular1componentthatshouldinjectit:


exportconstng1Article={

template:`


<p>{{article.author}}</p>

`,

controller:(ArticleService,$scope)=>{

$scope.article=ArticleService.article;

}

};

ArticleServicewon'tbeinjectedyetthough,sinceAngular1hasnoideathatthisserviceexists.Doingthisisverysimple,however.First,you'lllisttheserviceproviderintheAngular2moduledefinitionasyounormallywould:

[app/ng2.module.ts]





import{ArticleService}from'./article.service';

@NgModule({

imports:[

BrowserModule,

UpgradeModule,

],

declarations:[

RootComponent

],

providers:[

ArticleService

],

bootstrap:[

RootComponent

]

})



}

Still,Angular1doesnotunderstandhowtousetheservice.

InthesamewayyouconvertanAngular2componentdefinitionintoanAngular1directive,convertanAngular2serviceintoanAngular1factory.UsedowngradeInjectableandaddtheAngular1componentandtheconvertedservicetotheAngular1moduledefinition:

[app/ng1.module.ts]

import'angular';

import{ng1Article}from'./article.component';


import{downgradeInjectable}from'@angular/upgrade/static';

exportconstNg1AppModule=angular.module('Ng1AppModule',[])

.component('ng1Article',ng1Article)

.factory('ArticleService',downgradeInjectable(ArticleService));

That'sall!YoushouldbeabletoseetheAngular1componentrenderwiththedatapassedfromtheAngular2service.

SeealsoConnectingAngular1andAngular2withUpgradeModuleshowsyouhowtorunAngular1and2frameworkstogetherDowngradingAngular2componentstoAngular1directiveswithdowngradeComponentdemonstrateshowtouseanAngular2componentinsideanAngular1application

Chapter2.ConqueringComponentsandDirectivesYourobjectiveistoiteratethroughthisanddisplaythearticletitleonlyifitissetasactive.Thischapterwillcoverthefollowingrecipes:

UsingdecoratorstobuildandstyleasimplecomponentPassingmembersfromaparentcomponenttoachildcomponentBindingtonativeelementattributesRegisteringhandlersonnativebrowsereventsGeneratingandcapturingcustomeventsusingEventEmitterAttachingbehaviortoDOMelementswithDirectivesProjectingnestedcontentusingngContentUsingngForandngIfstructuraldirectivesformodel-basedDOMcontrolReferencingelementsusingtemplatevariablesAttributepropertybindingUtilizingcomponentlifecyclehooksReferencingaparentcomponentfromachildcomponentConfiguringmutualparent-childawarenesswithViewChildandforwardRefConfiguringmutualparent-childawarenesswithContentChildandforwardRef

IntroductionDirectivesasyoucametoknowtheminAngular1havebeendoneawaywith.Intheirplace,wehavetwonewentities:componentsandthenewversionofdirectives.Angular2applicationsarenowcomponent-driven;withfurtherexposure,youwilldiscoverwhythisstyleissuperior.

Muchofthesyntaxisentirelynewandmayseemstrangeatfirst.Fearnot!TheunderpinningsoftheAngular2styleareelegantandmarvelousoncecompletelyunderstood.

UsingdecoratorstobuildandstyleasimplecomponentWhenwritinganapplicationcomponentinTypeScript,thereareseveralnewparadigmsthatyoumustbecomefamiliarandcomfortablewith.Thoughpossiblyintimidatinginitially,youwillfindthatyou'llbeabletocarryovermuchofyourcomprehensionofAngular1directives.

Note

Thecodeandaliveexampleofthisareavailableathttp://ngcookbook.herokuapp.com/6577/.


GettingreadyOneofthesimplestimaginablecomponentswecanbuildisatemplateelementthatinterpolatessomevaluesintoitstemplate.InAngular1,onewaythiscouldbeachievedwasbycreatinganelementdirective,attachingsomedatatothescopeinsidethelinkfunction,andatemplatethatwouldreferencethedata.Iselectedthisdescriptionspecificallybecausenearlyallthoseconceptshavebeenbinned.

Supposeyouwanttocreateasimplearticlecomponentwithapseudotemplateasfollows:

<p>{{date}}</p>

<h1>{{title}}</h1>


YouwanttocreateacomponentthatwillliveinsideitsownHTMLtag,renderthetemplate,andinterpolatethevalues.

Howtodoit...TheelementalbuildingblockofAngular2applicationsisthecomponent.Thiscomponentcouldgenerallybedefinedwithtwopieces:thecoreclassdefinitionandtheclassdecoration.

Writingtheclassdefinition

AllAngular2componentsbeginasaclass.Thisclassisusedtoinstantiatethecomponent,andanydatarequiredinsidethecomponenttemplatewillbeaccessiblefromtheclass'sproperties.Thus,thefoundationalclassforthecomponentwouldappearasfollows:



currentDate:date;

title:string;

author:string;

constructor(){


this.title=`

FlightSecurityRestrictionstoInclude

Insults,MeanFaces

`;

this.author='Jake';

}

};

HereareafewthingstonoteforthosewhoarenewtoTypeScriptorES6ingeneral:

Youwillnotetheclassdefinitionisprefixedwithanexportkeyword.ThisisadherencetothenewES6moduleconvention,whichnaturallyisalsopartofTypeScript.AssumingtheArticleclassisdefinedinthefoo.tsfile,itcanbeimportedtoadifferentmoduleusingtheimportkeyword,andthepathtothatmodulewouldbeimport{Article}from'./foo';(thisassumesthattheimportingfileisinthesamedirectoryasfoo.ts).ThetitledefinitionusesthenewES6templatestringsyntax,apairofbackticks(``)insteadofthetraditionalsetofquotes('').Youwillfindyoubecomequitefondofthis,asitmeansthe''+''+''messinessformerlyusedtodefinemultilinetemplateswouldnolongerbenecessary.Allthepropertiesofthisclassaretyped.TypeScript'stypingsyntaxtakestheformofpropertyName:propertyType=optionalInitValue.JavaScriptis,ofcourse,alooselytypedlanguage,andJavaScriptiswhatthebrowserisinterpretinginthiscase.However,writingyourapplicationinTypeScriptallowsyoutoutilizetypesafetyatcompiletime,whichwillallowyoutoavoidundesirableandunanticipatedbehavior.AllES6classescomewithapredefinedconstructor()method,whichisinvokeduponinstantiation.Here,youareusingtheconstructortoinstantiatethepropertiesoftheclass,whichisaperfectlyfinestrategyformemberinitialization.Havingthememberproperty

definitionoutsidetheconstructorisallowed,sinceitisusefulforaddingtypestoproperties;thus,hereyouaresimplyobviatingtheuseoftheconstructorsinceyouareabletoaddatypeandassignthevalueinthesameline.Amoresuccinctstylecouldbeasfollows:



currentDate:date=newDate();

title:string=`


Insults,MeanFaces

`;

author:string='Jake';

}

TheTypeScriptcompilerwillautomaticallymovethememberinitializationprocessinsidetheclassconstructor,sothisversionandthepreviousonearebehaviorallyidentical.

Writingthecomponentclassdecorator

Althoughyouhavecreatedaclassthathasinformationassociatedwithit,itdoesnotyethaveanywaytointerfacewiththeDOM.Furthermore,thisclassisyettobeassignedwithanymeaninginthecontextofAngular2.Youcanaccomplishthiswithdecorators.

Note

DecoratorsareafeatureofTypeScriptbutnotbyanymeansuniquetothelanguage.Pythondevelopers,amongmanyothers,shouldbequitefamiliarwiththeconceptofclassmodulationviaexplicitdecoration.Generallyspeaking,itallowsyoutohavearegularizedmodificationofthedefinedclassesusingseparatelydefineddecorators.However,inAngular2,youwilllargelybeutilizingthedecoratorsprovidedtoyoubytheframeworktodeclarethevariousframeworkelements.Decoratorssuchas@ComponentaredefinedintheAngularsourcecodeasaComponentfunction,andthefunctionisappliedasadecoratorusingthe@symbol.

An@prefixsignalsthattheimportedfunctionshouldbeappliedasadecorator.Thesedecoratorsarevisuallyobviousbutwillusuallynotexistbythemselvesorwithanemptyobjectliteral.ThisisbecauseAngular2decoratorsaregenerallymadeusefulbytheirdecoratormetadata.ThisconceptcanbemademoreconcreteherebyusingthepredefinedComponentdecorator.

NothingisavailableforfreeinAngular2.Inordertousethecomponentdecorator,itmustbeimportedfromtheAngular2coremoduleintothemodulethatwishestouseit.YoucanthenprependthisComponenttotheclassdefinition:



@Component({})



title:string=`


Insults,MeanFaces

`;


}

Asmentionedbefore,the@ComponentdecoratoracceptsaComponentMetadataobject,whichintheprecedingcodeisjustanemptyobjectliteral(notethattheprecedingcodewillnotcompile).Conceptually,thismetadataobjectisverysimilartothedirectivedefinitionobjectinAngular1.Here,youwanttoprovidethedecoratormetadataobjectwithtwoproperties,namelyselectorandtemplate:



@Component({

selector:'article',

template:`


<h1>{{title}}</h1>


`

})



title:string=`


Insults,MeanFaces

`;


}

NotethatselectoristhestringthatwillbeusedtofindwherethecomponentshouldbeinsertedintheDOM,andtemplateisobviouslythestringifiedHTMLtemplate.

Withallthis,youwillbeabletoseeyourarticlecomponentinactionwiththe<article></article>tag.

Howitworks...TheclassdefinitionhassupplantedtheAngular1conceptofhavingacontroller.Thecomponentinstancesofthisclasshavememberpropertiesthatcanbeinterpolatedandboundintothetemplate,similarto$scopeinAngular1.

Inthetemplate,theinterpolationanddatabindingprocessesseemtooccurmuchinthesameway,theydidinAngular1.Thisisnotactuallythecase,whichisvisitedingreaterdetaillaterinthischapter.Thebuilt-indatemodifier,whichresemblesanAngular1filter,isnowdubbedwithapipealthoughitworksinaverysimilarfashion.

TheselectormetadatapropertyisastringrepresentingaCSSselector.Inthisdefinition,youtargetalltheoccurrencesofanarticletag,buttheselectorspecificityanddetailisofcourseabletohandleagreatdealofadditionalcomplexity.Usethistoyouradvantage.

There'smore...TheconceptthatmustbeinternalizedforAngular2neophytesisthetotalencapsulationofacomponent.ThisbookwillgointofurtherdetailaboutthedifferentabilitiesoftheComponentMetadataobject,buttheparadigmtheyandallclassdecoratorsintroduceistheconceptthatAngular2componentsareself-describing.Byexaminingtheclassdefinition,youcanwhollyreasonthedata,service,class,andinjectabledependencies.InAngular1,thiswasnotpossiblebecauseofthe"scopesoup"pattern.

OnecouldarguethatinAngular1,CSSstylingwasasecond-classcitizen.Thisisnolongerthecasewithcomponents,asthemetadataobjectoffersrobustsupportforcomplexstyling.Forexample,toitalicizetheauthorinyourArticlecomponent,usethiscode:



@Component({

selector:'article',

template:`


<h1>{{title}}</h1>


`,

styles:[`

h3{

font-style:italic;

}

`]

})



title:string=`


Insults,MeanFaces

`;


}

Angular2willusethisstylespropertyandcompileitintoageneratedstylesheet,whichitwillthenapplytoonlythiscomponent.YoudonothavetoworryabouttherestoftheHTMLh3tagsbeinginadvertentlystyled.ThisisbecauseAngular2'sgeneratedstylesheetwillensurethatonlythiscomponent—anditschildren—aresubjecttotheCSSruleslistedinthemetadataobject.

Note

Thisisintendedtoemulatethetotalmodularityofwebcomponents.However,sincewebcomponentsdonotyethaveuniversalsupport,Angular2'sdesignessentiallyperformsapolyfill

forthisbehavior.

SeealsoPassingmembersfromaparentcomponentintoachildcomponentgoesthroughthebasicsofdownwarddataflowbetweencomponentsUsingngForandngIfstructuraldirectivesformodel-basedDOMcontrolinstructsyouonhowtoutilizesomeofAngular2'scorebuilt-indirectivesUtilizingcomponentlifecyclehooksgivesanexampleofhowyoucanintegratewithAngular2'scomponentrenderingflow

PassingmembersfromaparentcomponentintoachildcomponentWiththedepartureoftheAngular1.xconceptof$scopeinheritance,mentally(partiallyorentirely)remodelinghowinformationwouldbepassedaroundyourapplicationisamust.Initsplace,youhaveanentirelynewsystemofpropagatinginformationthroughouttheapplication'shierarchy.

Gonealsoistheconceptofdefaultingtobidirectionaldatabinding.Althoughitmadeforanapplicationthatwassimplertoreasonabout,bidirectionaldatabindingincursanunforgivablyexpensivedragonperformance.Thisnewsystemoperatesinanasymmetricfashion:membersarepropagateddownwardsthroughthecomponenttree,butnotupwardsunlessexplicitlyperformed.

Note

Thecode,links,andaliveexampleofthisareavailableathttp://ngcookbook.herokuapp.com/6543/.


GettingreadySupposeyouhadasimpleapplicationthatintendedto(butcurrentlycannot)passdatafromaparentArticleComponenttoachildAttributionComponent:

[app/components.ts]


@Component({

selector:'attribution',

template:`


`

})

exportclassAttributionComponent{

author:string;

}

@Component({

selector:'article',

template:`

<h1>{{title}}</h1>


`

})


title:string='BelchingChoirBeginsWorldTour';

name:string='Jake';

}

Howtodoit...Inthisinitialimplementation,thecomponentsdefinedherearenotyetawareofeachother,andthe<attribution></attribution>tagwillremaininertintheDOM.Thisisagoodthing!Itmeansthesetwocomponentsarecompletelydecoupled,andyouareabletoonlyintroduceconnectionlogicasnecessary.

Connectingthecomponents

First,sincethe<attribution></attribution>tagappearsinsidetheArticlecomponent,youmustmakethecomponentawareoftheexistenceofAttributionComponent.ThisisaccomplishedbyintroducingthecomponentinthemoduleinwhichArticleComponentisalsodeclared:

[app/app.module.ts]



import{ArticleComponent,AttributionComponent}

from'./components';

@NgModule({

imports:[

BrowserModule

],

declarations:[

ArticleComponent,

AttributionComponent

],

bootstrap:[

ArticleComponent

]

})


Note

Forthepurposeofthisrecipe,don'tconcernyourselfjustyetwiththedetailsofwhatNgModuleisdoing.Intheexampleinthisrecipe,theentireapplicationisjustaninstanceofArticleComponentwithAttributionComponentinsideit.So,allthecomponentdeclarationscanbedoneinsidethesamemodule.

Withthis,youwillseethatArticleComponentisabletomatchthe<attribution></attribution>tagwiththeAttributionComponentdefinition.

Note

Insideasinglemodule,theorderofthedefinitioncouldmatteralot.ES6andTypeScriptclass

declarationsarenothoisted,soyoucannotreferencethematallbeforethedeclarationwithoutgeneratingerrors.Inthisrecipe,sinceArticleComponentisdefinedbeforeAttributionComponent,theformercannotdirectlyreferencethelatterinsideitsdefinition.

IfyouweretoinsteaddefineAttributionComponentinsideaseparatemoduleandimportitwiththemoduleloader,theorderissuebecomesirrelevant.Asyouwillnotice,thisisoneoftheexcellentbenefitsofhavingahighlymodularapplicationstructure.

OnecaveattothisisthatAngulardoesmakeitpossibletodoout-of-orderclassreferencesusingaforwardRef.However,ifsolvingtheorderproblemispossiblebysplittingitintoseparatemodules,thatispreferredoverforwardRef.

Thisbeingthecase,goaheadandsplityourcomponentfileintotwoseparatemodulesandimportthemaccordingly:

[app/app.module.ts]




import{AttributionComponent}from'./attribution.component';

@NgModule({

imports:[

BrowserModule

],

declarations:[

ArticleComponent,

AttributionComponent

],

bootstrap:[

ArticleComponent

]

})




@Component({

selector:'article',

template:`

<h1>{{title}}</h1>


`

})



name:string='Jake';

}

[app/attribution.component.ts]


@Component({


template:`


`

})


author:string;

}

Declaringinputs

SimilartotheAngular1directive'sscopepropertyobject,inAngular2,youmustdeclarethemembersoftheparentcomponenttobringthemdowntothechildcomponent.InAngular1,thiscouldbedoneimplicitlywithaninherited$scope,butthisisnolongerthecase.Angular2componentinputsmustbeexplicitlydefined.

Tip

AnotherimportantdifferencebetweenAngular1andAngular2isthat@InputinAngular2isaunidirectionaldatabindingfeature.Dataupdateswillflowdownwards,andtheparentwillnotbeupdatedunlessexplicitlynotified.

TheprocessofdeclaringinputsinachildcomponentisdonethroughtheInputdecorator,butthedecoratorisinvokedinsidetheclassdefinitioninsteadofdoingsoinfrontofit.Inputisimportedfromthecoremoduleandinvokedinsidetheclassdefinitionthatispairedwithamember.

Note

Don'tletthisconfuseyou.Theimplementationoftheactualdecoratingfunctionishiddenfromyousinceitisimportedasasingletarget,sodon'tthinkmuchaboutwhatthe@Input()syntaxisdoing.ThereisadefinedInputfunctionintheAngularsource,andyouarecertainlyinvokingthismethodhere.However,foryourpurposes,itismerelydeclaringthememberthatfollowsitastheonethatwillbepassedinexplicitlyfromtheparentcomponent.YouuseitinthesamewayastheComponentdecorator,justinadifferentplace.

[app/attribution.component.ts]


@Component({


template:`


`

})


@Input()author:string;

}

Next,youmustpassthevalueboundtothechildcomponenttagtotheparentcomponent.Inthecontextofthisrecipe,youwanttopassthenamepropertyoftheArticlecomponentobjecttotheauthorpropertyoftheAttributioncomponentobject.Onewayofaccomplishingthisisbyusingthesquarebracketnotationonthetagattribute,whichspecifiestheattributestringasbounddata:



@Component({

selector:'article',

template:`

<h1>{{title}}</h1>

<attribution[author]="name"></attribution>

`

})



name:string='Jake';

}

Withthis,youhavesuccessfullypassedamemberpropertydown,fromaparenttoachildcomponent!

Howitworks...Recallthatthestartingpointofthisexamplewasthatwehadtwocomponentsthatdidn'tknowtheotherexists,eventhoughtheyaredefinedandexportedinsidethesamemodule.Theprocessdemonstratedinthisrecipeistoprovidethechildcomponenttotheparentcomponent,configurethechildcomponenttoexpectthatamemberwillbeboundtoaninputattribute,andfinallyprovidethatmemberinthetemplateoftheparentcomponent.

There'smore...Somepeoplehaveanissuewiththesquarebracketnotation.ItisvalidHTML,butsomedevelopersfeelitisunintuitiveandlooksodd.

Tip

Additionally,thebracketnotationisnotvalidXML.DevelopersusingHTMLgeneratedthroughXSLTwillnotbeabletoutilizethenewsyntax.Fortunately,everywherethenewAngular2syntaxutilizesnewnew[]or()syntax,thereisanequivalentsyntaxthattheframeworksupportswhichwillbehaveidentically.

Insteadofusingpairsofsquarebrackets,youcanprefixtheattributenamewithbind-anditwillbehaveidentically:



@Component({

selector:'article',

template:`

<h1>{{title}}</h1>

<attributionbind-author="name"></attribution>

`

})



name:string='Jake';

}

Angularexpressions

Notethatthevalueoftheattributenameisnotastringbutanexpression.Angularknowshowtoevaluatethisexpressioninthecontextoftheparentcomponent.AsisthecasewithAngularexpressionsthough,youaremorethanwelcometoprovideastaticvalueandAngularwillhappilyevaluateitandprovideittothechildcomponent.

Forexample,thefollowingchangewouldhardcodethechildcomponenttoassignthestring"MikeSnifferpippets"astheauthorproperty:



import{AttributionComponent}from'./attribution.component';

@Component({

selector:'article',

template:`

<h1>{{title}}</h1>

<attribution[author]="'MikeSnifferpippets'"></attribution>

`,

directives:[AttributionComponent]

})



name:string='Jake';

}

Unidirectionaldatabinding

Thedatabindingyouhavesetupinthisrecipeisactuallyunidirectional.Morespecifically,changesintheparentcomponentmemberwillpropagatedownwardstothechildcomponent,butchangestothechildcomponentmemberwillnotpropagateupwards.Thiswillbeexploredfurtherinanotherrecipe,butitisimportanttokeepinmindthattheAngular2dataflowis,bydefault,downwardsthroughthecomponenttree.

Membermethods

Angulardoesn'tcareaboutthenatureoftheboundvalue.TypeScriptwillenforcetypecorrectnessshouldyoudeviatefromthedeclaredtype,butyouarewelcometopassparentmethodstothechildwiththisstrategyaswell.

Tip

Keepinmindthatpassingamethodboundinthiswaydoesnotenforcethecontextinwhichitisevaluated.Iftheparentcomponentpassesamembermethodthatutilizesthethiskeywordandthechildcomponentevaluatesit,thiswillrefertothechildcomponentinstanceandnottheparentcomponent.Therefore,ifthemethodtriestoaccessthememberdataontheparentcomponent,itwillnotbeavailable.

Thereareanumberofwaystomitigatethisproblem.Generallythough,ifyoufindyouarepassingaparentmembermethoddowntothechildcomponentandinvokingit,thereisprobablyabetterwaytodesignyourapplication.

SeealsoUsingdecoratorstobuildandstyleasimplecomponentdescribesthebuildingblocksofimplementinganAngular2componentBindingtonativeelementattributesshowshowAngular2interfaceswithHTMLelementattributesRegisteringhandlersonnativebrowsereventsdemonstrateshowyoucaneasilyattachbehaviortobrowserevents.GeneratingandcapturingcustomeventsusingEventEmitterdetailshowtopropagateinformationupwardsbetweencomponents.UsingngForandngIfstructuraldirectivesformodel-basedDOMcontrolinstructsyouonhowtoutilizesomeofAngular2'scorebuilt-indirectives.

BindingtonativeelementattributesInAngular1,itwasexpectedthatthedeveloperwouldutilizethebuilt-inreplacementdirectivesforelementattributesthathadmeaningfulDOMbehaviorattachedtothem.ThiswasduetothefactthatmanyoftheseattributeshadbehaviorthatwasincompatiblewithhowAngular1databindingoperated.InAngular2,thesespecialattributedirectivesaredoneawaywith,andthebindingbehaviorandsyntaxissubsumedintothenormalbindingbehavior.

Note



Howtodoit...Bindingtothenativeattributeisassimpleasplacingsquarebracketsaroundtheattributeandtreatingitasnormalbounddata:

[app/logo.component.ts]


@Component({

selector:'logo',

template:'<img[src]="logoUrl">'

})

exportclassLogoComponent{

logoUrl:string=

'//angular.io/resources/images/logos/standard/logo-nav.png';

}

Withthissetup,the<img>elementwilldutifullyfetchandshowtheimagewhenitisprovidedbyAngular.

Howitworks...Thisisadifferentsolutiontothesameproblemthatng-srcsolvedinAngular1.Thebrowserislookingforansrcattributeonthetag.Sincethesquarebracketsareincludedaspartoftheattributestring,thebrowserwillnotfindoneandthereforenotmakearequest.[src]willonlymakeanimagerequestoncethevalueisfilledandprovidedtotheelement.

SeealsoPassingmembersfromaparentcomponentintoachildcomponentgoesthroughthebasicsofdownwarddataflowbetweencomponents.Registeringhandlersonnativebrowsereventsdemonstrateshowyoucaneasilyattachbehaviortobrowserevents.AttachingbehaviortoDOMelementswithdirectivesdemonstrateshowtoattachbehaviortoelementswithattributedirectives.ReferencingelementsusingtemplatevariablesdemonstratesAngular2'snewtemplatevariableconstruct.AttributepropertybindingshowsAngular2'scleverwayofdeepreferencingelementproperties.

RegisteringhandlersonnativebrowsereventsInAngular2,theotherhemisphereofbindingthatisneededforafullyfunctioningapplicationiseventbinding.TheAngular2eventbindingsyntaxissimilartothatofdatabinding.

Note



GettingreadySupposeyouwantedtocreateanarticleapplicationthatcountedshares,andyoubeganwiththefollowingskeleton:



@Component({

selector:'article',

template:`

<h1>{{title}}</h1>

<p>Shares:{{shareCt}}</p>

<button>Share</button>

`

})


title:string='PoliceApprehendTiramisuThieves';

shareCt:number=0;

}

Howtodoit...TheAngular2eventbindingsyntaxisaccomplishedwithapairofparenthesessurroundingtheeventtype.Inthiscase,eventsthatyouwishtolistenforwillhaveatypepropertyofclick,andthisiswhattheywillbeboundagainst.Thevalueoftheboundeventattributeisanexpression,soyoucaninvokethemethodasahandlerwithinit:



@Component({

selector:'article',

template:`

<h1>{{title}}</h1>


<button(click)="share()">Share</button>

`

})



shareCt:number=0;

share():void{

++this.shareCt;

}

}

Howitworks...Angularwatchesfortheeventbindingsyntax(click)andaddsaclicklistenertoArticleComponent,boundtotheshare()handler.Whenthiseventisobserved,itevaluatestheexpressionattachedtotheevent,whichinthiscasewillinvokeamethoddefinedonthecomponent.

There'smore...Sincecapturingtheeventmustoccurinanexpression,youareprovidedwithan$eventparameterintheexpression,whichwillusuallybepassedasanargumenttothehandlermethod.ThisissimilartotheprocessinAngular1.Inspectingthis$eventobjectrevealsitasthevanillaclickeventgeneratedbythebrowser:



@Component({

selector:'article',

template:`

<h1>{{title}}</h1>


<button(click)="share($event)">Share</button>

`

})



shareCt:number=0;

share(e:Event):void{

console.log(e);//MouseEvent

++this.shareCt;

}

}

Note

Youwillalsonotethattheshare()methodhereisdemonstratinghowtypingcanbeappliedtotheparametersandthereturnvalueofthemethod:

myMethod(arg1:arg1type,arg2:arg2type,...):returnType

Aswithmemberbinding,youarealsoabletouseanalternateeventbindingsyntaxifyoudonotcaretouseasetofparentheses.Prefixingon-totheeventattributewillprovideyouwithidenticalbehavior:


@Component({

selector:'article',

template:`

<h1>{{title}}</h1>


<buttonon-click="share($event)">Share</button>

`

})

exportclassArticle{


shareCt:number=0;

share(e:Event):void{

++this.shareCt;

}

}

SeealsoBindingtonativeelementattributesshowshowAngular2interfaceswithHTMLelementattributes.GeneratingandcapturingcustomeventsusingEventEmitterdetailshowtopropagateinformationupwardsbetweencomponents.AttachingbehaviortoDOMelementswithdirectivesdemonstrateshowtoattachbehaviortoelementswithattributedirectives.AttributepropertybindingshowsAngular2'scleverwayofdeepreferencingelementproperties.

GeneratingandcapturingcustomeventsusingEventEmitterInthewakeofthedisappearanceof$scope,Angularwasleftwithavoidforpropagatinginformationupthecomponenttree.Thisvoidisfilledinpartbycustomevents,andtheyrepresenttheYintothedownwarddatabindingYang.

Note



GettingreadySupposeyouhadanArticleapplicationasfollows:

[app/text-editor.component.ts]


@Component({

selector:'text-editor',

template:`

<textarea></textarea>

`

})

exportclassTextEditorComponent{}



@Component({

selector:'article',

template:`

<h1>{{title}}</h1>

<p>Wordcount:{{wordCount}}</p>

<text-editor></text-editor>

`

})


title:string=`

MaternityWardResortstoRockPaperScissorsFollowing

BabyMixup`;

wordCount:number=0;

updateWordCount(e:number):void{

this.wordCount=e;

}

}

Thisapplicationwillideallybeabletoreadthecontentoftextareawhenthereisachange,andalsocountthenumberofwordsandreportittotheparentcomponenttobeinterpolated.Asisthecase,noneofthisisimplemented.

Howtodoit...AdeveloperthinkingintermsofAngular1wouldattachng-modeltotextarea,use$scope.$watchonthemodeldata,andpassthedatatotheparentvia$scopeorsomeothermeans.Unfortunatelyforsuchadeveloper,theseconstructsareradicallydifferentornon-existentinAngular2.Fearnot!Thenewimplementationismoreexpressive,moremodular,andmuchcleaner.

Capturingtheeventdata

ngModelstillexistsinAngular2,anditwouldcertainlybesuitablehere.However,youdon'tactuallyneedtousengModelatall,andinthiscase,itallowsyoutobemoreexplicitaboutwhenyourapplicationtakesaction.First,youmustretrievethetextfromthetextareaelementandmakeitusableinTextEditorComponent:



@Component({


template:`

<textarea(keyup)="emitWordCount($event)"></textarea>

`

})

exportclassTextEditorComponent{

emitWordCount(e:Event):void{

console.log(

(e.target.value.match(/\S+/g)||[]).length);

}

}

Excellent!Asclaimed,youdon'tneedtousengModeltoacquiretheelement'scontents.What'smore,youarenowabletoutilizenativebrowsereventstoexplicitlydefinewhenyouwantTextEditorComponenttotakeaction.

Withthis,youaresettingalisteneronthenativebrowser'skeyupevent,firedfromthetextareaelement.Thiseventhasatargetpropertythatexposesthevalueofthetextintheelement,whichisexactlywhatyouwanttouse.Thecomponentthenusesasimpleregularexpressiontocountthenumberofnon-whitespacesequences.Thisisyourwordcount.

Emittingacustomevent

console.logdoesnothelptoinformtheparentcomponentofthewordcountyouarecalculating.Todothis,youneedtocreateacustomeventandemititupwards:


import{Component,EventEmitter,Output}from'@angular/core';

@Component({


template:`

<textarea(keyup)="emitWordCount($event)"></textarea>

`

})

exportclassTextEditorComponent{

@Output()countUpdate=newEventEmitter<number>();

emitWordCount(e:Event):void{

this.countUpdate.emit(

(e.target.value.match(/\S+/g)||[]).length);

}

}

Usingthe@OutputdecoratorallowsyoutoinstantiateanEventEmittermemberonthechildcomponentthattheparentcomponentwillbeabletolistento.ThisEventEmittermember,likeanyotherclassmember,isavailableasthis.countUpdate.Thechildcomponentisabletosendeventsupwardbyinvokingtheemit()methodonthismember,andtheargumenttothismethodisthevaluewhichyouwishtosendtotheevent.Here,sinceyouwanttosendanintegercountofwords,youinstantiatetheEventEmittermemberbytypingitasa<number>emitter.

Listeningforcustomevents

Sofar,youarethroughwithonlyhalftheimplementation,asthesecustomeventsarebeingfiredoffintotheetherofthebrowserwithnolisteners.Sincethemethodyouneedtouseisalreadydefinedontheparentcomponent,allyouneedtodoishookintotheeventlistenertothatmethod.

The()templatesyntaxisusedtoaddlistenerstoevents,andAngulardoesnotdiscriminatebetweennativebrowsereventsandeventsthatoriginatefromEventEmitters.Thus,sinceyoudeclaredthechildcomponent'sEventEmitteras@Output,youwillbeabletoaddalistenerforeventsthatcomefromitontheparentcomponent,asfollows:


import{Component}from'angular2/core';

@Component({

selector:'article',

template:`

<h1>{{title}}</h1>

<p>Wordcount:{{wordCount}}</p>

<text-editor(countUpdate)="updateWordCount($event)">

</text-editor>

`

})


title:string=`

MaternityWardResortstoRockPaperScissorsFollowing

BabyMixup`;

wordCount:number=0;

updateWordCount(e:number):void{

this.wordCount=e;

}

}

Withthis,yourapplicationshouldcorrectlycountthewordsintheTextEditorcomponentandupdatethevalueintheArticlecomponent.

Howitworks...Using@OutputinconjunctionwithEventEmitterallowsyoutocreatechildcomponentsthatexposeanAPIfortheparentcomponenttohookinto.TheEventEmittersendstheeventsupwardwithitsemitmethod,andtheparentcomponentcansubscribetothembybindingtotheemitteroutput.

Theflowofthisexampleisasfollows:

1. Thekeystrokeinsidetextareacausesthenativebrowser'skeyupevent.2. TheTextEditorcomponenthasalistenersetonthisevent,sotheattachedexpressionis

evaluated,whichwillinvokeemitWordCount.3. TheemitWordCountinspectstheEventobjectandextractsthetextfromtheassociated

DOMelement.ItparsesthetextforthenumberofcontainedwordsandinvokestheEventEmitter.emitmethod.

4. TheEventEmittermethodemitsaneventassociatedwiththedeclaredcountUpdate@Outputmember.

5. TheArticleComponentseesthiseventandinvokestheattachedexpression.TheexpressioninvokesupdateWordCount,passingintheeventvalue.

6. TheArticleComponentpropertyisupdated,andsincethisvalueisinterpolatedintheview,Angularhonorsthedatabindingprocessbyupdatingtheview.

There'smore...ThenameEventEmitterisabitdeceiving.Ifyou'repayingattention,youwillnoticethattheparentcomponentmembermethodinvokedinthehandlerdoesnothaveatypedparameter.Youwillalsonoticethatyouaredirectlyassigningthatparametertothemembertypedasnumber.Thisshouldseemoddasthetemplateexpressioninvokingthemethodispassing$event,whichyouusedearlierasabrowserEventobject.Thisseemslikeamismatchbecauseitisamismatch.Ifyoubindtonativebrowserevents,theeventyouwillobservecanonlybethenativebrowsereventobject.Ifyoubindtocustomevents,theeventyouwillobserveiswhateverwaspassedwhenemitwasinvoked.Here,theparametertoupdateWordCount()issimplytheintegeryouprovidedwiththis.countUpdate.emit().

Alsonotethatyouarenotrequiredtoprovideavaluefortheemittedevent.YoucanstilluseEventEmittertosignaltoaparentcomponentthataneventhasoccurredandthatitshouldevaluatetheboundexpression.Todothis,yousimplycreateanuntypedemitterwithnewEventEmitter()andinvokeemit()withnoarguments.$eventshouldbeundefined.

Itisnotpossibletopassmultiplevaluesascustomevents.Tosendmultiplepiecesofdata,youneedtocombinethemintoanobjectorarray.

SeealsoBindingtonativeelementattributesshowshowAngular2interfaceswithHTMLelementattributes.Registeringhandlersonnativebrowsereventsdemonstrateshowyoucaneasilyattachbehaviortobrowserevents.

AttachingbehaviortoDOMelementswithdirectivesInthecourseofcreatingapplications,youwilloftenfinditusefultobeabletoattachcomponent-stylebehaviortoDOMelements,butwithouttheneedtohavetemplating.IfyouweretoattempttoconstructanAngular2componentwithoutprovidingatemplateinsomeway,youwillmeetwithasternerrortellingyouthatsomeformoftemplateisrequired.

HereliesthedifferencebetweenAngular2componentsanddirectives:componentshaveviews(whichcantaketheformofatemplate,templateUrl,or@Viewdecorator),whereasdirectivesdonot.Theyotherwisebehaveidenticallyandprovideyouwiththesamebehavior.

Note



GettingreadySupposeyouhavethefollowingapplication:



@Component({

selector:'article',

template:`<h1>{{title}}</h1>`,

styles:[`

h1{

text-overflow:ellipsis;

white-space:nowrap;

overflow:hidden;

max-width:300px;

}

`]

})


title:string=`PresidentialCandidatesRespondto

AllegationsInvolvingAbilitytoDunk`;

}

Currently,thisapplicationisusingCSStotruncatethearticletitlewithanellipsis.YouwouldliketoexpandthisapplicationsothattheArticlecomponentrevealstheentiretitlewhenclickedbysimplyaddinganHTMLattribute.

Howtodoit...Beginbydefiningthebasicclassthatwillpowertheattributedirectiveandaddittotheapplicationmodule:

[app/click-to-reveal.directive.ts]

exportclassClickToRevealDirective{

reveal(target){

target.style['white-space']='normal';

}

}

[app/app.module.ts]




import{ClickToRevealDirective}

from'./click-to-reveal.directive';

@NgModule({

imports:[

BrowserModule

],

declarations:[

ArticleComponent,

ClickToRevealDirective

],

bootstrap:[

ArticleComponent

]

})


First,youmustdecoratetheClickToRevealDirectiveclassas@DirectiveanduseitinsidetheArticlecomponent:


import{Directive}from'@angular/core';

@Directive({

selector:'[click-to-reveal]'

})


reveal(target){


}

}

Next,addtheattributetotheelementthatyouwishtoapplythedirectiveto:



@Component({

selector:'article',

template:`<h1click-to-reveal>{{title}}</h1>`,

styles:[`

h1{

text-overflow:ellipsis;

white-space:nowrap;

overflow:hidden;

max-width:300px;

}

`]

})


title:string;

constructor(){

this.title=`PresidentialCandidatesRespondto

AllegationsInvolvingAbilitytoDunk`;

}

}

Note

NotethattheDirectiveisusinganattributeCSSselectortoassociateitselfwithanyelementsthathaveclick-to-reveal.ThisofcourseapproximatesanAngular1attribute'sdirectivebehavior,butthisformisfarmoreflexiblesinceitcanwieldtheinnatematchabilityofselectors.

NowthattheArticlecomponentisawareofClickToRevealDirective,youmustprovideittheabilitytoattachitselftoclickevents.

AttachingtoeventswithHostListeners

Anattentivedeveloperwillhavenoticedthatupuntilthispointinthechapter,youhavecreatedcomponentsthatlistentotheeventsgeneratedbythechildren.Thisisnoproblemsinceyoucanexpressivelysetlistenersinaparentcomponenttemplateonthechildtag.

However,inthissituation,youarelookingtoaddalistenertothesameelementthatthedirectiveisbeingattachedto.What'smore,youdonothaveagoodwayofaddinganeventbindingexpressiontothetemplatefrominsideadirective.Ideally,youwouldliketonothavetoexposethismethodfrominsidethedirective.Howshouldyouproceedthen?

ThesolutionistoutilizeanewAngularconstructcalledHostListener.Simplyput,itallowsyoutocaptureself-originatingeventsandhandletheminternally:


import{Directive,HostListener}from'@angular/core';

@Directive({

selector:'[click-to-reveal]'

})


@HostListener('click',['$event.target'])

reveal(target){


}

}

Withthis,clickeventsonthe<h1>elementshouldsuccessfullyinvokethereveal()method.

Howitworks...Thedirectiveneedsawaytoattachtonativeclickevents.Furthermore,itneedsawaytocaptureobjectssuchas$eventthatAngularprovidestoyou;theseobjectswouldnormallybecapturedinthebindingexpression.

@HostListenerdecoratesadirectivemethodtoactasthedesignatedeventhandler.Thefirstargumentinitsinvocationistheeventidentificationstring(here,click,butitcouldjustaseasilybeacustomeventfromEventEmitter),andthesecondargumentisanarrayofstringargumentsthatareevaluatedasexpressions.

There'smore...YouarenotrestrictedtooneHostListenerinsideadirective.Usingitmerelyassociatesaneventwithadirectivemethod.SoyouareabletostackmultipleHostListenerdeclarationsonasinglehandler,forexample,tolistenforbothaclickandmouseoverevent.

SeealsoUsingdecoratorstobuildandstyleasimplecomponentdescribesthebuildingblocksofimplementinganAngular2componentPassingmembersfromaparentcomponentintoachildcomponentgoesthroughthebasicsofdownwarddataflowbetweencomponentsUsingngForandngIfstructuraldirectivesformodel-basedDOMcontrolinstructsyouinhowtoutilizesomeofAngular2'scorebuilt-indirectivesAttributepropertybindingshowsAngular2'scleverwayofdeepreferencingelementproperties

ProjectingnestedcontentusingngContentUtilizingcomponentsasstandalonetagsthatareself-containedandwhollymanagetheircontentsisacleanpattern,butyouwillfrequentlyfindthatyourcomponenttagsdemandthattheyenclosecontent.

Note



GettingreadySupposeyouhadthefollowingapplication:

[app/ad-section.component.ts]


@Component({

selector:'ad-section',

template:`

<ahref="#">{{adText}}</a>

`

})

exportclassAdSectionComponent{

adText:string='Selfiesticks40%off!';

}



@Component({

selector:'article',

template:`

<h1>{{title}}</h1>

<p>U.S.senatorsareupinarmsfollowingtherecentruling

strippingthemoftheirbelovedselfiesticks.</p>

<p>Abipartisancommitteedraftedaresolutiontosmuggle

selfiesticksontothefloorbyanymeansnecessary.</p>

`

})


title:string='SelfieSticksBannedfromSenateFloor';

}

YourobjectivehereistomodifythissothattheAdSectioncomponentcanbeincorporatedintotheArticlecomponentwithoutinterferingwithitscontent.

Howtodoit...TheAdSectioncomponentwantstoincorporateanextraelementaroundtheexistingArticlecontent.Thisiseasytoaccomplish:



@Component({

selector:'article',

template:`

<h1>{{title}}</h1>

<ad-section>

<p>U.S.senatorsareupinarmsfollowingtherecentruling

strippingthemoftheirbelovedselfiesticks.</p>

<p>Abipartisancommitteedraftedaresolutiontosmuggle

selfiesticksontothefloorbyanymeansnecessary.</p>

</ad-section>

`

})


title:string='SelfieSticksBannedfromSenateFloor';

}

Youwillnoticethoughthatthisisadestructiveoperation.WhenrenderingAdSectionComponent,Angularisnotconcernedaboutanycontentthatisinsideit.ItseesthatAdSectionComponenthasatemplateassociatedwithit,anditdutifullysupplantstheelement'scontentswithit;[email protected],thatwipesoutthe<p>tagsthatyouwanttoretain.

Topreservethem,youmustinstructAngularhowitshouldmanagewrappedcontent.Thiscanbeaccomplishedwithan<ng-content>tag:

[app/ad-section.component.ts]


@Component({

selector:'ad-section',

template:`

<ahref="#">{{adText}}</a>

<ng-contentselect="p"></ng-content>

`

})

exportclassAdSectionComponent{

adText:string='Selfiesticks40%off!';

}

Withthis,theadanchorelementisinsertedbeforethewrappedcontent.

Howitworks...Similartohowng-transcludeworkedinAngular1,ng-contentservestointerpolatethecomponenttag'swrappedcontentintoitstemplate.Thedifferencehereisthatng-contentusesaselectattributetotargetthewrappedelements.ThisissimplyaCSSselector,operatinginthesamewayinwhich@ComponentdecoratorshandletheselectorpropertyinComponentMetadata.

There'smore...Theselectattributeinthisexamplewassuperfluous,asitendedupselectingtheentiretyofthewrappedcontent.Ofcourse,iftheselectvalueonlymatchedsomeofthewrappedcontent,itwouldteaseoutonlythoseelementsandinterpolatethem.<ng-content>willbydefaultinserttheentiretyofthewrappedcontentifyoudeclinetoprovideitwithaselectvalue.

AlsonotethattheselectattributeisalimitedCSSselector.Itisnotcapableofperformingcomplexselectionssuchas:nth-child,anditisonlyabletotargettop-levelelementsinsidethewrappingtags.Forexample,inthisapplication,theparagraphtaginside<div><p>Blah</p></div>wouldnotbeincludedwithaselect="p"attributevalue.

SeealsoReferencingaparentcomponentfromachildcomponentdescribeshowacomponentcangainadirectreferencetoitsparentviainjectionConfiguringmutualparent-childawarenesswithViewChildandforwardRefinstructsyouonhowtoproperlyuseViewChildtoreferencechildcomponentobjectinstancesConfiguringMutualParent-ChildAwarenesswithContentChildandforwardRefinstructsyouonhowtoproperlyuseContentChildtoreferencechildcomponentobjectinstances

UsingngForandngIfstructuraldirectivesformodel-basedDOMcontrolAnydeveloperthathasusedaclientframeworkisintimatelyfamiliarwithtwobasicoperationsinanapplication:iterativerenderingfromacollectionandconditionalrendering.ThenewAngular2implementationslookabitdifferentbutoperateinmuchthesameway.

Note

Thecode,links,andaliveexampleareavailableathttp://ngcookbook.herokuapp.com/3211/.



[app/article-list.component.ts]


@Component({

selector:'article-list',

template:''

})

exportclassArticleListComponent{

articles:Array<Object>=[

{title:'Foo',active:true},

{title:'Bar',active:false},

{title:'Baz',active:true}

];

}

Yourobjectiveistoiteratethroughthisanddisplaythearticletitleonlyifitissetasactive.

Howtodoit...SimilartoAngular1,Angular2providesyouwithdirectivestoaccomplishthistask.ngForisusedtoiteratethroughthearticlescollection:



@Component({


template:`

<div*ngFor="letarticleofarticles;leti=index">

<h1>

{{i}}:{{article.title}}

</h1>

</div>

`

})






];

}

SimilartongFor,ngIfcanbeincorporatedasfollows:


import{Component}from'angular2/core';

@Component({


template:`

<div*ngFor="letarticleofarticles;leti=index">

<h1*ngIf="article.active">


</h1>

</div>

`

})






];

}

Withthis,youwillseethatonlytheobjectsinthearticlesarraywithactive:truearerendered.

Howitworks...Atfirst,theasteriskandpoundsignnotationcouldbeconfusingformanydevelopers.Formostapplications,youwillnotneedtoknowhowthissyntacticsugaractuallyworksbehindthescenes.

Inreality,Angulardecomposesallthestructuraldirectivesprefixedwith*toutilizeatemplate.First,AngularbreaksdownngForandngIftousethetemplatedirectivesonthesameelement.Thesyntaxdoesnotchangemuchyet:



@Component({


template:`

<divtemplate="ngForletarticleofarticles;leti=index">

<h1template="ngIfarticle.active">


</h1>

</div>

`

})

exportclassArticleList{

articles:Array<Object>,

constructor(){

this.articles=[




];

}

}

Followingthis,Angulardecomposesthistemplatedirectiveintoawrapping<template>element:



@Component({


template:`

<templatengForlet-article[ngForOf]="articles"let-i="index">

<div>

<template[ngIf]="article.active">

<h1>


</h1>

</template>

</div>

</template>

`

})

exportclassArticleList{

articles:Array<Object>,

constructor(){

this.articles=[




];

}

}

Note

Notethatboththeversionsdisplayedhere—eitherusingthetemplatedirectiveorthe<template>element—willbehaveidenticallytousingtheoriginalstructuraldirectives.Thatbeingsaid,theregenerallywillnotbeareasontoeverdoitthisway;thisismerelyademonstrationtoshowyouhowAngularunderstandsthesedirectivesbehindthescenes.

Tip

WheninspectingtheactualDOMoftheseexamplesusingngForandngIf,youwillbeabletoseeAngular'sautomaticallyaddedHTMLcommentsthatdescribehowitinterpretsyourmarkupandtranslatesitintotemplatebindings.

There'smore...ThetemplateelementisbornoutoftheWebComponents'specification.TemplatesareadefinitionofhowaDOMsubtreecaneventuallybedefinedasaunit,buttheelementsthatappearwithinitarenotcreatedoractiveuntilthetemplateisactuallyusedtocreateaninstancefromthattemplate.Notallwebbrowserssupportwebcomponents,soAngular2doesapolyfilltoemulatepropertemplatebehavior.

Inthisway,thengFordirectiveisactuallycreatingawebcomponenttemplatethatutilizesthesubordinatengForOfbinding,whichisapropertyofNgFor.EachinstanceinarticleswillusethetemplatetocreateaDOMsection,andwithinthissection,thearticleandindextemplatevariableswillbeavailableforinterpolation.

SeealsoUsingdecoratorstobuildandstyleasimplecomponentdescribesthebuildingblocksofimplementinganAngular2componentPassingmembersfromaparentcomponentintoachildcomponentgoesthroughthebasicsofdownwarddataflowbetweencomponentsBindingtonativeelementattributesshowshowAngular2interfaceswithHTMLelementattributesAttachingbehaviortoDOMelementswithdirectivesdemonstrateshowtoattachbehaviortoelementswithattributedirectivesAttributepropertybindingshowsAngular2'scleverwayofdeepreferencingelementpropertiesUtilizingcomponentlifecyclehooksgivesanexampleofhowyoucanintegratewithAngular2'scomponentrenderingflow.

ReferencingelementsusingtemplatevariablesManydeveloperswillbeginwithAngular2andreachforsomethingthatresemblesthetrustworthyng-modelinAngular1.NgModelexistsinAngular2,butthereisanewwayofreferencingelementsinthetemplate:localtemplatevariables.

Note



GettingreadySupposeyouhadthefollowingapplicationandwantedtodirectlyaccesstheinputelement:



@Component({

selector:'article',

template:`

<input>

<h1>{{title}}</h1>

`

})

exportclassArticleComponent{}

Howtodoit...Angular2allowsyoutohavea#assignmentwithinthetemplateitself,whichcanconsequentlybereferencedfrominsidethetemplate.Forexample,refertothefollowingcode:



@Component({

selector:'article',

template:`

<input#title>

<h1>{{title}}</h1>

`

})


Withthis,youwillsee[objectHTMLInputElement](orsomethingsimilar,dependingonyourbrowser)interpolatedintothe<h1>tag.Thismeansthatthe#titleinsidethe<input>tagisnowdirectlyreferencingtheelementobject,whichofcoursemeansthatthevalueoftheelementshouldbeavailableforyou.

Don'tgettooexcitedjustyet!Ifyouattempttointerpolatetitle.valueandthenmanipulatetheinputfield,youwillnotseethebrowserupdate.ThisisbecauseAngular2nolongersupportsbidirectionaldatabindinginthisway.Fearnot,forthesolutiontothisproblemlieswithinthenewAngular2databindingpattern.

AngularwilldeclinetoupdatetheDOMuntilitthinksitneedsto.Thisneedisdeterminedbywhatbehaviorintheapplicationmightcausetheinterpolateddatatochange.Aboundevent,whichwillpropagateupwardsthroughthecomponenttree,maycauseadatachange.Thus,youcancreateaneventbindingonanelement,andthemerepresenceofthiseventbindingwilltriggerAngulartoupdatethetemplate:



@Component({

selector:'article',

template:`

<input#title(keyup)="0">

<h1>{{title.value}}</h1>

`

})


Here,thekeyupeventfromthetextinputisboundtoanexpressionthatiseffectivelyano-op.

SincetheeventwilltriggeranupdateoftheDOM,youcansuccessfullypulloutthelatestvaluepropertyfromthetitleinputelementobject.Withthis,youhavesuccessfullyboundtheinputvaluetotheinterpolatedstring.

There'smore...Ifyouaren'tcrazyaboutthe#notation,youcanalwaysreplaceitwithval-andstillachieveidenticalbehavior:



@Component({

selector:'article',

template:`

<inputval-title(keyup)="0">

<h1>{{title.value}}</h1>

`

})


Also,it'simportanttorecallthatthesetemplatevariablesareonlyaccessiblewithinthetemplate.Ifyouwanttopassthembacktothecontroller,you'llhavetouseitasahandlerargument:



@Component({

selector:'article',

template:`

<input#title(keyup)="setTitle(title.value)">

<h1>{{myTitle}}</h1>

`

})


myTitle:string;

setTitle(val:string):void{

this.myTitle=val;

}

}

SeealsoReferencingaparentcomponentfromachildcomponentdescribeshowacomponentcangainadirectreferencetoitsparentviainjectionConfiguringmutualparent-childawarenesswithViewChildandforwardRefinstructsyouonhowtoproperlyuseViewChildtoreferencechildcomponentobjectinstancesConfiguringmutualparent-childawarenesswithContentChildandforwardRefinstructsyouonhowtoproperlyuseContentChildtoreferencechildcomponentobjectinstances

AttributepropertybindingOneofthegreatnewbenefitsofthenewAngularbindingstyleisthatyouareabletomoreaccuratelytargetwhatyouarebindingto.Formerly,theHTMLattributethatwasusedasadirectiveordatatokenwassimplyusedasamatchingidentifier.Now,youareabletousepropertybindingswithinthebindingmarkupforboththeinputandoutput.

Note

Thecode,links,andaliveexampleofthisisavailableathttp://ngcookbook.herokuapp.com/8565/.





@Component({

selector:'article',

template:`

<input#title(keydown)="setTitle(title.value)">


`

})


myTitle:string;


this.myTitle=val;

}

}

Yourobjectiveistomodifythissothatitexhibitsthefollowingbehavior:

The<h1>tagisnotupdatedwiththevalueoftheinputfielduntiltheuserstrikestheEnterkey.Ifthe<h1>valuedoesnotmatchthevalueinthetitleinput(callthisstate"stale"),thetextcolorshouldbered.Ifitdoesmatch,itshouldbegreen.

Howtodoit...BothofthesebehaviorscanbeachievedwithAngular2'sattributepropertybinding.First,youcanchangetheeventbindingsothatonlyanEnterkeywillinvokethecallback:



@Component({

selector:'article',

template:`

<input#title(keydown.enter)="setTitle(title.value)">


`

})


myTitle:string;


this.myTitle=val;

}

}

Next,youcanuseAngular'sstylebindingtodirectlyassignavaluetoastyleproperty.ThisrequiresaddingaBooleantothecontrollerobjecttomaintainthestate:



@Component({

selector:'article',

template:`

<input#title(keydown.enter)="setTitle(title.value)">

<h1[style.color]="isStale?'red':'green'">{{myTitle}}</h1>

`

})


myTitle:string='';

isStale:boolean=false;


this.myTitle=val;

}

}

Closer,butthisstillprovidesnowayofreachingastalestate.Toachievethis,addanotherkeydowneventbinding:



@Component({

selector:'article',

template:`

<input#title

(keyup.enter)="setTitle(title.value)"

(keyup)="checkStale(title.value)">

<h1[style.color]="isStale?'red':'green'">

{{myTitle}}

</h1>

`

})


myTitle:string='';

privateisStale:boolean=false;


this.myTitle=val;

}

checkStale(val:string):void{

this.isStale=val!==this.myTitle;

}

}

Withthis,thecolorofthe<h1>tagshouldcorrectlykeeptrackofwhetherthedataisstaleornot!

Howitworks...ThesimpleexplanationisthatAngularprovidesyouwithalotofsyntacticalsugar,butataverybasiclevelwithoutinvolvingalotofcomplexity.Ifyouweretoinspectthekeyupevent,youwouldofcoursenoticethatthereisnoenterpropertyavailable.AngularoffersyouanumberofthesepseudopropertiessothatcheckingthekeyCodeofthepressedkeyisnotnecessary.

Inasimilarway,Angularalsoallowsyoutobindtoandaccessstylepropertiesdirectly.Itisinferredthatthestylebeingaccessedreferstothehostelement.

There'smore...Noteherethatyouhaveassignedtwohandlerstowhatisessentiallythesameevent.Notonlythis,butrearrangingtheorderofthebindingmarkupwillbreakthisapplication'sdesiredbehavior.

Note

Whentwohandlersareassignedtothesameevent,Angularwillexecutethehandlersintheorderthattheyaredefinedinthemarkup.

SeealsoBindingtonativeelementattributesshowshowAngular2interfaceswithHTMLelementattributesRegisteringhandlersonnativebrowsereventsdemonstrateshowyoucaneasilyattachbehaviortobrowsereventsGeneratingandcapturingcustomeventsusingEventEmitterdetailshowtopropagateinformationupwardsbetweencomponentsAttachingbehaviortoDOMelementswithdirectivesdemonstrateshowtoattachbehaviortoelementswithattributedirectives

UtilizingcomponentlifecyclehooksAngular'scomponentrenderingprocesshasalargenumberoffacets,anddifferenttypesofdataandreferenceswillbecomeavailableatdifferenttimes.Toaccountforthis,Angular2allowscomponentstosetcallbacks,whichwillbeexecutedatdifferentpointsinthecomponent'slifecycle.

Note



GettingreadySupposeyoubeganwiththefollowingapplication,whichsimplyallowstheadditionandremovalofarticlesfromasingleinput:



@Component({


template:`

<input(keyup.enter)="add($event)">

<article*ngFor="lettitleoftitles;leti=index"

[articleTitle]="title">

<button(click)="remove(i)">X</button>

</article>

`

})


titles:Array<string>=[];

add(e:Event):void{

this.titles.push(e.target.value);

e.target.value='';

}

remove(index:number){

this.titles.splice(index,1);

}

}



@Component({

selector:'article',

template:`

<h1>

<ng-content></ng-content>{{articleTitle}}

</h1>

`

})


@Input()articleTitle:string;

}

Yourobjectiveistouselifecyclehookstokeeptrackoftheprocessofaddingandremovingoperations.

Howtodoit...Angularallowsyoutoimporthookinterfacesfromthecoremodule.Theseinterfacesaremanifestedasclassmethods,whichareinvokedattheappropriatetime:


import{Component,Input,ngOnInit,ngOnDestroy}

from'@angular/core';

@Component({

selector:'article',

template:`

<h1>

<ng-content></ng-content>{{articleTitle}}

</h1>

`

})

exportclassArticleComponentimplementsOnInit,OnDestroy{

@Input()articleTitle:string;

ngOnInit(){

console.log('created',this.articleTitle);

}

ngOnDestroy(){

console.log('destroyed',this.articleTitle);

}

}

Withthis,youshouldseelogseachtimeanewArticleComponentisaddedorremoved.

Howitworks...Differenthookshavedifferentsemanticmeanings,buttheywilloccurinawell-definedorder.Eachhook'sexecutionguaranteesthatacertainbehaviorofacomponentisjustcompleted.

Thehooksthatarecurrentlyavailabletoyouintheorderofexecutionareasfollows:

ngOnChanges

ngOnInit

ngDoCheck

ngAfterContentInit

ngAfterContentChecked

ngAfterViewInit

ngAfterContentChecked

ngOnDestroy

Itisalsopossibleforthird-partylibrariestoextendtheseandaddtheirownhooks.

There'smore...Usinghooksisoptional,andAngularwillonlyinvokethemifyouhavedefinedthem.Theuseoftheimplementsinterfacedeclarationisoptional,butitwillsignaltotheTypeScriptcompilerthatacorrespondingmethodshouldbeexpected,whichisobviouslyagoodpractice.

SeealsoReferencingaparentcomponentfromachildcomponentdescribeshowacomponentcangainadirectreferencetoitsparentviainjectionConfiguringmutualparent-childawarenesswithViewChildandforwardRefinstructsyouonhowtoproperlyuseViewChildtoreferencechildcomponentobjectinstancesConfiguringmutualparent-childawarenesswithContentChildandforwardRefinstructsyouonhowtoproperlyuseContentChildtoreferencechildcomponentobjectinstances

ReferencingaparentcomponentfromachildcomponentInthecourseofbuildinganapplication,youmayencounterascenariowhereitwouldbeusefultoreferenceaparentcomponentfromachildcomponent,suchastoinspectmemberdataorinvokepublicmethods.InAngular2,thisisactuallyquiteeasytoaccomplish.

Note



GettingreadySupposeyoubeginwiththefollowingArticleComponent:



@Component({

selector:'article',

template:`

<feedback[val]="likes"></feedback>

`

})


likes:number=0;

incrementLikes():void{

this.likes++;

}

}

Yourobjectiveistoimplementthefeedbackcomponentsothatitdisplaysthenumberoflikespassedtoit,buttheparentcomponentcontrolstheactuallikecountandpassesthatvaluein.

Howtodoit...Beginbyimplementingthebasicstructureofthechildcomponent:

[app/feedback.component.ts]


@Component({

selector:'feedback',

template:`

<h1>Numberoflikes:{{val}}</h1>

<button(click)="likeArticle()">Likethisarticle!</button>

`

})

exportclassFeedbackComponent{

@Input()val:number;

likeArticle():void{}

}

Sofar,noneofthisshouldsoundsurprising.Clickingonthebuttoninvokesanemptymethod,andyouwantthismethodtoinvokeamethodfromtheparentcomponent.However,youcurrentlylackareferencetodothis.Listingthecomponentinthechildcomponentconstructorwillmakeitavailabletoyou:




@Component({


template:`


<button(click)="like()">Likethisarticle!</button>

`

})


@Input()val:number;

privatearticleComponent:ArticleComponent;

constructor(articleComponent:ArticleComponent){

this.articleComponent=articleComponent;

}

like():void{

this.articleComponent.incrementLikes();

}

}

Withareferencetotheparentcomponentnowavailable,youareeasilyabletoinvokeitspublicmethod,namelyincrementLikes().Atthispoint,thetwocomponentsshouldcommunicatecorrectly.

Howitworks...Verysimply,Angular2recognizesthatyouareinjectingacomponentthatistypedinthesamewayastheparent,anditwillprovidethatparentforyou.Thisisthefullparentinstance,andyouarefreetointeractwithitasyouwouldnormallyinteractwithanycomponentinstance.

Tip

Noticethatitisrequiredthatyoustoreareferencetothecomponentinsidetheconstructor.Unlikewhenyouinjectaservice,thechildcomponentwillnotautomaticallymaketheArticleComponentinstanceavailabletoyouasthis.articleComponent;youneedtodothismanually.

There'smore...Anastutedeveloperwillnoticethatthiscreatesaveryrigiddependencyfromthechildcomponenttotheparentcomponent.Thisisindeedthecase,butnotnecessarilyabadthing.Often,itisusefultoallowcomponentstomoreeasilyinteractwitheachotherattheexpenseoftheirmodularity.Andgenerally,thiswillbeajudgmentcallonyourpart.

SeealsoPassingmembersfromaparentcomponentintoachildcomponentgoesthroughthebasicsofdownwarddataflowbetweencomponentsRegisteringhandlersonnativebrowsereventsdemonstrateshowyoucaneasilyattachbehaviortobrowsereventsGeneratingandcapturingcustomeventsusingEventEmitterdetailshowtopropagateinformationupwardsbetweencomponentsConfiguringmutualparent-childawarenesswithViewChildandforwardRefinstructsyouonhowtoproperlyuseViewChildtoreferencechildcomponentobjectinstancesConfiguringmutualparent-childawarenesswithContentChildandforwardRefinstructsyouonhowtoproperlyuseContentChildtoreferencechildcomponentobjectinstances

Configuringmutualparent-childawarenesswithViewChildandforwardRefDependingonyourapplication'sseparationofconcerns,itmightmakesenseforachildcomponentinyourapplicationtoreferenceaparent,andatthesametime,fortheparenttoreferencethechild.Therearetwosimilarimplementationsthatallowyoutoaccomplishthis:usingViewChildandContentChild.Thisrecipewilldiscussthemboth.

Note



GettingreadyBeginwiththerecipesetupshowninReferencingaparentcomponentfromachildcomponent.Yourobjectiveistoaddtheabilitytoenableanddisablethelikebuttonfromtheparentcomponent.

Howtodoit...Theinitialsetuponlygivesthechildaccesstotheparent,whichisonlyhalfofwhatyouneed.Theotherhalfistogivetheparentaccesstothechild.

GettingareferencetoFeedbackComponentthatyouseeintheArticleComponenttemplateviewcanbedoneintwoways,andthefirstwaydemonstratedherewilluseViewChild.

ConfiguringaViewChildreference

UsingViewChildwillallowyoutoextractacomponentreferencefrominsidetheview.Moreplainly,inthisexample,usingViewChildwillgiveyoutheabilitytoreferencetheFeedbackComponentinstancefrominsidetheArticleComponentcode.

First,configureArticleComponentsothatitwillretrievethecomponentreference:


import{Component,ViewChild}from'@angular/core';

import{FeedbackComponent}from'./feedback.component';

@Component({

selector:'article',

template:`

<inputtype="checkbox"

(click)="changeLikesEnabled($event)">


`

})


@ViewChild(FeedbackComponent)

feedbackComponent:FeedbackComponent;

likes:number=0;


this.likes++;

}

changeLikesEnabled(e:Event):void{

this.feedbackComponent.setLikeEnabled(e.target.checked);

}

}

ThemainthemeinthisnewcodeisthattheViewChilddecoratorimplicitlyunderstandsthatitshouldtargettheviewofthiscomponent,findtheinstanceofFeedbackComponentthatisbeingrenderedthere,andassignittothefeedbackCompnentmemberoftheArticleComponentinstance.

CorrectingthedependencycyclewithforwardRef

Atthispoint,youshouldbeseeingyourapplicationthrowingnewerrors,mostlikelyaboutbeingunabletoresolvetheparametersforFeedbackComponent.Thisoccursbecauseyouhavesetupacyclicdependency:FeedbackComponentdependsonArticleComponentandArticleComponentdependsonFeedbackComponent.Thankfully,thisproblemexistsinthedomainofAngulardependencyinjection,soyoudon'treallyneedthemodule,justatokenthatrepresentsit.Forthispurpose,Angular2providesyouwithforwardRef,whichallowsyoutouseamoduledependencyinsideyourclassdefinitionbeforeitisdefined.Useitasfollows:


import{Component,Input,Inject,forwardRef}



@Component({


template:`


<button(click)="likeArticle()">

Likethisarticle!

</button>

`

})


@Input()val:number;


constructor(@Inject(forwardRef(()=>ArticleComponent))

articleComponent:ArticleComponent){


}

likeArticle():void{


}

}

Addingthedisablebehavior

Withthecycleproblemresolved,addthesetLikeEnabled()methodthattheparentcomponentisinvoking:


import{Component,Input,Inject,forwardRef}



@Component({


template:`


<button(click)="likeArticle()"

[disabled]="!likeEnabled">

Likethisarticle!

</button>

`

})


@Input()val:number;

privatelikeEnabled:boolean=false;





}

likeArticle():void{


}

setLikeEnabled(newEnabledStatus:boolean):void{

this.likeEnabled=newEnabledStatus;

}

}

Withthis,togglingthecheckboxshouldenableanddisablethelikebutton.

Howitworks...ViewChilddirectsAngulartofindthefirstinstanceofFeedbackComponentpresentinsidetheArticleComponentviewandassignittothedecoratedclassmember.Thereferencewillbeupdatedalongwithanyviewupdates.Thisdecoratedmemberwillrefertothechildcomponentinstanceandcanbeinteractedwithlikeanynormalobjectinstance.

Note

It'simportanttorememberthedualityofthecomponentinstanceanditsrepresentationinthetemplate.Forexample,FeedbackComponentisrepresentedbyafeedbacktag(pre-render)andaheadertagandabutton(post-render),butneitheroftheseformtheactualcomponent.TheFeedbackComponentinstanceisaJavaScriptobjectthatlivesinthememory,andthisistheobjectyouwantaccessto.Ifyoujustwantedareferencetothetemplateelements,thiscouldbeaccomplishedbyatemplatevariable,forexample.

There'smore...SinceAngularperformshierarchicalrendering,ViewChildwillnotbereadyuntiltheviewisinitialized,butrather,aftertheAfterViewInitlifecyclehook.Thiscanbedemonstratedasfollows:


import{Component,ViewChild,ngAfterViewInit}



@Component({

selector:'article',

template:`




`

})

exportclassArticleComponentimplementsAfterViewInit{

@ViewChild(FeedbackComponent)


likes:number=0;

constructor(){

console.log(this.feedbackComponent);

}

ngAfterViewInit(){


}


this.likes++;

}



}

}

Thiswillfirstlogundefinedinsidetheconstructorastheview,andtherefore,FeedbackComponentdoesnotyetexist.OncetheAfterViewInitlifecyclehookoccurs,youwillbeabletoseeFeedbackComponentloggedtotheconsole.

ViewChildren

Ifyouwouldliketogetareferencetomultiplecomponents,youcanperformanidenticalreferenceacquisitionusingViewChildren,whichwillprovideyouwithaQueryListofallthe

matchingcomponentsintheview.

Tip

AQueryListcanbeusedlikeanarraywithitstoArray()method.Italsoexposesachangesproperty,whichemitsaneventeverytimeamemberofQueryListchanges.

SeealsoUtilizingcomponentlifecyclehooksgivesanexampleofhowyoucanintegratewithAngular2'scomponentrenderingflowReferencingaparentcomponentfromachildcomponentdescribeshowacomponentcangainadirectreferencetoitsparentviainjectionConfiguringmutualparent-childawarenesswithContentChildandforwardRefinstructsyouonhowtoproperlyuseContentChildtoreferencechildcomponentobjectinstances

Configuringmutualparent-childawarenesswithContentChildandforwardRefThecompaniontoAngular'sViewChildisContentChild.Itperformsasimilarduty;itretrievesareferencetothetargetchildcomponentandmakesitavailableasamemberoftheparentcomponentinstance.ThedifferenceisthatContentChildretrievesthemarkupthatexistsinsidetheparentcomponent'sselectortags,whereasViewChildretrievesthemarkupthatexistsinsidetheparentcomponent'sview.

Thedifferenceisbestdemonstratedbyacomparisonofbehavior,sothisrecipewillconverttheexamplefromConfiguringMutualParent-ChildAwarenesswithViewChildandforwardReftouseContentChildinstead.

Note



GettingreadyBeginwiththecodefromtheConfiguringmutualparent-childawarenesswithViewChildandforwardRefrecipe.

Howtodoit...Beforeyoubegintheconversion,you'llneedtonesttheArticleComponenttagsinsideanotherrootcomponent,asContentChildwillnotworkfortheroot-levelbootstrappedapplicationcomponent.CreateawrappedRootComponent:



@Component({

selector:'root',

template:`

<article></article>

`

})


ConvertingtoContentChild

ContentChildisintroducedtocomponentsinessentiallythesamewayasViewChild.InsideArticleComponent,performthisconversionandreplacethe<feedback>tagwith<ng-content>:


import{Component,ContentChild}from'@angular/core';


@Component({

selector:'article',

template:`



<ng-content></ng-content>

`

})


@ContentChild(FeedbackComponent)


likes:number=0;


this.likes++;

}



}

}

Ofcourse,thiswillonlybeabletofindthechildcomponentifthe<article></article>taghascontentinsideofit:



@Component({

selector:'root',

template:`

<article>

<feedback></feedback>

</article>

`

})


Note

You'llnoticethatthelikecountvaluebeingpassedtothechildcomponentasaninputhasbeenremoved.Verysimply,thatconventionwillnotworkanymore,asbindingitherewoulddrawthelikecountfromRootComponent,whichdoesnothavethisinformation.

Correctingdatabinding

TheFeedbackComponentwillneedtoretrievethelikecountdirectly:


import{Component,Inject,forwardRef}from'@angular/core';


@Component({


template:`


<button(click)="likeArticle()"

[disabled]="!likeEnabled">

Likethisarticle!

</button>

`

})


privateval:number;

privatelikeEnabled:boolean=false;





this.updateLikes();

}

updateLikes(){

this.val=this.articleComponent.likes;

}

likeArticle():void{


this.updateLikes();

}

setLikeEnabled(newEnabledStatus:boolean):void{

this.likeEnabled=newEnabledStatus;

}

}

That'sit!TheapplicationshouldbehaveidenticallytothesetupfromtheGettingreadysectionoftherecipe.

Howitworks...ContentChilddoesnearlythesamethingasViewChild;itjustlooksinadifferentplace.ContentChilddirectsAngulartofindthefirstinstanceofFeedbackComponentpresentinsidetheArticleComponenttags.Here,thisstepreferstoanythingthatisinterpolatedby<ng-content>.Itthenassignsthefoundcomponentinstancetothedecoratedclassmember.Thereferenceisupdatedalongwithanyviewupdates.Thisdecoratedmemberwillrefertothechildcomponentinstanceandcanbeinteractedwithlikeanynormalobjectinstance.

There'smore...SinceAngularperformshierarchicalrendering,ContentChildwillnotbereadyuntiltheviewisinitialized,butrather,aftertheAfterContentInitlifecyclehook.Thiscanbedemonstratedasfollows:


import{Component,ContentChild,ngAfterContentInit}



@Component({

selector:'article',

template:`




`

})

exportclassArticleComponentimplementsAfterContentInit{

@ContentChild(FeedbackComponent)


likes:number=0;

constructor(){


}

ngAfterContentInit(){


}


this.likes++;

}



}

}

Thiswillfirstlogundefinedinsidetheconstructorasthecontent,andthereforeFeedbackComponentdoesnotyetexist.OncetheAfterContentInitlifecyclehookoccurs,youwillbeabletoseeFeedbackComponentloggedtotheconsole.

ContentChildren

Ifyouwouldliketogetareferencetomultiplecomponents,youcanperformanidenticalreferenceacquisitionprocessusingContentChildren,whichwillprovideyouwithQueryList

ofallthematchingcomponentsinsidethecomponent'stags.

Tip

AQueryListcanbeusedlikeanarraywithitstoArray()method.Italsoexposesachangesproperty,whichemitsaneventeverytimeamemberofQueryListchanges.

SeealsoUtilizingcomponentlifecyclehooksgivesanexampleofhowyoucanintegratewithAngular2'scomponentrenderingflow.Referencingaparentcomponentfromachildcomponentdescribeshowacomponentcangainadirectreferencetoitsparentviainjection.Configuringmutualparent-childawarenesswithViewChildandforwardRefinstructsyouonhowtoproperlyuseViewChildtoreferencechildcomponentobjectinstances.

Chapter3.BuildingTemplate-DrivenandReactiveFormsThischapterwillcoverthefollowingrecipes:

Implementingsimpletwo-waydatabindingwithngModelImplementingbasicfieldvalidationwithaFormControlBundlingFormControlswithaFormGroupBundlingFormControlswithaFormArrayImplementingbasicformswithngFormImplementingbasicformswithFormBuilderandformControlNameCreatingandusingacustomvalidatorCreatingandusingacustomasynchronousvalidatorwithPromises

IntroductionFormsareimportantelementalconstructsfornearlyeverywebapplication,andtheyhavebeenreimaginedforthebetterinAngular2.Angular1formswereveryuseful,buttheyweretotallydependentontheconventionsofngModel.Angular2'snewfoundconventionsremoveitfromngModeldependenceandofferafreshapproachtoformandinformationmanagementthatultimatelyfeelscleanerandmoreapproachable.

Fundamentally,itisimportanttounderstandwhereandwhyformsareuseful.Therearemanyplacesinanapplicationwheremultitudinousinputdemandsassociation,andformsarecertainlyusefulinthiscontext.Angular2formsarebestusedwhenvalidatingthesaidinput,especiallysowhenmultiple-fieldandcross-fieldvalidationisrequired.Additionally,Angularformsmaintainthestateofvariousformelements,allowingtheusertoreasonthe"history"ofaninputfield.

ItisalsocriticaltorememberthattheAngular2formbehavior,muchinthesamewayasitseventanddatabinding,isgettingintegratedwiththealreadyrobustbrowserformbehavior.Browsersarealreadyverycapableofsubmittingdata,recallingdatauponapagereload,simplevalidation,andotherbehaviorsthatprettymuchallformsrelyupon.Angular2doesn'tredefinethese;rather,itintegrateswiththesebehaviorsinordertolinkinotherbehaviorsanddatathatarepartofeitheraframeworkoryourapplication.

Tip

Inthischapter,beawareofthedualityoftheuseofFormsModuleandReactiveFormsModule.Theybehaveverydifferentlyandarealmostalwaysusedseparatelywhenitcomestoformconstruction.

Implementingsimpletwo-waydatabindingwithngModelAngular2stillhastwo-waydatabinding,butthewayitbehavesisabitdifferentthanwhatyou'reusedto.Thisrecipewillbeginwithaverysimpleexampleandthenbreakitdownintopiecestodescribewhatit'sactuallydoing.

Note



Howtodoit...Two-waydatabindingusesthengModeldirective,whichisincludedinFormsModule.Addthisdirectivetoyourapplicationmodule:

[app/app.module.ts]



import{FormsModule}from'@angular/forms';

import{ArticleEditorComponent}from'./article-editor.component';

@NgModule({

imports:[

BrowserModule,

FormsModule

],

declarations:[

ArticleEditorComponent

],

bootstrap:[


]

})


Next,fleshoutyourcomponent,whichwillhavetwoinstancesofinputboundtothesamecomponentmemberusingngModel:

[app/article-editor.component.ts]


@Component({

selector:'article-editor',

template:`

<input[(ngModel)]="title">

<input[(ngModel)]="title">

<h2>{{title}}</h2>

`

})

exportclassArticleEditorComponent{

title:string;

}

That'sallthat'srequired!Youshouldseeinputmodificationsinstantlyreflectedintheotherinputaswellasin<h2>itself.

Howitworks...Whatyou'rereallydoingisbindingtotheeventandpropertythatngModelassociateswiththisinput.Whenthecomponent'stitlememberchanges,theinputisboundtothatvalueandwillupdateitsownvalue.Whentheinput'svaluechanges,itemitsanevent,whichngModelwillbindtoandextractthevaluefrombeforepropagatingittothecomponent'stitlemember.

Note

Thebanana-in-a-boxsyntax[()]issimplyindicativeofthebindingdonetoboththeinputpropertywith[]andtheinputeventswith().

Inreality,thisisshorthandforthefollowing:



@Component({


template:`

<input[ngModel]="title"(ngModelChange)="title=$event">

<input[ngModel]="title"(ngModelChange)="title=$event">

<h2>{{title}}</h2>

`

})


title:string;

}

Youwillfindthatthisbehavesidenticallytowhatwediscussedbefore.

There'smore...Youmightstillfindthatthere'sabittoomuchsyntacticalsugarhappeninghereforyourtaste.You'rebindingtongModel,butsomehow,itisequivalenttotheinputvalue.Similarly,you'rebindingtongModelChangeevents,whichareallemittinga$eventthatappearstobeonlyastring.

Thisisindeedcorrect.ThengModeldirectiveunderstandswhatitisapartofandisabletointegrate[ngModel]and(ngModelChange)correctlytoassociatethedesiredbindings.

Thecoreofthesebindingsisessentiallydoingthefollowing:



@Component({


template:`

<input[value]="title"(input)="title=$event.target.value">

<input[value]="title"(input)="title=$event.target.value">

<h2>{{title}}</h2>

`

})


//Initializetitle,otherwiseyou'llget"undefined"

title:string='';

}

SeealsoImplementingsimpletwo-waydatabindingwithngModeldemonstratesthenewwayinAngular2tocontrolbidirectionaldataflowImplementingbasicfieldvalidationwithaFormControldetailsthebasicbuildingblockofanAngularformBundlingFormControlswithaFormGroupshowshowtocombineFormControlsBundlingFormControlswithaFormArrayshowshowtohandleiterableformelementsImplementingbasicformswithngFormdemonstratesAngular'sdeclarativeformconstructionImplementingbasicformswithFormBuilderandformControlNameshowshowtousetheFormBuilderservicetoquicklyputtogethernestedformsCreatingandusingacustomvalidatordemonstrateshowtocreateacustomdirectivethatbehavesasinputvalidationCreatingandusingacustomasynchronousvalidatorwithPromisesshowshowAngularallowsyoutohaveadelayedevaluationofaformstate

ImplementingbasicfieldvalidationwithaFormControlThesimplestformbehaviorimaginablewouldbethevalidationofasingleinputfield.Mostofthetime,utilizing<form>tagsandgoingthroughtherestoftheboilerplateisgoodpractice,butforthepurposeofcheckingasingleinput,it'spreferabletodistillthisdowntothebareminimumrequiredinordertouseinputchecking.

Note



GettingreadySupposethefollowingisyourinitialsetup:



@Component({


template:`

<p>Articletitle(required):</p>

<inputrequired>

<button>Save</button>

<h1>{{title}}</h1>

`

})


title:string;

}

Yourgoalistochangethisinawaythatclickingthesavebuttonwillvalidatetheinputandupdatethetitlememberonlyifitisvalid.

Howtodoit...ThemostelementalcomponentofAngularformsistheFormControlobject.Inordertobeabletoassessthestateofthefield,youfirstneedtoinstantiatethisobjectinsidethecomponentandassociateitwiththefieldusingtheformControldirective.FormControllivesinsideReactiveFormsModule.Additasamoduleimport:

[app/app.module.ts]



import{ReactiveFormsModule}from'@angular/forms';


@NgModule({

imports:[

BrowserModule,

ReactiveFormsModule

],

declarations:[


],

bootstrap:[


]

})


Withthis,youcanuseFormControlinsideArticleEditorComponent.InstantiateFormControlinsidethecomponentandbindtheinputelementtoitusingtheformControldirective:



import{FormControl}from'@angular/forms';

@Component({


template:`


<input[formControl]="titleControl"required>

<button>Save</button>

<h1>{{title}}</h1>

`

})


title:string;

titleControl:FormControl=newFormControl();

}

NowthatyouhavecreatedaFormControlobjectandassociateditwithaninputfield,youwillbeabletouseitsvalidationAPItocheckthestateofthefield.Allthatisleftistouseitinsidethesubmitclickhandler:




@Component({


template:`


<input[formControl]="titleControl"required>

<button(click)="submitTitle()">Save</button>

<h1>{{title}}</h1>

`

})


title:string;

titleControl:FormControl=newFormControl();

submitTitle():void{

if(this.titleControl.valid){

this.title=this.titleControl.value;

}else{

alert("Titlerequired");

}

}

}

Withthis,thesubmitclickhandlerwillbeabletochecktheinput'svalidationstateandvaluewiththesameobject.

Howitworks...TheformControldirectiveservesonlytobindanexistingFormControlobjecttoaDOMelement.TheFormControlobjectthatyouinstantiateinsidethecomponentconstructorcaneitherutilizevalidationattributesinsideanHTMLtag(asisdoneinthisexample),oracceptAngularvalidatorswheninitialized;or,itcandoboth.

Note

It'sextremelyimportanttonotethatjustbecausetheFormControlobjectisinstantiated,itdoesnotmeanthatitisabletovalidatetheinputimmediately.

Withoutaninitializedvalue,anemptyinputfieldwillbeginitslifewithavalueofnull,whichinthepresenceofarequiredattributeisofcourseinvalid.However,inthisexample,ifyouweretocheckwhethertheFormControlobjectbecomesvalidimmediatelyafteryouinstantiateitintheconstructor,theFormControlobjectwoulddutifullyinformyouthatthestateisvalidsinceithasnotbeenboundtotheDOMelementyet,andtherefore,novalidationsarebeingviolated.Sincetheinputelement'sformControlbindingwillnotoccuruntilthecomponenttemplatebecomespartoftheactualDOM,youwillnotbeabletochecktheinputstateuntilthebindingiscompleteorinsidethengAfterContentCheckedlifecyclehook.Notethatthispertainstotheexampleunderconsideration.

OncetheformControldirectivecompletesthebinding,theFormControlobjectwillexistasaninputwrapper,allowingyoutouseitsvalidandvaluemembers.

There'smore...ThisrecipeusesReactiveFormsModule,whichissimplertounderstandsinceallofthesetupisexplicit.WhenyouuseFormsModuleinstead,youdiscoverthatalotofwhatisaccomplishedinthisrecipecouldbedoneautomaticallyforyou,suchastheinstantiationandbindingofFormControlobjects.Italsorevolvesaroundthepresenceofa<form>tag,whichisthedefactotop-levelFormControlcontainer.ThisrecipeservestodemonstrateoneofthesimplestformsofAngularformbehavior.

Validatorsandattributeduality

Asmentionedinthisrecipe,validationdefinitionscancomefromtwoplaces.Here,youusedastandardizedHTMLtagattributethatAngularrecognizesandautomaticallyincorporatesintotheFormControlvalidationspecification.YoucouldhavejustaseasilyelectedtoutilizeanAngularValidatortoaccomplishthesametaskinstead.ThiscanbeaccomplishedbyimportingAngular'sdefaultValidatorsandinitializingtheFormControlobjectwiththerequiredvalidator:



import{FormControl,Validators}from'@angular/forms';

@Component({


template:`


<input[formControl]="titleControl">

<button(click)="submitTitle()">Save</button>

<h1>{{title}}</h1>

`

})


title:string;

//Firstargumentisthedefaultinputvalue

titleControl:FormControl=

newFormControl(null,Validators.required);

submitTitle():void{

if(this.titleControl.valid){

this.title=this.titleControl.value;

}else{

alert("Titlerequired");

}

}

}

Taglesscontrols

Asyoumightsuspect,thereisnoreasonaFormControlmustbeboundtoaDOMelement.FormControlisanelementalpieceofformlogicthatactsasanatomicpieceofstatefulinformation,whetherornotthisinformationisderivedfrom<input>.SayyouwantedtoaddaFormControlthatwouldpreventquickformsubmissionbyonlybecomingvalidafter10seconds.YoucouldexplicitlycreateaFormControlobjectthatwouldtieintothecombinedformvalidationbutwouldnotbeassociatedwithaDOMelement.

SeealsoImplementingsimpletwo-waydatabindingwithngModeldemonstratesthenewwayinAngular2tocontrolbidirectionaldataflowBundlingFormControlswithaFormGroupshowshowtocombineFormControlobjectsBundlingFormControlswithaFormArrayshowshowtohandleiterableformelements

BundlingcontrolswithaFormGroupNaturally,formsinapplicationsfrequentlyexisttoaggregatemultipleinstancesofinputintoaunifiedbehavior.Onecommonbehavioristoassesswhetheraformisvalid,whichofcourserequiresthatallofitssubfieldsarevalid.ThiswillmostcommonlybeachievedbybundlingmultipleFormControlobjectsintoaFormGroup.Thiscanbedoneindifferentways,withvaryingdegreesofexplicitness.Thisrecipecoversanentirelyexplicitimplementation,thatis,everythingherewillbecreatedand"joined"manually.

Note



GettingreadySupposeyoubeganwiththefollowingskeletonapplication:



@Component({


template:`

<p>Title:<input></p>

<p>Text:<input></p>

<p><button(click)="saveArticle()">Save</button></p>

<hr/>

<p>Preview:</p>

<divstyle="border:1pxsolid#999;margin:50px;">


<p>{{article.text}}</p>

</div>

`

})


article:{title:string,text:string}={};

saveArticle():void{}

}

Yourgoalistoupdatethearticleobject(andconsequentlythetemplate)onlyifalltheinputfieldsarevalid.

Howtodoit...First,addthenecessarycodetoattachnewFormControlobjectstoeachinputfieldandvalidatethemwiththebuilt-inrequiredvalidator:



import{FormControl,Validators}

from'@angular/forms';

@Component({


template:`

<p>Title:<input[formControl]="titleControl"></p>

<p>Text:<input[formControl]="textControl"></p>


<hr/>

<p>Preview:</p>




</div>

`

})



titleControl:FormControl

=newFormControl(null,Validators.required);

textControl:FormControl



}

Atthispoint,youcouldindividuallyinspecteachinput'sFormControlobjectandcheckwhetheritisvalid.However,ifthisformgrowsto100fields,itwouldbecomeunbearablytedioustomaintainthem.Therefore,youcanbundletheseFormControlobjectsintoasingleFormGroupinstead:



import{FormControl,FormGroup,Validators}


@Component({


template:`




<hr/>

<p>Preview:</p>




</div>

`

})







articleFormGroup:FormGroup=newFormGroup({

title:this.titleControl,

text:this.textControl

});


}

FormGroupobjectsalsoexposevalidandvaluemembers,soyoucanusethesetoverifyandassigndirectlyfromtheobject:



import{FormControl,FormGroup,Validators}


@Component({


template:`




<hr/>

<p>Preview:</p>




</div>

`

})







articleFormGroup:FormGroup=newFormGroup({



});

saveArticle():void{

if(this.articleFormGroup.valid){

this.article=this.articleFormGroup.value;

}else{

alert("Missingfield(s)!");

}

}

Withthisaddition,yourformshouldnowbeworkingfine.

Howitworks...BothFormControlandFormGroupinheritfromtheabstractbaseclasscalledAbstractControl.Whatthismeansforyouisthatbothofthemexposethesamebaseclassmethods,butFormGroupwillaggregateitscompositionofAbstractControlobjectstobereadfromitsownmembers.Asyoucanseeintheprecedingcode,validactsasalogicalANDoperatorforallthechildren(meaningeverysinglechildmustreturntrueforittoreturntrue);valuereturnsanobjectofthesametopologyastheoneprovidedattheinstantiationofFormGroup,butwitheachFormControlvalueinsteadoftheFormControlobject.

Note

Asyoumightexpect,sinceFormGroupexpectsanobjectwithAbstractControlproperties,youarefreetonestaFormGroupinsideanotherFormGroup.

There'smore...YouareabletoaccessaFormGroup'scontainedFormControlmembersviathecontrolsproperty.ThestringthatyouusedtokeytheFormControlmembers—eitheruponFormGroupinstantiation,orwiththeaddControlmethod—isusedtoretrieveit.Inthisexample,thetextFormControlobjectcouldberetrievedinsideacomponentmethodviathis.articleCtrlGroup.controls.text.

Tip

TheAngulardocumentationwarnsyoutospecificallynottomodifytheunderlyingFormControlcollectiondirectly.Thismayleadtoanundefineddatabindingbehavior.So,alwaysbesuretousetheFormGroupmembermethodsaddControlandremoveControlinsteadofdirectlymanipulatingthecollectionofFormControlobjectsthatyoupassuponinstantiation.

FormGroupvalidators

LikeControl,aFormGroupcanhaveitsownvalidators.ThesecanbeprovidedwhentheFormGroupisinstantiated,andtheybehaveinthesamewaythataFormControlvalidatorwouldbehave.ByaddingvalidatorsattheFormGrouplevel,FormGroupcanoverridethedefaultbehaviorofonlybeingvalidwhenallitscomponentsarevalidoraddingextravalidationclauses.

Errorpropagation

Angularvalidatorsnotonlyhavetheabilitytodeterminewhethertheyarevalidornot,buttheyarealsocapableofreturningerrormessagesdescribingwhatiswrong.Forexample,whentheinputfieldsareempty,ifyouweretoexaminetheerrorspropertyofthetextFormControlobjectviathis.articleCtrlGroup.controls.text.errors,itwouldreturn{required:true}.Thisisthedefaulterrormessageofthebuilt-inrequiredvalidator.However,ifyouweretoinspecttheerrorspropertyontheparentFormGroupviathis.articleCtrlGroup.errors,youwillfindittobenull.

Thismaybecounter-intuitive,butitisnotamistake.ErrormessageswillonlyappearontheFormControlinstancethatiscausingthem.Ifyouwishtoaggregateerrormessages,youwillhavetotraversethenestedcollectionsofFormControlobjectsmanually.

SeealsoImplementingsimpletwo-waydatabindingwithngModeldemonstratesthenewwayinAngular2tocontrolbidirectionaldataflowImplementingbasicfieldvalidationwithaFormControldetailsthebasicbuildingblockofanAngularformBundlingFormControlswithaFormArrayshowshowtohandleiterableformelements

BundlingFormControlswithaFormArrayYouwillmostlikelyfindthatFormGroupsaremorethancapableofservingyourneedsforthepurposeofcombiningmanyFormControlobjectsintoonecontainer.However,thereisoneverycommonpatternthatmakesitssistertype,theFormArray,extremelyuseful:variablelengthclonedinputs.

Note



GettingreadySupposeyouhadthefollowingskeletonapplication:



import{FormControl,Validators}


@Component({


template:`

<p>Tags:</p>

<ul>

<li*ngFor="lettoftagControls;leti=index">

<input[formControl]="t">

</li>

</ul>

<p><button(click)="addTag()">+</button></p>


`

})


tagControls:Array<FormControl>=[];

addTag():void{}


}

Yourobjectiveistomodifythiscomponentsothatanarbitrarynumberoftagscanbeaddedandsoallthetagscanbevalidatedtogether.

Howtodoit...Inmanyways,aFormArraybehavesmoreorlessidenticallytoaFormGroup.ItisimportedinthesamewayandinheritedfromAbstractControl.Also,itisinstantiatedinasimilarwayandcanaddandremoveFormControlinstances.First,addtheboilerplatetoyourapplication;thiswillallowyoutoinstantiateaninstanceofaFormArrayandpassitthearrayofFormControlobjectsalreadyinsidethecomponent.SinceyoualreadyhaveabuttonthatismeanttoinvoketheaddTagmethod,youshouldalsoconfigurethismethodtopushanewFormControlontotagControl:



import{FormControl,FormArray,Validators}


@Component({


template:`

<p>Tags:</p>

<ul>



</li>

</ul>



`

})



tagFormArray:FormArray=newFormArray(this.tagControls);

addTag():void{

this.tagFormArray

.push(newFormControl(null,Validators.required));

}


}

Note

Atthispoint,it'simportantthatyoudon'tconfuseyourselfwithwhatyouareworkingwith.InsidethisArticleEditorcomponent,youhaveanarrayofFormControlobjects(tagControls)andyoualsohaveasingleinstanceofFormArray(tagFormArray).TheFormArrayinstanceisinitializedbybeingpassedthearrayofFormControlobjects,whichitwillthenbeabletomanage.

NowthatyourFormArrayismanagingthetag'sFormControlobjects,youcansafelyuseitsvalidator:





@Component({


template:`

<p>Tags:</p>

<ul>



</li>

</ul>



`

})




addTag():void{

this.tagFormArray


}

saveArticle():void{

if(this.tagFormArray.valid){

alert('Valid!');

}else{

alert('Missingfield(s)!');

}

}

}

Howitworks...Becausethetemplateisreactingtotheclickevent,youareabletouseAngulardatabindingtoautomaticallyupdatethetemplate.However,itisextremelyimportantthatyounotetheasymmetryinthisexample.ThetemplateisiteratingthroughthetagControlsarray.However,whenyouwanttoaddanewFormControlobject,youpushittotagFormArray,whichwillinturnpushittothetagControlsarray.TheFormArrayobjectactsasthemanagerofthecollectionofFormControlobjects,andallmodificationsofthiscollectionshouldgothroughthemanager,notthecollectionitself.

Tip

TheAngulardocumentationwarnsyoutospecificallynotmodifytheunderlyingFormControlcollectiondirectly.Thismayleadtoundefineddatabindingbehavior,soalwaysbesuretousetheFormArraymemberspush,insert,andremoveAtinsteadofdirectlymanipulatingthearrayofFormControlobjectsthatyoupassuponinstantiation.

There'smore...Youcantakethisexampleonestepfurtherbyaddingtheabilitytoremovefromthislistaswell.SinceyoualreadyhavetheindexinsidethetemplaterepeaterandFormArrayoffersindex-basedremoval,thisissimpletoimplement:





@Component({


template:`

<p>Tags:</p>

<ul>



<button(click)="removeTag(i)">X</button>

</li>

</ul>



`

})




addTag():void{

this.tagFormArray


}

removeTag(idx:number):void{

this.tagFormArray.removeAt(idx);

}

saveArticle():void{

if(this.tagFormArray.valid){

alert('Valid!');

}else{

alert('Missingfield(s)!');

}

}

}

ThisallowsyoutocleanlyinsertandremoveFormControlinstanceswhilelettingAngulardatabindingdoalloftheworkforyou.

SeealsoImplementingsimpletwo-waydatabindingwithngModeldemonstratesthenewwayinAngular2tocontrolbidirectionaldataflowImplementingbasicformswithngFormdemonstratesAngular'sdeclarativeformconstructionImplementingbasicformswithFormBuilderandformControlNameshowshowtousetheFormBuilderservicetoquicklyputtogethernestedforms

ImplementingbasicformswithNgFormThebasicdenominationsofAngularformsareFormControl,FormGroup,andFormArrayobjects.However,itisoftennotdirectlynecessarytousetheseobjectsatall;Angularprovidesmechanismswithwhichyoucanimplicitlycreateandassigntheseobjectsandattachthemtotheform'sDOMelements.

Note






@Component({


template:`

<p><inputplaceholder="Articletitle"></p>

<p><textareaplaceholder="Articletext"></textarea></p>


`

})



}

YourobjectiveistocollectalloftheformdataandsubmititusingAngular'sformconstructs.

Howtodoit...Youshouldbeginbyreorganizingthisintoanactualbrowserform.Angulargivesyoualotofdirectivesandcomponentsforthis,andimportingtheFormsModulewillgiveyouaccesstoalltheonesyouneedmostofthetime:

[app/app.module.ts]



import{FormsModule}from'@angular/forms';


@NgModule({

imports:[

BrowserModule,

FormsModule

],

declarations:[


],

bootstrap:[


]

})


Inaddition,youshouldreconfigurethebuttonsoitbecomesanactualsubmitbutton.Thehandlershouldbetriggeredwhentheformissubmitted,soyoucanreattachthelistenertotheform'snativesubmiteventinsteadofthebutton'sclickevent.AngularprovidesanngSubmitEventEmitterontopofthisevent,sogoaheadandattachthelistenertothis:



@Component({


template:`

<form(ngSubmit)="saveArticle()">



<p><buttontype="submit">Save</button></p>

</form>

`

})



}

Next,youshouldconfiguretheformtopasstheformdatatothehandlerthroughatemplatevariable.

Note

TheformelementwillhaveanNgFormobject(andinsidethis,aFormGroup)automaticallyassociatedwithitwhenyouimportFormsModuleintotheencompassingmodule.AngularcreatesandassociatestheNgForminstancebehindthescenes.

OnewayyoucanaccessthisinstanceisbyassigningthengFormdirectiveasatemplatevariable.It'sabitofsyntacticalmagic,butusing#f="ngForm"signalstoAngularthatyouwanttobeabletoreferencetheform'sNgFormfromthetemplateusingthefvariable.

Onceyoudeclarethetemplatevariable,youareabletopassthengForminstancetothesubmithandlerasanargument,specificallyassaveArticle(f).

Thisleavesyouwiththefollowing:



import{NgForm}from'@angular/forms';

@Component({


template:`

<form#f="ngForm"

(ngSubmit)="saveArticle(f)">




</form>

`

})


saveArticle(f:NgForm):void{

console.log(f);

}

}

Whenyoutestthismanually,youshouldseeyourbrowserlogginganNgFormobjecteverytimeyouclickontheSavebutton.Insidethisobject,youshouldseeashinynewFormGroupandalsothengSubmitEventEmitterthatyouarelisteningto.Sofar,sogood!

DeclaringformfieldswithngModel

Youmayhavenoticedthatnoneoftheformfieldshavebeencollected.This,ofcourse,isbecauseAngularhasnotbeeninstructedtopayattentiontothem.Forthis,FormsModuleprovidesyouwithngModel,whichwilldocertainthingsforyou:

InstantiateaFormControlobject.AttachittotheDOMelementthatincorporatesthengModelattribute.LocatetheFormGroupthattheelementlivesinsideandaddtoittheFormControlitjustcreated.ThestringvalueofthenameattributewillbeitskeyinsidetheFormGroup.

Note

Thislastbulletisimportant,asattemptingtousengModelwithoutanencompassingformcontrolconstructtoattachitselftowillresultinerrors.Thisformcontrolconstructcanbetheform'sFormGroupitself,oritcanevenbeachildFormGroupinstance.

Withthis,goaheadandaddngModeltoeachofthetextinputfields:



@Component({


template:`

<form#f="ngForm"


<p><inputngModel

name="title"

placeholder="Articletitle"></p>

<p><textareangModel

name="text"

placeholder="Articletext"></textarea></p>


</form>

`

})



console.log(f);

}

}

Yourformshouldnowbefullyfunctional.Inthesubmithandler,youcanverifythatFormGrouphastwoFormControlobjectsattachedtoitbyinspectingf.form.controls,whichshouldgiveyouthefollowing:

{

text:FormControl{...},

title:FormControl{...}

}

Howitworks...Inessence,youareusingthehierarchicalnatureoftheDOMtodirecthowyourFormControlarchitectureisstructured.ThetopmostNgForminstanceiscoupledwithaFormGroup;insidethis,therestoftheform'sFormControlobjectswillreside.

EachngModeldirectsitsreferencedFormControltotheFormGroupownedbytheNgForminstance.Withthisnestedstructurenowassembled,itispossibletoreadandreasonthestateoftheentireformfromtheNgFormobject.Thisbeingthecase,passingthisobjecttothesubmithandlerwillallowyoutomanageeveryaspectofforminspectionandvalidation.

There'smore...If,instead,youwantedtogroupsomeofthesefieldstogether,thiscanbeaccomplishedbysimplywrappingthemwithanngModelGroupdirective.SimilartongModel,thisautomaticallyinstantiatesaFormGroupandattachesittotheparentFormGroup;also,itwilladdanyenclosedFormControlorFormGroupobjectstoitself.Forexample,refertothefollowing:




@Component({


template:`

<form#f="ngForm"


<divngModelGroup="article">

<p><inputngModel

name="title"


<p><textareangModel

name="text"


</div>


</form>

`

})



console.log(f);

}

}

Now,inspectingf.form.controlswillrevealthatithasasingleFormGroupkeyedbyarticle:

{

article:FormGroup:{

controls:{

text:FormControl{...},

title:FormControl{...}

},

...

}

}

Sincethismatchesthestructureyousetupinthetemplate,itchecksout.

SeealsoImplementingsimpletwo-waydatabindingwithngModeldemonstratesthenewwayinAngular2tocontrolbidirectionaldataflowImplementingbasicformswithFormBuilderandformControlNameshowshowtousetheFormBuilderservicetoquicklyputtogethernestedforms

ImplementingbasicformswithFormBuilderandformControlNameOutofthebox,Angularprovidesawayforyoutoputtogetherformsthatdon'trelyonthetemplatehierarchyfordefinition.Instead,youcanuseFormBuildertoexplicitlydefinehowyouwanttostructuretheformobjectsandthenmanuallyattachthemtoeachinput.

Note






@Component({


template:`




`

})


constructor(){}


}

YourobjectiveistocollectalloftheformdataandsubmititusingAngular'sformconstructs.

Howtodoit...FormBuilderisincludedinReactiveFormsModule,soyouwillneedtoimportthesetargetsintotheapplicationmodule:

[app/app.module.ts]





@NgModule({

imports:[

BrowserModule,

ReactiveFormsModule

],

declarations:[


],

bootstrap:[


]

})


Additionally,youwillneedtoinjectitintoyourcomponenttomakeuseofit.InAngular2,thiscansimplybeaccomplishedbylistingitasatypedconstructorparameter.TheFormBuilderusesthegroup()methodtoreturnthetop-levelFormGroup,whichyoushouldassigntoyourcomponentinstance.Fornow,youwillpassanemptyobjectasitsonlyargument.

Withallthis,youcanintegratethearticleGroupFormGroupintothetemplatebyattachingitinsideaformtagusingtheformGroupdirective:


import{Component,Inject}from'@angular/core';

import{FormBuilder,FormGroup}from'@angular/forms';

@Component({


template:`

<form[formGroup]="articleGroup"

(ngSubmit)="saveArticle()">




</form>

`

})


articleGroup:FormGroup;

constructor(@Inject(FormBuilder)formBuilder:FormBuilder){

this.articleGroup=formBuilder.group({});

}


}

Withallthis,youhavesuccessfullycreatedthestructureforyourform,butFormGroupisstillnotconnectedtothemultipleinput.Forthis,youwillfirstsetupthestructureofthecontrolsinsidethebuilderandconsequentlyattachthemtoeachinputtagwithformControlName,asfollows:



import{FormBuilder,FormGroup,Validators}from'@angular/forms';

@Component({


template:`



<p><inputformControlName="title"


<p><textareaformControlName="text"



</form>

`

})




this.articleGroup=formBuilder.group({

title:[null,Validators.required],

text:[null,Validators.required]

});

}

saveArticle():void{

console.log(this.articleGroup);

}

}

Withthis,yourformwillhavetwoFormControlobjectsinstantiatedinsideit,andtheywillbeassociatedwithproperinputelements.WhenyouclickonSubmit,youwillbeabletoseetheinputFormControlsinsideFormGroup.However,youmayprefertonamespacetheseFormControlobjectsinsideanarticledesignation,andyoucaneasilydothisbyintroducinganngFormGroupandacorrespondinglevelofindirectioninsidetheformBuilderdefinition:



import{FormBuilder,FormGroup,Validators}from'@angular/forms';

@Component({


template:`



<divformGroupName="article">

<p><inputformControlName="title"


<p><textareaformControlName="text"


</div>


</form>

`

})





article:formBuilder.group({

title:[null,Validators.required],

text:[null,Validators.required]

})

});

}

saveArticle():void{


}

}

Now,thetitleandtextFormControlobjectswillexistnestedinsideanarticleFormGroupandtheycanbesuccessfullyvalidatedandinspectedinthesubmithandler.

Howitworks...Asyoumightsuspect,thearrayslivinginsidetheformBuilder.groupdefinitionswillbeappliedasargumentstoaFormControlconstructor.ThisisnicesinceyoucanavoidthenewFormControl()boilerplatewhencreatingeachcontrol.ThestringthatkeystheFormControlislinkedtoitwithformControlName.BecauseyouareusingformControlNameandformGroupName,youwillneedtohavetheformBuildernestedstructurematchexactlytowhatisthereinthetemplate.

There'smore...ItistotallyunderstandablethathavingtoduplicatethestructureinthetemplateandtheFormBuilderdefinitionisalittleannoying.Thisisespeciallytrueinthiscase,asthepresenceofformGroupdoesn'treallyaddanyvaluablebehaviorsinceitisattachedtoaninertdivelement.Instead,youmightwanttobeabletodothisarticlenamespacegroupingwithoutmodifyingthetemplate.ThisbehaviorcanbeaccomplishedwithformControl,whosebehaviorissimilartoformModel(itbindstoanexistinginstanceonthecomponent).

Note

Notetheparadigmthatisbeingdemonstratedwiththesedifferentkindsofformdirectives.WiththingssuchasngForm,formGroup,formArray,andformControl,Angularisimplicitlycreatingandlinkingtheseinstances.IfyouchoosetonotuseFormBuildertodefinehowFormControlsbehave,thiscanbeaccomplishedbyaddingvalidationdirectivestothetemplate.Ontheotherhand,youalsohaveformModelandformControl,whichbindtotheinstancesofthesecontrolobjectsthatyoumustmanuallycreateonthecomponent.



import{FormBuilder,FormControl,FormGroup,Validators}


@Component({


template:`



<p><input[formControl]="titleControl"


<p><textarea[formControl]="textControl"



</form>

`

})









article:formBuilder.group({



})

});

}

saveArticle():void{


}

}

Importantly,notethatyouhavecreatedanidenticaloutputoftheoneyoucreatedearlier.titleandtextarebundledinsideanarticleFormGroup.However,thetemplatedoesn'tneedtohaveanyreferencetothisintermediateFormGroup.

SeealsoImplementingsimpletwo-waydatabindingwithngModeldemonstratesthenewwayinAngular2tocontrolbidirectionaldataflowImplementingbasicfieldvalidationwithaFormControldetailsthebasicbuildingblockofanAngularformImplementingbasicformswithngFormdemonstratesAngular'sdeclarativeformconstruction

CreatingandusingacustomvalidatorThebasicbuilt-invalidatorsthatAngularprovideswillgetyouofftheground,butifyourapplicationreliesonforms,youwillundoubtedlycometoapointwhereyouwillwanttodefineyourownvalidatorlogic.

Note



GettingreadySupposeyouhadstartedwiththefollowingskeletonapplication:




@Component({


template:`

<h2>PsychStudyonHumilityWinsMajorAward</h2>

<textarea[formControl]="bodyControl"

placeholder="Articletext"></textarea>


`

})


articleBody:string='';

bodyControl:Control


saveArticle():void{

if(this.bodyControl.valid){

alert('Valid!');

}else{

alert('Invalid!');

}

}

}

Yourobjectiveistoaddanadditionalvalidationtothetextareathatwilllimititto10words.(Theeditorialstaffisbigonbrevity.)

Howtodoit...IfyoulookatthefunctionsignatureofanAbstractControl,youwillnoticethatthevalidatorargumentisjustaValidatorFn.ThisvalidatorfunctioncanbeanyfunctionthatacceptsanAbstractControlobjectasitssoleargumentandreturnsanobjectkeyedwithstringsfortheerrorobject.Thiserrorobjectactsasadictionaryoferrors,andavalidatorcanreturnasmanyerrorsasapplicable.Thevalueofthedictionaryentrycan(andshould)containmetadataaboutwhatiscausingtheerror.Iftherearenoerrorsfoundbythecustomvalidator,itshouldjustreturnnull.

Thesimplestwaytoimplementthisisbyaddingamembermethodtothecomponent:


exportclassArticleEditor{

articleBody:string

bodyCtrl:Control

constructor(){

this.articleBody='';

this.bodyCtrl=newControl('',Validators.required);

}

wordCtValidator(c:Control):{[key:string]:any}{

letwordCt:number=(c.value.match(/\S+/g)||[]).length;

returnwordCt<=10?

null:

{'maxwords':{'limit':10,'actual':wordCt}};

}

saveArticle(){

if(this.bodyCtrl.valid){

alert('Valid!');

}else{

alert('Invalid!');

}

}

}

Note

Here,you'reusingaregularexpressiontomatchanynon-whitespacestrings,whichcanbetreatedasa"word."YoualsoneedtoinitializetheFormControlobjecttoanemptystringsinceyouareusingthestringprototype'smatchmethod.Sincethisregularexpressionwillreturnnullwhentherearenomatches,afallback||[]clauseisaddedtoalwaysyieldsomethingthathasalengthmethod.

Nowthatthevalidatormethodisdefined,youneedtoactuallyuseitonFormControl.Angularallowsyoutobundleanarrayofvalidatorsintoasinglevalidator,evaluatingtheminorder:




@Component({


template:`





`

})



bodyControl:FormControl=newFormControl(null,

[Validators.required,this.wordCtValidator]);

wordCtValidator(c:FormControl):{[key:string]:any}{

letwordCt:number

=((c.value||'').match(/\S+/g)||[]).length;

returnwordCt<=10?

null:

{maxwords:{limit:10,actual:wordCt}};

}

saveArticle():void{


alert('Valid!');

}else{

alert('Invalid!');

}

}

}

Withthis,yourFormControlshouldnowonlybevalidwhenthereare10wordsorfewerandtheinputisnotempty.

Howitworks...AFormControlexpectsaValidatorFnwithaspecifiedreturntype,butitdoesnotcarewhereitcomesfrom.Therefore,youwereabletodefineamethodinsidethecomponentclassandjustpassitalongwhenFormControlwasinstantiated.

TheFormControlobjectassociatedwithagiveninputmustbeabletohavevalidatorsassociatedwithit.Inthisrecipe,youfirstimplementedcustomvalidationusingexplicitassociationviatheinstantiationargumentsanddefiningthevalidatorasasimplestandaloneValidationFn.

There'smore...Yourinnersoftwareengineershouldbetotallydissatisfiedwiththissolution.Thevalidatoryoujustdefinedcannotbeusedoutsidethiscomponentwithoutinjectingtheentirecomponent,andexplicitlylistingeveryvalidatorwheninstantiatingtheFormControlisamajorpain.

Refactoringintovalidatorattributes

AsuperiorsolutionistoimplementaformalValidatorclass.Thishasseveralbenefits:youwillbeabletoimport/exporttheclassandusethevalidatorasanattributeinthetemplate,whichobviatestheneedforbundlingvalidatorswithValidators.compose.

Yourstrategyshouldbetocreateadirectivethatcanfunctionnotonlyasanattribute,butalsoassomethingthatAngularcanrecognizeasaformalValidatorandautomaticallyincorporateitassuch.ThiscanbeaccomplishedbycreatingadirectivethatimplementstheValidatorinterfaceandalsobundlesthenewValidatordirectiveintotheexistingNG_VALIDATORStoken.

Note

Fornow,don'tworryaboutthespecificsofwhatishappeningwiththeprovidersarrayinsidethedirectivemetadataobject.Thiswillbecoveredindepthinthechapterondependencyinjection.AllthatyouneedtoknowhereisthatthiscodeisallowingtheFormControlobjectboundtotextareatoassociatethecustomvalidatoryouarebuildingwithit.

First,movethevalidationmethodtoitsowndirectivebyperformingthestepsmentionedintheprecedingparagraph:

[app/max-word-count.validator.ts]


import{Validator,FormControl,NG_VALIDATORS}


@Directive({

selector:'[max-word-count]',

providers:[{

provide:NG_VALIDATORS,

useExisting:MaxWordCountValidator,

multi:true

}]

})

exportclassMaxWordCountValidatorimplementsValidator{

validate(c:FormControl):{[key:string]:any}{

letwordCt:number=((c.value||'')

.match(/\S+/g)||[]).length;

returnwordCt<=10?

null:

{maxwords:{limit:10,actual:wordCt}};

}

}

Next,addthisdirectivetotheapplicationmodule:

[app/app.module.ts]





import{MaxWordCountValidator}from'./max-word-count.validator';

@NgModule({

imports:[

BrowserModule,

ReactiveFormsModule

],

declarations:[

ArticleEditorComponent,

MaxWordCountValidator

],

bootstrap:[


]

})


Thismakesitavailabletoallthecomponentsinthismodule.What'smore,theproviderconfigurationyouspecifiedbeforeallowsyoutosimplyaddthedirectiveattributetoanyinput,andAngularwillbeabletoincorporateitsvalidationfunctionintothatFormControl.Theintegrationisasfollows:




@Component({


template:`



required

max-word-count



`

})



bodyControl:FormControl=newFormControl();

saveArticle():void{


alert('Valid!');

}else{

alert('Invalid!');

}

}

}

Thisisalreadyfarsuperior.TheMaxWordCountdirectivecannowbeimportedandusedanywhereinourapplicationbysimplylistingitasadirectivedependencyinacomponent.There'snoneedfortheValidator.composenastinesswheninstantiatingaFormControlobject.

Tip

ThisisespeciallyusefulwhenyouareimplicitlycreatingtheseFormControlobjectswithformControlandotherbuilt-informdirectives,whichformanyapplicationswillbetheprimaryformutilizationmethod.Buildingyourcustomvalidatorasanattributedirectivewillintegrateseamlesslyinthesesituations.

Youshouldstillbedissatisfiedthough,asthevalidatorishardcodedtocheckfor10words.Youwouldinsteadliketoleavethisuptotheinputthatisusingit.Therefore,youshouldchangethedirectivetoacceptasingleparameter,whichwilltaketheformoftheattribute'svalue:

[app/max-word-count.validator.ts]


import{Validator,FormControl,NG_VALIDATORS}


@Directive({

selector:'[max-word-count]',

inputs:['rawCount:max-word-count'],

providers:[{

provide:NG_VALIDATORS,

useExisting:MaxWordCountValidator,

multi:true

}]

})

exportclassMaxWordCountValidatorimplementsValidator{

rawCount:string;

validate(c:FormControl):{[key:string]:any}{

letwordCt:number=

((c.value||'').match(/\S+/g)||[]).length;

returnwordCt<=this.maxCount?

null:

{maxwords:{limit:this.maxCount,actual:wordCt}};

}

getmaxCount():number{

returnparseInt(this.rawCount);

}

}




@Component({


template:`



required

max-word-count="10"



`

})




saveArticle():void{


alert('Valid!');

}else{

alert('Invalid!');

}

}

}

Nowyouhavedefinedthevalueoftheattributeasaninputtothevalidator,whichyoucanthenusetoconfigurehowthevalidatorwilloperate.

SeealsoCreatingandusingacustomasynchronousvalidatorwithPromisesshowshowAngularallowsyoutohaveadelayedevaluationoftheformstate

CreatingandusingacustomasynchronousvalidatorwithPromisesAstandardvalidatoroperatesundertheassumptionthatthevalidityofacertaininputcanbecalculatedinashortamountoftimethattheapplicationcanwaittogetoverwithbeforeitcontinuesfurther.What'smore,Angularwillrunthisvalidationeverytimethevalidatorisinvoked,whichmightbequiteoftenifformvalidationisboundtorapid-fireeventssuchaskeypresses.

Therefore,itmakesgoodsensethataconstructexiststhatwillallowyoutosmoothlyhandlethevalidationproceduresthattakeanarbitraryamountoftimetoexecuteorproceduresthatmightnotreturnatall.Forthis,AngularoffersasyncValidator,whichisfullycompatiblewithPromises.

Note



GettingreadySupposeyouhadstartedwiththefollowingskeletonapplication:




@Component({


template:`

<h2>NewYork-StylePizzaActuallySaucyCardboard</h2>


placeholder="Articletext">

</textarea>


`

})




saveArticle():void{


alert('Valid!');

}else{

alert('Invalid!');

}

}

}

Yourobjectiveistoconfigurethisforminawaythatitwillbecomevalidonly5secondsaftertheuserenterstheinputinordertodetersimplespambots.

Howtodoit...First,createyourvalidatorclass,andinsideit,placeastaticvalidationmethod.Thisissimilartoasynchronousvalidationmethod,butitwillinsteadreturnaPromiseobject,passingtheresultdatatotheresolvemethod.TheFormControlobjectacceptstheasyncValidatorasitsthirdargument.Ifyouweren'tusinganynormalValidators,youcouldleaveitasnull.

Tip

AsyouwouldcombineseveralValidatorsintooneusingValidators.compose,asyncValidatorscanbecombinedusingValidators.composeAsync.

Createthevalidatorskeletoninitsownfile:

[app/delay.validator.ts]

import{FormControl,Validator}from'@angular/forms';

exportclassDelayValidatorimplementsValidator{

staticvalidate(c:FormControl):Promise<{[key:string]:any}>{

}

}

Thoughthevalidatordoesnotyetdoanything,youmaystilladdittothecomponent:




import{DelayValidator}from'./delay.validator';

@Component({


template:`

<h2>NewYork-StylePizzaActuallySaucyCardboard</h2>


placeholder="Articletext">

</textarea>


`

})



bodyControl:FormControl=

newFormControl(null,null,DelayValidator.validate);

saveArticle():void{


alert('Valid!');

}else{

alert('Invalid!');

}

}

}

Thevalidatormustreturnapromise,butthispromisedoesn'teverneedtoberesolved.Furthermore,you'dliketosetthedelaytoonlyonetimeperrendering.Sointhiscase,youcanjustattachthepromisetotheFormControl:

[app/delay.validator.ts]

import{FormControl,Validator}from'@angular/forms';

exportclassDelayValidatorimplementsValidator{

staticvalidate(c:FormControl):Promise<{[key:string]:any}>{

if(c.pristine&&!c.value){

returnnewPromise;

}

if(!c.delayPromise){

c.delayPromise=newPromise((resolve)=>{

setTimeout(()=>{

console.log('resolve');

resolve();

},5000);

});

}

returnc.delayPromise;

}

}

Withthisaddition,theformwillremaininvaliduntil5secondsafterthefirsttimethevalueofthetextareaischanged.

Howitworks...Asynchronousvalidatorsarehandledindependentlyviaregular(synchronous)validators,butotherthantheirinternallatencydifferences,theyultimatelybehaveinnearlytheexactsameway.TheimportantdifferenceisthatanasyncValidator,apartfromthevalidandinvalidstatesthatitshareswithanormalValidator,hasapendingstate.TheFormControlwillremaininthisstateuntilapromiseismadeindicatingtheValidatorwillreturneitherresolvesorrejects.

Note

AFormControlinapendingstateistreatedasinvalidforthepurposeofcheckingthevalidityofaggregatingconstructs,suchasFormGrouporFormArray.

IntheValidatoryoujustcreated,checkingthepristinepropertyofFormControlisafinewayofascertainingwhetherornottheformis"fresh."Beforetheusermodifiestheinput,pristineistrue;followinganymodification(evenremovingalloftheenteredtext),pristinebecomesfalse.Therefore,itisaperfecttoolinthisexample,asitallowsustohavetheFormControlmaintaintheformstatewithoutovercomplicatingtheValidator.

There'smore...It'scriticaltonotetheformthatthisvalidatortakes.ThevalidationmethodinsidetheDelayValidatorclassisastaticmethodandnowhereistheDelayValidatorclassbeinginstantiated.Thepurposeoftheclassismerelytohousethevalidator.Therefore,youareunabletostoreinformationinsidethisclass,sincetherearenoinstancesinwhichyoucandoso.

Tip

Inthisexample,youmightbetemptedtoaddmemberdatatothevalidatorsinceyouwanttotrackwhethertheinputhasbeenmodifiedyet.Doingsoisverymuchananti-pattern!TheFormControlobjectshouldactasyoursolesourceofstatefulinformationinthisscenario.AFormControlobjectisinstantiatedforeachinputfield,andthereforeitistheideal"datastore"withwhichyoucantrackwhattheinputisdoing.

Validatorexecution

Ifyouweretoinspectwhenthevalidatormethodisbeingcalled,youwouldfindthatitexecutesonlyonakeypressinsidetextarea.Thismayseemarbitrary,butthedefaultFormControl/inputassignmentistoevaluatethevalidatorsofFormControlonachangeeventemittedfromtheinput.FormControlobjectsexposearegisterOnChangemethod,whichletsyouhookontothesamepointthatthevalidatorswillbeevaluated.

SeealsoCreatingandusingacustomvalidatordemonstrateshowtocreateacustomdirectivethatbehavesasinputvalidation

Chapter4.MasteringPromisesThischapterwillcoverthefollowingrecipes:

UnderstandingandimplementingbasicPromisesChainingPromisesandPromisehandlersCreatingPromisewrapperswithPromise.resolve()andPromise.reject()ImplementingPromisebarrierswithPromise.all()CancelingasynchronousactionswithPromise.race()ConvertingaPromiseintoanObservableConvertinganHTTPserviceObservableintoZoneAwarePromise

IntroductionInAngular1,promisesactedasstrangebirds.Theywereessentialforbuildingrobustasynchronousapplications,butusingthemseemedtocomeataprice.Theirimplementationbywayofthe$qserviceandthedualityofpromiseanddeferredobjectsseemedbizarre.Nonetheless,onceyouwereabletomasterthem,itwaseasytoseehowtheycouldbethefoundationofextremelyrobustimplementationsinthesingle-threadedevent-drivenworldofJavaScript.

Fortunately,fordeveloperseverywhere,ES6formallyembracesthePromisefeatureasacentralcomponent.SinceTypeScriptisasupersetofES6,youwillbepleasedtoknowthatyoucanwieldpromiseseverywhereinAngularwithoutextrabaggage.AlthoughObservablessubsumealotoftheutilityofferedbypromises,thereisstillverymuchaplacefortheminyourtoolkit.

Tip

BeingabletousePromisesnativelyisaprivilegeofTypeScripttoaJavaScripttranspilation.Asofnow,somebrowserssupportPromisesnatively,whilesomedonot.Goodnewsisthatifyou'rewritingyourapplicationsinTypeScriptandaretranspilingthemproperly,youdon'thavetoworryaboutthis!Really,theonlytimeyouwouldneedtoconsidertheactualtranspilationmechanicsiswhenyouneedinformationrelatedtotheperformanceorpayloadsizebenefitsofnativeimplementationsversustheirrespectivepolyfills,andthisshouldneverbeanissuefornearlyallapplications.

UnderstandingandimplementingbasicPromisesPromisesareveryusefulinmanyofthecoreaspectsofAngular.Althoughtheyarenolongerboundtothecoreframeworkservice,theystillmanifestthemselvesthroughoutAngular'sAPIs.TheimplementationisconsiderablysimplerthanAngular1,butthemainrhythmshaveremainedconsistent.

Note

Youcanrefertothecode,links,andaliveexampleofthisathttp://ngcookbook.herokuapp.com/5195.


GettingreadyBeforeyoustartusingpromises,youshouldfirstunderstandtheproblemtheyaretryingtosolve.Withoutworryingtoomuchabouttheinternals,youcanclassifytheconceptofaPromiseintothreedistinctstages:

Initialization:IhaveapieceofworkthatIwanttoaccomplish,andIwanttodefinewhatshouldhappenwhenthisworkiscompleted.Idonotknowwhetherthisworkwillbeevercompleted;also,theworkmayeitherfailorsucceed.Pending:Ihavestartedthework,butithasnotbeencompletedyet.Completed:Theworkisfinished,andthepromiseassumesafinalstate.The"completed"stateassumestwoforms:resolvedandrejected.Thesecorrespondtosuccessandfailure,respectively.

Thereismorenuancetohowpromiseswork,butfornow,thisissufficienttogetintosomeofthecode.

Howtodoit...Apromiseimplementationinoneofitssimplestformsisasfollows:

//promisesareinstantiatedwiththe'new'keyword

varpromise=newPromise(()=>{});

ThefunctionpassedtothePromiseconstructoristhepieceofworkthatisexpectedtoexecuteasynchronously.Theformaltermforthisfunctionisexecutor.

Note

ThePromiseconstructordoesn'tcareatallabouthowtheexecutorfunctionbehaves.Itmerelyprovidesitwiththetworesolveandrejectfunctions.Itisleftuptotheexecutorfunctiontoutilizethemappropriately.Notethattheexecutorfunctiondoesn'tneedtobeasynchronousatall;however,ifitisn'tasynchronous,thenyoumightnotneedaPromiseforwhatyouaretryingtoaccomplish.

Whenthisfunctionisexecuted,internallyitunderstandswhenitiscompleted;however,ontheoutside,thereisnoconstructthatrepresentstheconceptof"runthiswhentheexecutorfunctioniscompleted".Therefore,itsfirsttwoparametersaretheresolveandrejectfunctions.Thepromisewrappingtheexecutorfunctionisinthependingstateuntiloneoftheseisinvoked.Onceinvoked,thepromiseirreversiblyassumestherespectivestate.

Note

Theexecutorfunctionisinvokedimmediatelywhenthepromiseisinstantiated.Justasimportantly,itisinvokedbeforethepromiseinstantiationisreturned.Thismeansthatifthepromisereacheseitherafulfilledorrejectedstateinsidetheexecutorsynchronously,thenthereturnvalueofnewPromise(...)willbethefreshlyconstructedPromisewitharesolvedorrejectedstatus,skippingthependingstateentirely.

Thereturnvalueofexecutorisunimportant.Nomatterwhatitreturns,thepromiseconstructorwillalwaysreturnthefreshlycreatedpromise.

Thefollowingcodedemonstratesfivedifferentexamplesofwaysthatapromisecanbeinstantiated,resolved,orrejected:

//Thisexecutorispassedresolveandreject,butis

//effectivelyano-op,sothepromisep2willforever

//remaininthe'pending'state.

constp1=newPromise((resolve,reject)=>{});

//Thisexecutorinvokes'resolve'immediately,so

//p2willtransitiondirectlytothe'fulfilled'state.

constp2=newPromise((resolve,reject)=>resolve());

//Thisexecutorinvokes'reject'immediately,so

//p3willtransitiondirectlytothe'rejected'state.

//Atransitiontothe'rejected'statewillalsothrow

//anexception.Thisexceptionisthrownafterthe

//executorcompletes,soanylogicfollowingthe

//invocationofrejectwillstillbeexecuted.

constp3=newPromise((resolve,reject)=>{

reject();

//Thislog()printsbeforetheexceptionisthrown

console.log('Igotrejected!');

});

//Thisexecutorinvokes'resolve'immediately,so

//p4willtransitiondirectlytothe'fulfilled'state.

//Onceapromiseexitsthe'pending'state,itcannotchange

//again,soeventhoughrejectisinvokedafterwards,the

//finalstateofp4isstill'fulfilled'.


resolve();

reject();

});

//Thisexecutorassignsitsresolvefunctiontoavariable

//intheencompassinglexicalscopesoitcanbecalled

//outsidethepromisedefinition.

varouterResolve;


outerResolve=resolve();

});

//Stateofp5is'pending'

outerResolve();

//Stateofp5is'fulfilled'

Withwhatyou'vedonesofar,youwillnotfindthepromiseconstructtobeofmuchuse;thisisbecauseallthattheprecedingcodeaccomplishesisthesettingupofthestateofasinglepromise.Therealvalueemergeswhenyousetthesubsequentstatehandlers.APromiseobject'sAPIexposesathen()method,whichallowsyoutosethandlerstobeexecutedwhenthePromisereachesitsfinalstate:

//p1isasimplepromisetowhichyoucanattachhandlers

constp1=newPromise((resolve,reject)=>{});

//p1exposesathen()methodwhichacceptsa

//resolvehandler(onFulfilled),anda

//rejecthandler(onRejected)

p1.then(

//onFulfilledisinvokedwhenresolve()isinvoked

()=>{},

//onRejectedisinvokewhenreject()isinvoked

()=>{});

//Iflefthere,p1willforeverremain"pending"

//Usingthe'new'keywordstillallowsyoutocalla

//methodonthereturnedinstance,sodefiningthe

//then()handlersimmediatelyisallowed.

//

//Instantlyresolvesp2

constp2=newPromise((resolve,reject)=>resolve())

.then(

//Thismethodwillimmediatelybeinvokedfollowing

//thep2executorinvokingresolve()

()=>console.log('resolved!'));

//"resolved!"

//Instantlyrejectsp3

constp3=newPromise((resolve,reject)=>reject())

.then(

()=>console.log('resolved!'),

//Thissecondmethodwillimmediatelybeinvokedfollowing

//thep3executorinvokingreject()

()=>console.log('rejected!'));

//"rejected!"

constp4=newPromise((resolve,reject)=>reject())

//Ifyoudon'trequireuseoftheresolvehandler,

//catch()allowsyoutodefinejusttheerrorhandling

.catch(()=>console.log('rejected!'));

//executorparameterscanbecapturedoutsideitslexical

//scopeforlaterinvocation

varouterResolve;


outerResolve=resolve;

}).then(()=>console.log('resolved!'));

outerResolve();

//"resolved!"

Howitworks...PromisesinJavaScriptconfertothedevelopertheabilitytowriteasynchronouscodeinparallelwithsynchronouscodemoreeasily.InJavaScript,thiswasformerlysolvedwithnestedcallbacks,colloquiallyreferredtoas"callbackhell."Asinglecallback-orientedfunctionmightbewrittenasfollows:

//agenericasynchronouscallbackfunction

functionasyncFunction(data,successCallback,errorCallback){

//asyncFunctionwillperformsomeoperationthatmaysucceed,

//mayfail,ormaynotreturnatall,anyofwhich

//occursinanunknownamountoftime

//thispseudo-responsecontainsasuccessboolean,

//andthereturneddataifsuccessful

asyncOperation(data,function(response){

if(response.success===true){

successCallback(response.data);

}else{

errorCallback();

}

});

};

Ifyourapplicationdoesnotdemandanysemblanceofin-orderorcollectivecompletion,thenthefollowingwillsuffice:

functionsuccessCallback(data){

//asyncFunctionsucceeded,handledataappropriately

};

functionerrorCallback(){

//asyncFunctionfailed,handleappropriately

};

asyncFunction(data1,successCallback,errorCallback);



Thisisalmostneverthecasethough.Often,yourapplicationwilleitherdemandthatthisdataisacquiredinasequence,orthatanoperationthatrequiresmultipleasynchronouslyacquiredpiecesofdataexecutesonceallofthedatahasbeensuccessfullyacquired.Inthiscase,withoutaccesstopromises,thecallbackhellemerges:

asyncFunction(data1,(foo)=>{

asyncFunction(data2,(bar)=>{

asyncFunction(data3,(baz)=>{

//foo,bar,bazcannowallbeusedtogether

combinatoricFunction(foo,bar,baz);

},errorCallback);

},errorCallback);

},errorCallback);

Thisso-calledcallbackhellhereisreallyjustanattempttoserializethreeasynchronouscalls,buttheparametrictopologyoftheseasynchronousfunctionsforcesthedevelopertosubjecttheirapplicationtothisugliness.

There'smore...Animportantpointtorememberaboutpromisesisthattheyallowyoutobreakapartacalculationintotwoparts:thepartthatunderstandswhenthepromise's"execution"hasbeencompletedandthepartthatsignalstotherestoftheprogramthattheexecutionhasbeencompleted.

DecoupledandduplicatedPromisecontrol

BecauseapromisecangiveawaythecontrolofwhodecideswherethePromisewillbemadeready,multipleforeignpartsofthecodecansetthestateofthepromise.

Apromiseinstancecanbeeitherresolvedorrejectedatmultipleplacesinsidetheexecutor::

constp=newPromise((resolve,reject)=>{

//thefollowingarepseudo-methods,eachofwhichcanbecalled

//independentlyandasynchronously,ornotatall

functioncanHappenFirst(){resolve();};

functionmayHappenFirst(){resolve();}

functionmightHappenFirst(){reject();};

});

Apromiseinstancecanalsoberesolvedatmultipleplacesoutsidetheexecutor:

varouterResolve;



});

//thefollowingarepseudo-methods,eachofwhichcanbecalled

//independentlyandasynchronously,ornotatall

functioncanHappenFirst(){outerResolve();};

functionmayHappenFirst(){outerResolve();}

functionmightHappenFirst(){outerResolve();};

Note

OnceaPromise'sstatebecomesfulfilledorrejected,attemptstorejectorresolvethatpromisefurtherwillbesilentlyignored.Apromisestatetransitionoccursonlyonce,anditcannotbealteredorreversed.

ResolvingaPromisetoavalue

Partofthecentralconceptofpromiseconstructsisthattheyareableto"promise"thattherewillbeavalueavailablewhenthepromiseisresolved.

Statesdonotnecessarilyhaveadatavalueassociatedwiththem;theyonlyconfertothepromiseadefinedstateofevaluation:

varresolveHandler=()=>{},

rejectHandler=()=>{};


//statecanbedefinedwithanyofthefollowing:

//resolve();

//reject();

//resolve(myData);

//reject(myData);

}).then(resolveHandler,rejectHandler);

Anevaluatedpromise(resolvedorrejected)isassociatedwithahandlerforeachofthestates.Thishandlerisinvokeduponthepromise'stransitionintothatrespectivestate.Thesehandlerscanaccessthedatareturnedbytheresolutionorrejection:


//console.infoistheresolvehandler,

//console.erroristherejecthandler

resolve(123);

}).then(console.info,console.error);

//(info)123

//resettodemonstratereject()


//console.infoistheresolvehandler,

//console.erroristherejecthandler

reject(456);

}).then(console.info,console.error);

//(error)456

Delayedhandlerdefinition

Unlikecallbacks,handlerscanbedefinedatanypointinthepromiselifecycle,includingafterthepromisestatehasbeendefined:


//immediatelyresolvethepromise

resolve(123);

});

//subsequentlydefineahandler,willbeimmediately

//invokedsincepromiseisalreadyresolved

p3.then(console.info);

//(info)123

Multiplehandlerdefinition

Similartohowasingledeferredobjectcanberesolvedorrejectedatmultipleplacesintheapplication,asinglepromisecanhavemultiplehandlersthatcanbeboundtoasinglestate.For

example,asinglepromisewithmultipleresolvedhandlersattachedtoitwillinvokeallthehandlersiftheresolvedstateisreached;thesameistrueforrejectedhandlers:


//Invokeresolve()after1second

setTimeout(()=>resolve(),1000);

});

constcb=()=>console.log('called');

p4.then(cb);

p4.then(cb);

//After1second:

//"called"

//"called"

PrivatePromisemembers

AnextremelyimportantdeparturefromAngular1isthatthestateofapromiseistotallyopaquetotheexecution.Formerly,youwereabletoteaseoutthestateofthepromiseusingthepseudo-private$$stateproperty.WiththeformalES6Promiseimplementation,thestatecannotbeinspectedbyyourapplication.Youcan,however,gleanthestateofapromisefromtheconsole.Forexample,inspectingapromiseinGoogleChromeyieldssomethinglikethefollowing:

Promise{

[[PromiseStatus]]:"fulfilled",

[[PromiseValue]]:123

}

Note

PromiseStatusandPromiseValueareprivateSymbols,whichareanewconstructinES6.Symbolcanbethoughtofasauniquekeythatisusefulforsettingpropertiesonobjectsthatshouldn'tbeeasilyaccessedfromelsewhere.Forexample,ifapromiseweretousethe'PromiseStatus'stringtokeyaproperty,itcouldbeeasilyusedoutsidetheobject,evenifthepropertywassupposedtoremainprivate.WithES6privatesymbols,however,asymbolisuniquewhengenerated,andthereisnogoodwaytoaccessitinsidetheinstance.

SeealsoChainingPromisesandPromisehandlersdetailshowyoucanwieldthispowerfulchainingconstructtoserializeasynchronousoperationsCreatingPromisewrapperswithPromise.resolve()andPromise.reject()demonstrateshowtousethecorePromiseutilities

ChainingPromisesandPromisehandlersMuchofthepurposeofpromisesistoallowthedevelopertoserializeandreasonaboutindependentasynchronousactions.ThiscanbeaccomplishedbyutilizingthePromisechainingfeature.

Note



Howtodoit...Thepromisehandlerdefinitionmethodthen()returnsanotherpromise,whichcanhavefurtherhandlersdefineduponit—inahandlercalledchain:

varsuccessHandler=()=>{console.log('called');};

varp=newPromise((resolve,reject)=>{resolve();})

.then(successHandler)


.then(successHandler);

//called

//called

//called

Chainedhandlers'datahandoff

Chainedhandlerscanpassdatatotheirsubsequenthandlersinthefollowingmanner:

varsuccessHandler=(val)=>{

console.log(val);

returnval+1;

};

varp=newPromise((resolve,reject)=>{resolve(0);})



.then(successHandler);

//0

//1

//2

Rejectingachainedhandler

Returningnormallyfromapromisehandler(nottheexecutor)will,bydefault,signalchildpromisestatestobecomeresolved.However,ifeithertheexecutororthesubsequenthandlersthrowanuncaughtexception,theywill,bydefault,reject;thiswillservetocatchtheexception:


//executorwillimmediatelythrowanexception,forcing

//areject

throw123;

})

.then(

//childpromiseresolvedhandler

data=>console.log('resolved',data),

//childpromiserejectedhandler

data=>console.log('rejected',data));

//"rejected",123

Note

Notethattheexception,hereanumberprimitive,isthedatathatispassedtotherejectionhandler.

Howitworks...APromisereachingafinalstatewilltriggerchildpromisestofollowitinturn.Thissimplebutpowerfulconceptallowsyoutobuildbroadandfault-tolerantpromisestructuresthatelegantlymeshcollectionsofdependentasynchronousactions.

There'smore...Thetopologyofpromiseslendsitselftosomeinterestingutilizationpatterns.

Promisehandlertrees

Promisehandlerswillexecuteintheorderthatthepromisesaredefined.Ifapromisehasmultiplehandlersattachedtoasinglestate,thenthatstatewillexecuteallitshandlersbeforeresolvingthefollowingchainedpromise:

constincr=val=>{

console.log(val);

return++val;

};

varouterResolve;

constfirstPromise=newPromise((resolve,reject)=>{


});

//definefirstPromise'shandler

firstPromise.then(incr);

//appendanotherhandlerforfirstPromise,andcollect

//thereturnedpromiseinsecondPromise

constsecondPromise=firstPromise.then(incr);

//appendanotherhandlerforthesecondpromise,andcollect

//thereturnedpromiseinthirdPromise

constthirdPromise=secondPromise.then(incr);

//atthispoint,invokingouterResolve()will:

//resolvefirstPromise;firstPromise'shandlersexecutes

//resolvesecondPromise;secondPromises'shandlerexecutes

//resolvethirdPromise;nohandlersdefinedyet

//additionalpromisehandlerdefinitionorderis

//unimportant;theywillberesolvedasthepromises

//sequentiallyhavetheirstatesdefined

secondPromise.then(incr);

firstPromise.then(incr);

thirdPromise.then(incr);

//thesetupcurrentlydefinedisasfollows:

//firstPromise->secondPromise->thirdPromise

//incr()incr()incr()

//incr()incr()

//incr()

outerResolve(0);

//0

//0

//0

//1

//1

//2

Note

Sincethereturnvalueofahandlerdecideswhetherornotthepromisestateisresolvedorrejected,anyofthehandlersassociatedwithapromiseisabletosetthestate—which,asyoumayrecall,canonlybesetonce.Thedefiningoftheparentpromisestatewilltriggerthechildpromisehandlerstobeexecuted.

Itshouldnowbeapparenthowthetreesofthepromisefunctionalitycanbederivedfromthecombinationofpromisechainingandhandlerchaining.Whenusedproperly,theycanyieldextremelyelegantsolutionsfordifficultanduglyasynchronousactionserializations.

catch()

Thecatch()methodisashorthandforpromise.then(null,errorCallback).Usingitcanleadtoslightlycleanerpromisedefinitions,butitisnothingmorethansyntacticalsugar:

varouterReject;


outerReject=reject;

})

.catch(()=>console.log('rejected!'));

outerReject();

//"rejected"

Tip

Itisalsopossibletochainp.then().catch().Anerrorthrownbytheoriginalpromisewillpropagatethroughthepromisecreatedbythen(),causeittoreject,andreachthepromisecreatedbycatch().Itcreatesoneextralevelofpromiseindirection,buttoanoutsideobserver,itwillbehavethesame.

SeealsoUnderstandingandimplementingbasicPromisesgivesanextensiverundownofhowandwhytousePromisesCreatingPromisewrapperswithPromise.resolve()andPromise.reject()demonstrateshowtousethecorePromiseutilities

CreatingPromisewrapperswithPromise.resolve()andPromise.reject()Itisusefultohavetheabilitytocreatepromiseobjectsthathavealreadyreachedafinalstatewithadefinedvalue,andalsotobeabletonormalizeJavaScriptobjectsintopromises.Promise.resolve()andPromise.reject()affordyoutheabilitytoperformboththeseactions.

Note



Howtodoit...LikeallotherstaticPromisemethods,Promise.resolve()andPromise.reject()returnapromiseobject.Inthiscase,thereisnoexecutordefinition.

Ifoneofthesemethodsisprovidedwithanon-promiseargument,thereturnedpromisewillassumeeitherafulfilledorrejectedstate(correspondingtotheinvokedmethod).ThismethodwillpasstheargumenttoPromise.resolve()andPromise.reject(),alongwithanycorrespondinghandlers:

Promise.resolve('foo');

//Promise{[[PromiseStatus]]:"resolved",[[PromiseValue]]:"foo"}

Promise.reject('bar');

//Promise{[[PromiseStatus]]:"rejected",[[PromiseValue]]:"bar"}

//(error)Uncaught(inpromise)bar

Theprecedingcodeisbehaviorallyequivalenttothefollowing:

newPromise((resolve,reject)=>resolve('foo'));

//Promise{[[PromiseStatus]]:"resolved",[[PromiseValue]]:"foo"}

newPromise((resolve,reject)=>reject('bar'));

>>Promise{[[PromiseStatus]]:"rejected",[[PromiseValue]]:"bar"}

//(error)Uncaught(inpromise)bar

Promisenormalization

Promise.resolve()willuniquelyhandlescenarioswhereitispassedwithapromiseobjectasitsargument.Promise.resolve()willeffectivelyoperateasano-op,returningtheinitialpromiseargumentwithoutanymodification.Itwillnotmakeanattempttocoercetheargumentpromise'sstate:

consta=Promise.resolve('baz');

console.log(a);

//Promise{status:'resolved',value:'baz'}

constb=Promise.resolve(a);

console.log(b);

//Promise{status:'resolved',value:'baz'}

console.log(a===b);

//true

constc=Promise.reject('qux');

//Errorqux

console.log(c)

//Promise{status:'rejected',value:'qux'}

constd=Promise.resolve(c);

console.log(d);

//Promise{status:'rejected',value:'qux'}

console.log(c===d);

//true

Howitworks...WhenthinkingaboutPromisesinthecontextofthem"promising"toeventuallyassumeavalue,thesemethodsaresimplyamelioratinganylatentperiodseparatingthependingandfinalstates.

Thedichotomyisverysimple:

Promise.reject()willreturnarejectedpromisenomatterwhatitsargumentis.Evenifitisapromiseobject,thevalueofthereturnedpromisewillbethatofthepromiseobject.Promise.resolve()willreturnafulfilledpromisewiththewrappedvalueifthatvalueisnotapromise.Ifitisapromise,itbehavesasano-op.

There'smore...Importantly,thebehaviorofPromise.resolve()isnearlythesameashow$q.when()operatedinAngular1.$q.when()wasabletonormalizepromiseobjects,butitwouldalwaysreturnanewlycreatedpromiseobject:

//Angular1

consta=$q(()=>{});

console.log(a);

//Promise{...}

constb=$q.when(a);

console.log(b);

//Promise{...}

console.log(a===b);

//false

SeealsoUnderstandingandimplementingbasicPromisesgivesanextensiverundownofhowandwhytousePromisesImplementingPromisebarrierswithPromise.all()showyouhowPromisescanbecomposableCancelingasynchronousactionswithPromise.race()guidesyouthroughtheprocessofimplementingazero-failure-tolerantPromisesystem

ImplementingPromisebarrierswithPromise.all()Youmayfindyourapplicationrequirestheuseofpromisesinanall-or-nothingtypeofsituation.Thatis,itwillneedtocollectivelyevaluateagroupofpromises,andthiscollectionwillresolveasasinglepromiseifandonlyifallofthecontainedpromisesareresolved;ifanyoneofthemisrejected,theaggregatepromisewillberejected.

Note



Howtodoit...ThePromise.all()methodacceptsaniterablecollectionofpromises(forexample,anarrayofPromiseobjectsoranobjectwithanumberofpromiseproperties),anditwillattempttoresolveallofthemasasingleaggregatepromise.Theparameteroftheaggregateresolvedhandlerwillbeanarrayorobjectthatmatchestheresolvedvaluesofthecontainedpromises:

varouterResolveA,outerResolveB;

constpromiseA=newPromise((resolve,reject)=>{

outerResolveA=resolve;

});

constpromiseB=newPromise((resolve,reject)=>{

outerResolveB=resolve;

});

constmultiPromiseAB=Promise.all([promiseA,promiseB])

.then((values)=>console.log(values));

outerResolveA(123);

outerResolveB(456);

//[123,456]

Ifanyofthepromisesinthecollectionarerejected,theaggregatepromisewillberejected.Theparameteroftheaggregaterejectedhandlerwillbethereturnedvalueoftherejectedpromise:

varouterResolveC,outerRejectD;

constpromiseC=newPromise((resolve,reject)=>{

outerResolveC=resolve;

});

constpromiseD=newPromise((resolve,reject)=>{

outerRejectD=reject;

});

constmultiPromiseCD=Promise.all([promiseC,promiseD])

.then(

values=>console.log(values),

rejectedValue=>console.error(rejectedValue));

//resolveacollectionpromise,nohandlerexecution

outerResolveC(123);

//rejectacollectionpromise,rejectionhandlerexecutes

outerRejectD(456);

//(error)456

Howitworks...Asdemonstrated,theaggregatepromisewillreachthefinalstateonlywhenalloftheenclosedpromisesareresolved,orwhenasingleenclosedpromiseisrejected.Usingthistypeofpromiseisusefulwhenthecollectionofpromisesdonotneedtoreasonaboutoneanother,butcollectivecompletionistheonlymetricofsuccessforthegroup.

Inthecaseofacontainedrejection,theaggregatepromisewillnotwaitfortheremainingpromisestocomplete,butthosepromiseswillnotbepreventedfromreachingtheirfinalstate.Onlythefirstpromisetoberejectedwillbeabletopassrejectiondatatotheaggregatepromiserejectionhandler.

There'smore...Promise.all()isinmanywaysextremelysimilartoanoperating-system-levelprocesssynchronizationbarrier.Aprocessbarrierisacommonpointinthethreadinstructionexecutionthatacollectionofprocesseswillreachindependentlyandatdifferenttimes,andnoprocesscanproceedfurtheruntilallhavereachedthispoint.Inthesameway,Promise.all()willnotproceedunlesseitherallofthecontainedpromiseshavebeenresolved—reachedthebarrier—orasinglecontainedrejectionwillpreventthatstatefromeverbeingachieved,inwhichcasethefailoverhandlerlogicwilltakeover.

SincePromise.all()allowsyoutohavearecombinationofpromises,italsoallowsyourapplication'sPromisechainstobecomeadirectedacyclicgraph(DAG).Thefollowingisanexampleofapromiseprogressiongraphthatdivergesfirstandconvergeslater:

Thislevelofcomplexityisuncommon,butitisavailableforuseshouldyourapplicationrequireit.

SeealsoCreatingPromiseWrapperswithPromise.resolve()andPromise.reject()demonstrateshowtousethecorePromiseutilitiesCancelingasynchronousactionswithPromise.race()guidesyouthroughtheimplementationofazero-failure-tolerantPromisesystem

CancelingasynchronousactionswithPromise.race()ES6introducesPromise.race(),whichisabsentfromthe$qspecinAngular1.LikePromise.all(),thisstaticmethodacceptsaniterablecollectionofpromiseobjects;whicheveroneresolvesorrejectsfirstwillbecometheresultofthepromisewrappingthecollection.Thismayseemlikeunusualbehavior,butitbecomesquiteusefulwhenyou'rebuildingacancellationbehaviorintothesystem.

Note



GettingreadySupposeyoustartedwithasimplepromisethatresolvestoavalueafter3seconds:

constdelayedPromise=newPromise((resolve,reject)=>

setTimeout(resolve.bind(null,'foobar'),3000))

.then(val=>console.log(val));

Youwouldliketohavetheabilitytodetachapartofyourapplicationfromwaitingforthispromise.

Howtodoit...Asimplesolutionwouldbetoexposethepromise'srejecthandlerandjustinvokeitfromwhateveristoperformthecancelation.However,itispreferabletostopwaitingforthispromiseinsteadofdestroyingit.

Note

AconcreteexampleofthiswouldbeaslowbutcriticalHTTPrequestthatyourapplicationmakes.YoumightnotwanttheUItowaitforittocomplete,butyoumayhaveresolvehandlersattachedtotherequestthatyoustillwanttohandletheresult,onceitisreturned.

Instead,youcantakeadvantageofPromise.race()andintroduceacancellationpromisealongsidetheoriginalone:

//Usethismethodtocapturethecancellationfunction

varcancel;

constcancelPromise=newPromise((resolve,reject)=>{

cancel=reject;

});


setTimeout(resolve.bind(null,'foobar'),3000));

//Promise.race()createsanewpromise

Promise.race([cancelPromise,delayedPromise])

.then(

val=>console.log(val),

()=>console.error('cancelled!'));

//Ifyouinvokecancel()before3secondselapses

//(error)"cancelled!"

//Instead,if3secondselapses

//"foobar"

Now,ifdelayedPromiseresolvesfirst,thepromisecreatedbyPromise.race()willlogthevaluepassedtoithere,foobar.If,however,youinvokecancel()beforeithappens,thenthatsamePromisewillprintacancelled!error.

Howitworks...Promise.race()justwaitsforanyofitsinnerpromisestoarriveatthefinalstate.Itcreatesandreturnsanewpromisethatisbeholdentothestateofthecontainedpromises.Whenitobservesthatanyofthemtransitionstothefinalstate,thenewpromisealsoassumesthisstate.

Note

Inthisexample,theexecutorofcancelPromiseanddelayedPromiseareinvokedbeforePromise.race()iscalled.Sincepromisesonlycareaboutthestateofotherpromises,itisn'timportantthatthepromisespassedtoPromise.race()needtobealreadytechnicallystarted.

NotethattheuseofPromise.race()doesn'taffecttheimplementationofdelayedPromise.Evenwhencancel()isinvoked,delayedPromisewillstillberesolvedanditshandlerswillstillbeexecutednormally,unawarethatthesurroundingPromise.race()hasalreadybeenrejected.YoucanprovethistoyourselfbyaddingaresolvehandlertodelayedPromise,invokingcancel()andseeingtheresolvehandlerofdelayedPromisebeingexecutedanyway:

varcancel;

constcancelPromise=newPromise((resolve,reject)=>{

cancel=reject;

});


setTimeout(resolve.bind(null,'foobar'),3000))

.then(()=>console.log('stillresolved!'));

Promise.race([cancelPromise,delayedPromise])

.then(

val=>console.log(val),

()=>console.error('cancelled!'));

cancel();

//(error)cancelled!

//After3secondselapses

//"stillresolved!"

SeealsoCreatingPromisewrapperswithPromise.resolve()andPromise.reject()demonstrateshowtousethecorePromiseutilitiesImplementingPromisebarrierswithPromise.all()showyouhowPromisescanbecomposable

ConvertingaPromiseintoanObservableObservablesandPromisesservedifferentpurposesandaregoodatdifferentthings,butinaspecificpartofanapplication,youwillalmostcertainlywanttobedealingwithasingledenomination.Thismeansconvertingobservablesintopromisesandviceversa.ThankstoRxJS,thisisquitesimple.

Tip

FormoreonRxJSObservables,refertoChapter5,ReactiveXObservables,whichcoversthemindepth.

Note



Howtodoit...ThereisagooddealofparitybetweenPromiseandObservable.Therearediscretesuccessanderrorcases,andtheconceptofsuccessfulcompletiononlycorrespondstothesuccesscase.

RxJSobservablesexposeafromPromisemethod,whichwrapsPromiseasanObservable:

import{Observable}from'rxjs/Rx';

varouterResolve,outerReject;



outerReject=reject;

});

varo1=Observable.fromPromise(p1);

NowthatyouhaveanObservableinstance,youcanutilizeitssubscribe()events,whichcorrespondtothestateofthePromiseinstance:


varouterResolve,outerReject;



outerReject=reject;

});

varo1=Observable.fromPromise(p1);

o1.subscribe(

//onNexthandler

()=>console.log('resolved!'),

//onErrorhandler

()=>console.log('rejected'),

//onCompletedhandler

()=>console.log('finished!'));

outerResolve();

//"resolved!"

//"finished!"

Howitworks...ThenewObservableinstancedoesn'treplacethepromise.ItjustattachesitselftothePromise'sresolvedandrejectedstates.Whenthishappens,itemitseventsandinvokestherespectivecallbacks.TheObservableinstanceisboundtothestateofthePromise,butPromiseisnotawarethatanythinghasbeenattachedtoitsinceitblindlyexposesitsresolveandrejecthooks.

Tip

NotethatonlyaresolvedPromisewillinvoketheonCompletedhandler;rejectingthepromisewillnotinvokeit.

There'smore...ObservablesandPromisesareinterchangeableifyouaresoinclined,butdoconsiderthattheyarebothappropriateindifferentsituations.

Observablesaregoodatstream-typeoperations,wherethelengthofthestreamisindeterminate.ItiscertainlypossibletohaveanObservablethatonlyeveremitsoneevent,butanObservablewillnotbroadcastthisstatetolistenersthatareattachedlater,unlessyouconfigureittodoso(suchasBehaviorObservable).

Promisesaregoodatmaskingasynchronousbehavior.TheyallowyoutowritecodeandsethandlersuponthePromiseasifthepromisedstateorvaluewasrealizedatthetimeofexecution.Ofcourseit'snot,buttheabilitytodefineahandlersynchronouslyatruntimeandhavethePromiseinstancedecidewhenit'sappropriatetoexecuteit,aswellastheabilitytochainthesehandlers,isextremelyvaluable.

SeealsoUnderstandingandimplementingbasicPromisesgivesanextensiverundownofhowandwhytousePromisesConvertinganHTTPserviceObservableintoZoneAwarePromisegivesyouanAngular-centricviewofhowPromises,Observables,andZonesintegrateinsideanAngularapplication

ConvertinganHTTPserviceObservableintoaZoneAwarePromiseInAngular2,theRxJSasynchronousobservablesarefirst-classcitizensandmuchofthecoretoolkithasbeenconfiguredtorelyuponthem.Nonetheless,itisstillvaluabletobeabletohaveconversionbetweenthem,especiallysincetheyhavesimilarduties.

Tip

FormoreonRxJSObservables,refertoChapter5,ReactiveXObservables,whichcoversthemindepth.

Note



GettingreadyYou'llbeginwiththefollowingsimplisticapplication:



import{Http}from'@angular/http';

@Component({

selector:'article',

template:`

<p></p>

`

})


constructor(privatehttp:Http){

//Fordemopurposes,havethisplunkrequestitselfto

//avoidcrossoriginerrors

console.log(

http.get('//run.plnkr.co/plunks/TBtcNDRelAOHDVpIuWw1'));

}

}

//Observable{...}

SupposeyourgoalwastoconvertthisHTTPcalltousepromisesinstead.

Howtodoit...Forthepurposesofthisrecipe,youdon'treallyneedtounderstandanydetailsaboutthehttpserviceorRxJSasynchronousobservables.Allthatyouneedtoknowisthatanymethodexposedbythehttpservicewillreturnanobservable.Happily,theRxJSimplementationcanexposea.toPromise()methodthatconvertstheobservableintoitsequivalentPromiseobject:




import'rxjs/Rx';

@Component({

selector:'article',

template:`

<p></p>

`

})



//Fordemopurposes,havethisplunkrequestitselfto

//avoidcrossoriginerrors

console.log(

http.get('//run.plnkr.co/plunks/TBtcNDRelAOHDVpIuWw1')

.toPromise());

}

}

//ZoneAwarePromise{...}

Howitworks...TheHTTPservice,bydefault,returnsanobservable;however,withouttheimportedRxmodule,thiswillthrowanerror,sayingitcannotfindthetoPromise()method.

TheRxmoduleconferstoanobservabletheabilitytoconvertitselfintoapromiseobject.Angular2isintentionallynotutilizingtheObservablespecwithalltheRxJSoperatorstoallowyoutospecifyexactlywhichonesyouwant.Becausetheoperatorsexistasseparatemodules,thisleadstoasmallerpayloadsenttothebrowser.

Oncethe.toPromise()methodisinvoked,theobjectiscreatedtoaZoneAwarePromiseinstance.

Note

Thissoundsgnarly,butreally,it'sjustwrappingthePromiseimplementationaszone.jssothattheAngularzoneisawareofanyactionsthePromisecouldcausethatitshouldbeawareof.Foryourpurposes,thiscanbetreatedasaregularPromise.

SeealsoUnderstandingandimplementingbasicPromisesgivesanextensiverundownofhowandwhytousePromisesConvertingaPromiseintoanObservablegivesyouanexampleofhowRxJScanbeusedtoconvertbetweenthesetwopowerfultypes

Chapter5.ReactiveXObservablesThischapterwillcoverthefollowingrecipes:

BasicutilizationofObservableswithHTTPImplementingaPublish-SubscribemodelusingSubjectsCreatinganObservableAuthenticationServiceusingBehaviorSubjectsBuildingageneralizedPublish-Subscribeservicetoreplace$broadcast,$emit,and$onUsingQueryListsandObservablestofollowthechangesinViewChildrenBuildingafullyfeaturedAutoCompletewithObservables

IntroductionBeforeyougetintothemeatofAngular2Observables,itisimportanttofirstunderstandtheproblemyouaretryingtosolve.

Afrequentlyencounteredscenarioinsoftwareiswhereyouareexpectingsomeentitytobroadcastthatsomethinghappened;let'scallthisan"event"(distinctfromabrowserevent).Youwouldliketohookintothisentityandattachbehaviortoitwheneveraneventoccurs.Youwouldalsoliketobeabletodetachfromthisentitywhenyounolongercareabouttheeventsitisbroadcasting.

ThereismorenuanceandadditionalcomplexitytoObservablesthatthischapterwillcover,butthisconceptofeventsunderscoresthefundamentalpatternthatisusefultoyouasthedeveloper.

TheObserverPatternTheObserverPatternisn'talibraryorframework.ItisjustasoftwaredesignpatternuponwhichReactiveXObservablesarebuilt.Manylanguagesandlibrariesimplementthispattern,andReactiveXisjustoneoftheseimplementations;however,ReactiveXistheonethatAngular2hasformallyincorporatedintoitself.

TheObserverPatterndescribestherelationshipbetweensubject,whichwasdescribedasthe"entity"earlier,anditsobservers.Thesubjectisawareofanyobserversthatarewatchingit.Whenaneventisemitted,thesubjectisabletopassthiseventtoeachobserverviamethodsthatareprovidedwhentheobserverbeginstosubscribeit.

ReactiveXandRxJSTheReactiveXlibraryisimplementedinnumerouslanguages,includingPython,Java,andRuby.RxJS,theJavaScriptimplementationoftheReactiveXlibrary,isthedependencythatAngular2utilizestoincorporateObservablesintonativeframeworkbehavior.SimilartoPromises,youcancreateastandaloneObservableinstancethroughdirectinstantiation,butmanyAngular2methodsandserviceswillalsoutilizeanObservableinterfacebydefault.

ObservablesinAngular2Angular2integratesObservablesinawidevarietyofways.Ifyouarenewtothem,youmayinitiallyfeeloddusingthem.However,itisimportantyourecognizethatObservablesprovideasuperiorsoftwaredevelopmentpattern.

AlongwiththebulkRxJSmodulerxjs/Rx,youarealsoprovidedwiththestrippeddownObservablemodulerxjs/Observable.Thisminimalmoduleallowsindividualpiecesofnon-essentialbehaviortobeimportedasrequiredinordertoreducemodulebloat.Forexample,whenusingthislightweightObservablemodule,usingoperatorsorothersuchReactiveXconventionsnecessitatesthatyouexplicitlyincorporatethesemodules,inordertoextendtheavailableObservableinterface.

ObservablesandPromisesBothObservablesandPromisesoffersolutionstoasynchronousconstructs,butObservablesaremorerobust,extensible,anduseful.AlthoughPromisesareavailablebydefaultintheES6specification,youwillquicklyrealizethattheybecomebrittlewhenyouattempttoapplythemoutsidetherealmofbasicapplicationbehavior.

TheReactiveXlibraryofferspowerfultoolingtowhichPromisescannotcompare.Observablesarecomposable,allowingyoutotransformandcombinethemintonewObservables.Theyalsoencapsulatetheconceptofacontinuousstreamofevents-aparadigmthatisencounteredinclient-sideprogrammingextremelyfrequentlyandthatPromisesdonottranslatewellto.

BasicutilizationofObservableswithHTTPInAngular2,theHttpmodulenowbydefaultutilizestheObservablepatterntowrapXMLHttpRequest.Fordevelopersthatarefamiliarwiththepattern,itreadilytranslatestotheasynchronousnatureofrequeststoremoteresources.Fordevelopersthatarenewertothepattern,learningtheinsandoutsofHttpObservablesisagoodwaytowrapyourheadaroundthisnewparadigm.

Note

Thecode,links,andaliveexamplerelatedtothisareavailableathttp://ngcookbook.herokuapp.com/4121.


GettingreadyForthepurposeofthisexample,you'lljustserveastaticJSONfiletotheapplication.HowevernotethatthiswouldbenodifferentifyouweresendingrequeststoadynamicAPIendpoint.

Beginbycreatingaskeletoncomponent,includingallthenecessarymodulesformakingHTTPrequests:




@Component({

selector:'article',

template:`

<h1>{{title}}</h1>

<p>{{author}}</p>

`

})


title:string;

body:string;


}

}

Forthisexample,assumethereisaJSONfileinsidethestaticdirectorynamedarticle.json:

[article.json]

{

"title":"OrthopedicDoctorsAskCityforMoreSidewalkCracks",

"author":"JakeHsu"

}

Howtodoit...SinceyouhavealreadyinjectedtheHttpservice,youcanbeginbydefiningthegetrequest:




@Component({

selector:'article',

template:`

<h1>{{title}}</h1>

<p>{{author}}</p>

`

})


title:string;

body:string;

constructor(privatehttp_:Http){

http_.get('static/article.json');

}

}

ThiscreatesanObservableinstance,butyoustillneedtoaddinstructionsonhowtohandletherawstringoftheresponse.

Note

Atthispoint,youwillnoticethatthisdoesnotactuallyfireabrowserGETrequest.Thisiscoveredinthisrecipe'sThere'smoresection.

SinceyouknowtherequestwillreturnJSON,youcanutilizethejson()methodthataResponsewouldexpose.Thiscanbedoneinsidethemap()method.However,theObservabledoesnotexposethemap()methodbydefault,soyoumustimportitfromtherxjsmodule:




import'rxjs/add/operator/map';

@Component({

selector:'article',

template:`

<h1>{{title}}</h1>

<p>{{author}}</p>

`

})


title:string;

author:string;


http_.get('static/article.json')

.map(response=>response.json());

}

}

Sofarsogood,butyou'restillnotdone.TheprecedingcodewillcreatetheObservableinstance,butyoustillhavetosubscribetoitinordertohandleanydataitwouldemit.Thiscanbeaccomplishedwiththesubscribe()method,whichallowsyoutoattachthecallbackanderrorhandlingmethodsofobserver:





@Component({

selector:'article',

template:`

<h1>{{title}}</h1>

<p>{{author}}</p>

`

})


title:string;

author:string;



.map(response=>response.json())

.subscribe(

article=>{

this.title=article.title;

this.author=article.author;

},

error=>console.error(error));

}

}

Withallofthis,theGETrequestwillreturntheJSONfile,andtheresponsedatawillbeparsedanditsdatainterpolatedintotheDOMbythecomponent.

Howitworks...Theprevioussectiongaveagoodhigh-leveloverviewofwhatwashappening,butitisusefultobreakthingsdownmorecarefullytounderstandwhateachindividualstepaccomplishes.

Observable<Response>

TheHttpserviceclassexposesthemethodsget(),post(),put(),andsoon—alltheHTTPverbsthatyouwouldexpect.EachofthesewillreturnObservable<Response>,whichwillemitaResponseinstancewhentherequestisreturned:

console.log(http_.get('static/article.json'));

//Observable{...}

Note

Itsoundsobvious,butObservablesareobservedbyanobserver.TheobserverwillwaitforObservabletoemitobjects,whichinthisexampletakestheformofResponse.

TheRxJSmap()operator

TheResponseinstanceexposesajson()method,whichconvertsthereturnedserializedpayloadstringintoitscorrespondingin-memoryobjectrepresentation.Youwouldliketobeabletopassaregularobjecttotheobserverhandler,sotheidealtoolhereisawedgemethodthatstillgivesyouanObservableintheend:

console.log(http_.get('static/article.json')

.map(response=>response.json()));

//Observable{source:Observable,operator:MapOperator,...}

RecallthatthecanonicalformofObservablesisastreamofevents.Inthiscase,weknowtherewillonlyeverbeoneevent,whichistheHTTPresponse.Nonetheless,allthenormaloperatorsthatwouldbeusedonastreamofeventscanjustaseasilybeusedonthissingle-eventObservable.

InthesamewaythatArray.map()canbeusedtotransformeachinstanceinthearray,Observable.map()allowsyoutotransformeacheventemittedfromObservable.Morespecifically,itcreatesanotherObservablethatemitsthemodifiedeventpassedfromtheinitialobservable.

Subscribe

Observableinstancesexposeasubscribe()methodthatacceptsanonNexthandler,anonErrorhandler,andanonCompletedhandlerasarguments.ThesehandlerscorrespondtotheeventsinthelifecycleoftheObservablewhenitemitsResponseinstances.TheparameterfortheonNextmethodiswhateverisemittedfromtheObservable.Inthiscase,theemitteddatais

thereturnedvaluefrommap(),soitwillbetheparsedobjectthathasreturnedafterinvokingjson()ontheResponseinstance.

Allthesemethodsareoptional,butinthisexample,theonNextandonErrormethodsareuseful.

Note

Together,thesemethodswhenprovidedtosubscribe()constitutewhatisidentifiedastheobserver.


.map(respose=>respose.json())

.subscribe(

article=>{


this.body=article.body;

},

error=>console.error(error));

Withallofthistogether,thebrowserwillfetchtheJSONandparseit,andthesubscriberwillpassitsdatatotherespectivecomponentmembers.

There'smore...Whenconstructingthisrecipepiecebypiece,ifyouarewatchingyourbrowser'snetworkrequestsasyouassembleit,youwillnoticethattheactualGETrequestisnotfireduntilthesubscribe()methodisinvoked.ThisisbecausethetypeObservableyouareusingis"cold".

HotandcoldObservables

The"cold"designationmeansthattheObservabledoesnotbegintoemituntilanobserverbeginstosubscribetoit.Thisisdifferentfroma"hot"Observable,whichwillemititemseveniftherearenoobserverssubscribedtoit.Sincethismeansthateventsthatoccurbeforeanobserverisattachedarelost,HTTPObservablesdemandacolddesignation.

TheonNextmethodistermed"emission"sincethereisassociateddatathatisbeingemitted.TheonCompletedandonErrormethodsaretermed"notifications,"astheyrepresentsomethingofsignificance,buttheydonothaveanassociatedeventthatwouldbeconsideredpartofthestream.

SeealsoImplementingaPublish-SubscribemodelusingSubjectsshowsyouhowtoconfigureinputandoutputforRxJSObservablesBuildingafullyfeaturedAutoCompletewithObservablesgivesyouabroadtourofsomeoftheutilitiesofferedtoyouaspartoftheRxJSlibrary

ImplementingaPublish-SubscribemodelusingSubjectsAngular2willoftenprovideyouwithanObservableinterfacetoattachtoforfree,butitisimportanttoknowhowtheyarecreated,configured,andused.Morespecifically,itisvaluableforyoutoknowhowtotakeObservablesandapplythemtorealscenariosthatwillbeencounteredintheclient.

Note



GettingreadySupposeyoustartedwiththefollowingskeletonapplication:

[app/click-observer.component.ts]


@Component({

selector:'click-observer',

template:`

<button>

Emitevent!

</button>

<p*ngFor="letclickofclicks;leti=index">

{{i}}:{{click}}

</p>

`

})

exportclassClickObserverComponent{

clicks:Array<Event>=[];

}

Yourgoalistoconvertthissothatallthebuttonclickeventsareloggedintotherepeatedfield.

Howtodoit...Accomplishingthiswithacomponentmembermethodandusingitintheclickeventbindinginthetemplateispossible,butthisdoesn'tcapturetherealvalueofObservables.YouwanttobeabletoexposeanObservableonClickObserverComponent.Thiswillallowanyotherpartofyourapplicationtosubscribetotheseclickeventsandhandletheminitsownway.

Instead,youwouldliketobeabletofunneltheclickeventsfromthebuttonintotheObservable.WitharegularObservableinstance,thisisn'tpossiblesinceitisonlyactingastheSubscribepartofthePublish-Subscribemodel.ToaccomplishthePublishaspect,youmustuseaSubjectinstance:



import{Subject}from'rxjs/Subject';

@Component({


template:`

<button>

Emitevent!

</button>


{{i}}:{{click}}

</p>

`

})


clickEmitter:Subject<Event>=newSubject();


}

ReactiveXSubjectsactasboththeObservableandtheObserver.Therefore,itexposesboththesubscribe()method,usedfortheSubscribebehavior,andthenext()method,usedforthePublishbehavior.

Note

Inthisexample,thenext()methodisusefulbecauseyouwanttoexplicitlyspecifywhenanemissionshouldoccurandwhatthatemissionshouldcontain.TherearelotsofwaysofinstantiatingObservablesinordertoimplicitlygenerateemissions,suchas(butcertainlynotlimitedto)Observable.range().Inthesecases,Observableunderstandshowitsinputbehaves,andthusitdoesnotneeddirectionastowhenemissionsoccurandwhattheyshouldcontain.

Inthiscase,youcanpasstheeventdirectlytonext()inthetemplateclickhandlerdefinition.

Withthis,allthatisleftistopopulatethearraybydirectingtheemissionsintoit:




@Component({


template:`

<button(click)="clickEmitter.next($event)">

Emitevent!

</button>


{{i}}:{{click}}

</p>

`

})


clickEmitter:Subject<Event>=newSubject();


constructor(){

this.clickEmitter

.subscribe(clickEvent=>this.clicks.push(clickEvent));

}

}

That'sall!Withthis,youshouldseeclickeventspopulateinthebrowserwitheachsuccessivebuttonclick.

Howitworks...ReactiveXObservablesandObserversaredistinct,buttheirbehaviorismutuallycompatibleinsuchawaythattheirunion,Subject,canactaseitheroneofthem.Inthisexample,theSubjectisusedastheinterfacetofeedinEventobjectsasthePublishmodalityaswellastohandletheresultthatwouldcomeoutastheSubscribemodality.

There'smore...Thewaythisisconstructedmightfeelabitstrangetoyou.ThecomponentisexposingtheSubjectinstanceasthepointwhereyourapplicationwillattachobserverhandlers.

However,youwanttopreventotherpartsoftheapplicationfromaddingadditionalevents,whichisstillpossibleshouldtheychoosetousethenext()method.What'smore,theSubjectinstanceisreferenceddirectlyinsidethetemplateandexposingittheremayfeelabitodd.Therefore,itisdesirable,andcertainlygoodsoftwarepractice,toonlyexposetheObservablecomponentoftheSubject.

Todothis,youmustimporttheObservablemoduleandutilizetheSubjectinstance'smembermethod,namelyasObservable().ThismethodwillcreateanewObservableinstancethatwilleffectivelypipetheobservedemissionsfromtheSubjectintothenewObservable,whichwillbeexposedasapubliccomponentmember:



import{Observable}from'rxjs/Observable';


@Component({


template:`

<button(click)="publish($event)">

Emitevent!

</button>


{{i}}:{{click}}

</p>

`

})


clickEmitter:Observable<Event>;

privateclickSubject_:Subject<Event>=newSubject();


constructor(){

this.clickEmitter=this.clickSubject_.asObservable();

this.clickEmitter.subscribe(clickEvent=>

this.clicks.push(clickEvent));

}

publish(e:Event):void{

this.clickSubject_.next(e);

}

}

NoweventhoughonlythiscomponentisreferencingclickEmitter,everycomponentthatusesclickEmitterwillnotneedorbeabletotouchthesource,Subject.

NativeRxJSimplementation

Thishasallbeenagreatexample,butthisissuchacommonpatterninthattheRxJSlibraryalreadyprovidesabuilt-inwayofimplementingit.TheObservableclassexposesastaticmethodfromEvent(),whichtakesinanelementthatisexpectedtogenerateeventsandtheeventtypetolistento.

However,youneedareferencetotheactualelement,whichyoucurrentlydonothave.Forthepresentimplementation,theAngular2ViewChildfacultieswillgiveyouaverynicereferencetothebutton,whichwillthenbepassedtothefromEvent()methodoncethetemplatehasbeenrendered:


import{Component,ViewChild,ngAfterViewInit}



import'rxjs/add/observable/fromEvent';

@Component({


template:`

<button#btn>

Emitevent!

</button>


{{i}}:{{click}}

</p>

`

})

exportclassClickObserverComponentimplementsAfterViewInit{

@ViewChild('btn')btn;

clickEmitter:Observable<Event>;


ngAfterViewInit(){

this.clickEmitter=Observable.fromEvent(

this.btn.nativeElement,'click');

this.clickEmitter.subscribe(clickEvent=>

this.clicks.push(clickEvent));

}

}

Withallofthis,thecomponentshouldstillbehaveidentically.

SeealsoBasicutilizationofObservableswithHTTPdemonstratesthebasicsofhowtouseanobservableinterfaceCreatinganObservableauthenticationserviceusingBehaviorSubjectsinstructsyouonhowtoreactivelymanagethestateinyourapplicationBuildingafullyfeaturedAutoCompletewithObservablesgivesyouabroadtourofsomeoftheutilitiesofferedtoyouaspartoftheRxJSlibrary

CreatinganObservableauthenticationserviceusingBehaviorSubjectsOneofthemostobviousandusefulcasesoftheObserverPatternistheoneinwhichasingleentityinyourapplicationunidirectionallycommunicatesinformationtoafieldoflistenersontheoutside.Theselistenerswouldliketobeabletoattachanddetachfreelyfromthesinglebroadcastingentity.Agoodinitialexampleofthisisthelogin/logoutcomponent.

Note



GettingreadySupposeyouhavethefollowingskeletonapplication:

[app/login.component.ts]


@Component({

selector:'login',

template:`

<button*ngIf="!loggedIn"

(click)="loggedIn=true">

Login

</button>

<button*ngIf="loggedIn"

(click)="loggedIn=false">

Logout

</button>

`

})

exportclassLoginComponent{

loggedIn:boolean=false;

}

Asitpresentlyexists,thiscomponentwillallowyoutotogglebetweenthelogin/logoutbutton,butthereisnoconceptofsharedapplicationstate,andothercomponentscannotutilizetheloginstatethatthiscomponentwouldtrack.

YouwouldliketointroducethisstatetoasharedservicethatisoperatedusingtheObserverPattern.

Howtodoit...Beginbycreatinganemptyserviceandinjectingitintothiscomponent:

[app/authentication.service.ts]


@Injectable()

exportclassAuthService{

privateauthState_:AuthState;

}

exportconstenumAuthState{

LoggedIn,

LoggedOut

}

NoticethatyouareusingaTypeScriptconstenumtokeeptrackoftheuser'sauthenticationstate.

Note

Ifyou'renewtoES6andTypeScript,thesekeywordsmayfeelabitbizarretoyou.TheconstkeywordisfromtheES6specification,signifyingthatthisvalueisreadonlyoncedeclared.InvanillaES6,thiswillthrowanerror,usuallySyntaxError,atruntime.WithTypeScriptcompilationthough,constwillbecaughtatcompiletime.

TheenumkeywordisanofferingofTypeScript.Itisnotdissimilartoaregularobjectliteral,butnotethattheenummembersdonothavevalues.

Throughouttheapplication,youwillreferencetheseviaAuthState.LoggedInandAuthState.LoggedOut.IfyoureferencethecompiledJavaScriptthatTypeScriptgenerates,youwillseethattheseareactuallyassignedintegervalues.Butforthepurposesofbuildinglargeapplications,thisallowsustodevelopacentralizedrepositoryofpossibleAuthStatevalueswithoutworryingabouttheiractualvalues.

Injectingtheauthenticationservice

Astheskeletonservicecurrentlyexists,youaregoingtoinstantiateaSubjectthatwillemitAuthState,butthereisnowayavailablecurrentlytointeractwithit.Youwillsetthisupinabit.First,youmustinjectthisserviceintoyourcomponent:

[app/app.module.ts]



import{LoginComponent}from'./login.component';

import{AuthService}from'./authentication.service';

@NgModule({

imports:[

BrowserModule

],

declarations:[

LoginComponent

],

providers:[

AuthService

],

bootstrap:[

LoginComponent

]

})


Thisisallwellandgood,buttheserviceisstillunusableasis.

Tip

NotethatthepathyouimportyourAuthServicefrommayvarydependingonwhereitliesinyourfiletree.

AddingBehaviorSubjecttotheauthenticationservice

Thecoreofthisserviceistomaintainaglobalapplicationstate.Itshouldexposeitselftotherestoftheapplicationbylettingotherpartssaytotheservice,"Letmeknowwheneverthestatechanges.Also,I'dliketoknowwhatthestateisrightnow."TheperfecttoolforthistaskisBehaviorSubject.

Note

RxJSSubjectsalsohaveseveralsubclasses,andBehaviorSubjectisoneofthem.Fundamentally,itfollowsalltherhythmsofSubjects,butthemaindifferenceisthatitwillemititscurrentstatetoanyobserverthatbeginstolistentoit,asifthateventisentirelynew.Incaseslikethis,whereyouwanttokeeptrackofthestate,thisisextremelyuseful.

AddaprivateBehaviorSubject(initializedtotheLoggedOutstate)andapublicObservabletoAuthService:



import{BehaviorSubject}from'rxjs/BehaviorSubject';


@Injectable()


privateauthManager_:BehaviorSubject<AuthState>

=newBehaviorSubject(AuthState.LoggedOut);


authChange:Observable<AuthState>;

constructor(){

this.authChange=this.authManager_.asObservable();

}

}


LoggedIn,

LoggedOut

}

AddingAPImethodstotheauthenticationservice

RecallthatyoudonotwanttoexposetheBehaviorSubjectinstancetooutsideactors.Instead,youwouldliketoofferonlyitsObservablecomponent,whichyoucanopenlysubscribeto.Furthermore,youwouldliketoallowoutsideactorstosettheauthenticationstate,butonlyindirectly.Thiscanbeaccomplishedwiththefollowingmethods:





@Injectable()


privateauthManager_:BehaviorSubject<AuthState>

=newBehaviorSubject(AuthState.LoggedOut);


authChange:Observable<AuthState>;

constructor(){

this.authChange=this.authManager_.asObservable();

}

login():void{

this.setAuthState_(AuthState.LoggedIn);

}

logout():void{

this.setAuthState_(AuthState.LoggedOut);

}

emitAuthState():void{

this.authManager_.next(this.authState_);

}

privatesetAuthState_(newAuthState:AuthState):void{

this.authState_=newAuthState;

this.emitAuthState();

}

}


LoggedIn,

LoggedOut

}

Outstanding!Withallofthis,outsideactorswillbeabletosubscribetoauthChangeObservableandwillindirectlycontrolthestatevialogin()andlogout().

Tip

NotethattheObservablecomponentofBehaviorSubjectisnamedauthChange.NamingthedifferentcomponentsoftheelementsintheObserverPatterncanbetricky.ThisnamingconventionwasselectedtorepresentwhataneventemittedfromtheObservableactuallymeant.Quiteliterally,authChangeistheanswertothequestion,"WhateventamIobserving?".Therefore,itmakesgoodsemanticsensethatyourcomponentsubscribestoauthChangeswhentheauthenticationstatechanges.

Wiringtheservicemethodsintothecomponent

LoginComponentdoesnotyetutilizetheservice,soaddinitsnewlycreatedmethods:



import{AuthService,AuthState}from'./authentication.service';

@Component({

selector:'login',

template:`


(click)="login()">

Login

</button>


(click)="logout()">

Logout

</button>

`

})


loggedIn:boolean;

constructor(privateauthService_:AuthService){

authService_.authChange.subscribe(

newAuthState=>

this.loggedIn=(newAuthState===AuthState.LoggedIn));

}

login():void{

this.authService_.login();

}

logout():void{

this.authService_.logout();

}

}

Withallofthisinplace,youshouldbeabletoseeyourlogin/logoutbuttonsfunctionwell.ThismeansyouhavecorrectlyincorporatedObservableintoyourcomponent.

Tip

Thisrecipeisagoodexampleofconventionsyou'rerequiredtomaintainwhenusingpublic/private.Notethattheinjectedserviceisdeclaredasaprivatememberandwrappedwithpubliccomponentmembermethods.Anythingthatanotherpartoftheapplicationcallsoranythingthatisusedinsidethetemplateshouldbeapublicmember.

Howitworks...CentraltothisimplementationisthateachcomponentthatislisteningtoObservablehasanidempotenthandlingofeventsthatareemitted.EachtimeanewcomponentisconnectedtoObservable,itinstructstheservicetoemitwhateverthecurrentstateis,usingemitAuthState().Necessarily,allcomponentsdon'tbehaveanydifferentlyiftheyseethesamestateemittedmultipletimesinarow;theywillonlyaltertheirbehavioriftheyseeachangeinthestate.

Noticehowyouhavetotallyencapsulatedtheauthenticationstateinsidetheauthenticationservice,andatthesametime,haveexposedandutilizedareactiveAPIfortheentireapplicationtobuildupon.

There'smore...Twocriticalcomponentsofhookingintoservicessuchasthesearethesetupandteardownprocesses.AfastidiousdeveloperwillhavenoticedthatevenifaninstanceofLoginComponentisdestroyed,thesubscriptiontoObservablewillstillpersist.This,ofcourse,isextremelyundesirable!

Fortunately,thesubscribe()methodofObservablesreturnsaninstanceofSubscription,whichexposesanunsubscribe()method.Youcanthereforecapturethisinstanceupontheinvocationofsubscribe()andtheninvokeitwhenthecomponentisbeingtorndown.

SimilartolistenerteardowninAngular1,youmustinvoketheunsubscribemethodwhenthecomponentinstanceisbeingdestroyed.Happily,theAngular2lifecycleprovidesyouwithsuchamethod,ngOnDestroy,inwhichyoucaninvokeunsubscribe():


import{Component,ngOnDestroy}from'@angular/core';

import{AuthService,AuthState}from'./authentication.service';

import{Subscription}from'rxjs/Subscription';

@Component({

selector:'login',

template:`


(click)="login()">

Login

</button>


(click)="logout()">

Logout

</button>

`

})

exportclassLoginComponentimplementsOnDestroy{

loggedIn:boolean;

privateauthChangeSubscription_:Subscription;


this.authChangeSubscription_=

authService_.authChange.subscribe(

newAuthState=>

this.loggedIn=(newAuthState===AuthState.LoggedIn));

}

login():void{

this.authService_.login();

}

logout():void{


}

ngOnDestroy(){

this.authChangeSubscription_.unsubscribe();

}

}

Nowyourapplicationissafefrommemoryleaksshouldanyinstanceofthiscomponenteverbedestroyedinthelifetimeofyourapplication.

SeealsoBasicutilizationofObservableswithHTTPdemonstratesthebasicsofhowtouseanobservableinterfaceImplementingaPublish-SubscribemodelusingSubjectsshowsyouhowtoconfigureinputandoutputforRxJSObservablesBuildingageneralizedPublish-Subscribeservicetoreplace$broadcast,$emit,and$onassemblesarobustPubSubmodelforconnectingapplicationcomponentswithchannelsBuildingafullyfeaturedAutoCompletewithObservablesgivesyouabroadtourofsomeoftheutilitiesofferedtoyouaspartoftheRxJSlibrary

BuildingageneralizedPublish-Subscribeservicetoreplace$broadcast,$emit,and$onInAngular1,the$emitand$broadcastbehaviorswereindeedveryusefultools.Theygaveyoutheabilitytosendcustomeventsupwardsanddownwardsthroughthescopetreetoanylistenersthatmightbewaitingforsuchanevent.Thispushedthedevelopertowardsaveryusefulpattern:theabilityformanycomponentstobeabletotransmiteventstoandfromacentralsource.However,using$emitand$broadcastforsuchapurposewasgrosslyinappropriate;theyhadtheeffectoffeedingtheeventthroughhugenumbersofscopesonlytoreachthesingleintendedtarget.

Note

Inthepreviouseditionofthisbook,thecorrespondingrecipedemonstratedhowtobuildaPublish-Subscribeservicethatusedthe$emitand$rootScopeinjection.Theversioninthisrecipe,althoughdifferentinahandfulofways,achievessimilarresultsinasubstantiallycleanerandmoreelegantfashion.

Itispreferabletocreateasingleentitythatcanserveasagenericthroughwayforeventstopassfrompublisherstotheirsubscribers.

Note



GettingreadyBeginwithaskeletonserviceinjectedintoacomponent:

[app/node.component.ts]


import{PubSubService}from'./publish-subscribe.service';

@Component({

selector:'node',

template:`

<p>Heard{{count}}of{{subscribeChannel}}</p>

<button(click)="send()">Send{{publishChannel}}</button>

`

})

exportclassNodeComponent{

@Input()publishChannel:string;

@Input()subscribeChannel:string;

count:number=0;

constructor(privatepubSubService_:PubSubService){}

send(){}

}

[app/publish-subscribe.service.ts]


@Injectable()

exportclassPubSubService{

constructor(){}

publish(){}

subscribe(){}

}

Howtodoit...Thegroundworkforthisimplementationshouldbeprettyobvious.TheserviceisgoingtohostasingleSubjectinstancethatisgoingtofunneleventsofanytypeintotheserviceandoutthroughtheobserversoftheSubject.

First,implementthefollowingsothatsubscribe()andpublish()actuallydoworkwhenyouinvolvetheSubjectinstance:





import{Observer}from'rxjs/Observer';

import{Subscriber}from'rxjs/Subscriber;

@Injectable()


privatepublishSubscribeSubject_:Subject<any>=newSubject();

emitter_:Observable<any>;

constructor(){

this.emitter_=this.publishSubscribeSubject_.asObservable();

}

publish(event:any):void{

this.publishSubscribeSubject_.next(event);

}

subscribe(handler:NextObserver<any>):Subscriber{

returnthis.emitter_.subscribe(handler);

}

}

Thisisterrificforaninitialimplementation,butyieldsaproblem:everyeventpublishedtothisservicewillbebroadcastedtoallthesubscribers.

Introducingchannelabstraction

Itispossibleandinfactquiteeasytorestrictpublishandsubscribeinsuchawaythattheywillonlypayattentiontothechanneltheyspecify.First,modifypublish()tonesttheeventinsidetheemittedobject:







@Injectable()




constructor(){


}

publish(channel:string,event:any):void{

this.publishSubscribeSubject_.next({

channel:channel,

event:event

});

}

subscribe(handler:NextObserver<any>):Subscriber{

returnthis.emitter_.subscribe(handler);

}

}

Withthis,youarenowabletoutilizesomeObservablebehaviortorestrictwhicheventsthesubscriptionispayingattentionto.

Observableemissionscanhavefilter()andmap()appliedtothem.filter()willreturnanewObservableinstancethatonlyemitswhicheveremissionsevaluateastrueinitsfilterfunction.map()returnsanewObservableinstancethattransformsallemissionsintoanewvalue.







import'rxjs/add/operator/filter';


@Injectable()




constructor(){


}

publish(channel:string,event:any):void{

this.publishSubscribeSubject_.next({

channel:channel,

event:event

});

}

subscribe(channel:string,handler:((value:any)=>void)):Subscriber{

returnthis.emitter_

.filter(emission=>emission.channel===channel)

.map(emission=>emission.event)

.subscribe(handler);

}

}

Hookingcomponentsintotheservice

Theserviceiscomplete,butthecomponentdoesn'tyethavetheabilitytouseit.Usetheinjectedservicetolinkthecomponenttothechannelsspecifiedbyitsinputstrings:




@Component({

selector:'node',

template:`



`

})

exportclassNodeComponent{



count:number=0;


send(){

this.pubSubService_

.publish(this.publishChannel,{});

}

ngAfterViewInit(){

this.pubSubService_

.subscribe(this.subscribeChannel,

event=>++this.count);

}

}

Tip

Thepublish()methodhasanemptyobjectliteralasitssecondargument.Thisisthepayloadforthepublishedmessage,whichisn'tusedinthisrecipe.Ifyouwanttosenddataalongwitha

message,thisiswhereitwouldgo.

Withallofthis,testyourapplicationwiththefollowing:



@Component({

selector:'root',

template:`

<nodesubscribeChannel="foo"

publishChannel="bar">

</node>

<nodesubscribeChannel="bar"

publishChannel="foo">

</node>

`

})


Youwillseethatchannelpublishingandsubscribingishappeningasyouwouldexpect.

Unsubscribingfromchannels

Ofcourse,youwanttoavoidmemoryleakswhereverpossible.Thisrequiresthatyouexplicitlycompletethecleanupprocesswhenyourcomponentinstanceisdestroyed:


import{Component,Input,OnDestroy}from'@angular/core';



@Component({

selector:'node',

template:`



`

})

exportclassNodeComponentimplementsOnDestroy{



count:number=0;

privatepubSubServiceSubscription_:Subscription;


send(){

this.pubSubService_

.publish(this.publishChannel,{});

}

ngAfterViewInit(){

this.pubSubService_

.subscribe(this.subscribeChannel,

event=>++this.count);

}

ngOnDestroy(){

this.pubSubServiceSubscription_.unsubscribe();

}

}

Howitworks...Eachtimepublish()isinvoked,theprovidedeventiswrappedbytheprovidedchannelandsubmittedtoacentralSubject,whichisprivateinsidetheservice.Atthesametime,thefactthateachinvocationofsubscribe()wantstolistentoadifferentchannelpresentsaproblem.ThisisbecauseanObservabledoesnotdrawdistinctionsregardingwhatisbeingemittedwithoutexplicitdirection.

Youareabletoutilizethefilter()andmap()operatorstoestablishacustomizedviewoftheemissionsofSubjectandusethisviewintheapplicationoftheObserverhandler.Eachtimesubscribe()isinvoked,itcreatesanewObservableinstance;however,theseareallmerelypointsofindirectionfromtheonetrueObservable,whichisownedbytheprivateinstancehiddeninsidetheservice.

There'smore...It'simportanttounderstandwhythisserviceisnotbuiltinadifferentway.

AnimportantfeatureofObservablesistheirabilitytobecomposed.Thatis,severalObservableinstancesindependentlyemittingeventscanbecombinedintooneObservableinstance,whichwillemitalltheeventsfromacombinedsource.Thiscanbeaccomplishedinseveraldifferentways,includingflatMap()ormerge().ThisabilityiswhatisbeingreferredtowhenReactiveXObservablesaredescribedas"composable."

Therefore,adevelopermightseethiscompositionabilityandthinkitwouldbesuitableforaPublish-Subscribeentity.TheentitywouldacceptObservableinstancesfromthepublishers.TheywouldbecombinedtocreateasingleObservableinstance,andsubscriberswouldattachObservabletothiscombination.Whatcouldpossiblygowrong?

ConsiderationsofanObservable'scompositionandmanipulation

OneprimaryconcernisthatthecomposedObservablethatthesubscribersarebeingattachedtowillchangeconstantly.Asisthecasewithmap()andfilter(),anymodulationperformedonanObservableinstance,includingcomposition,willreturnanewObservableinstance.ThisnewinstancewouldbecometheObservablethatsubscriberswouldattachto,andthereinliestheproblem.

Let'sexaminethisproblemstepbystep:

1. PubSubserviceemitseventsfromObservableA.2. NodeXsubscribestotheserviceandreceiveseventsfromObservableA.3. SomeotherpartoftheapplicationaddsObservableBtothePubSubservice.4. ThePubSubservicecomposesObservableAandObservableBintoObservableAB.5. NodeYsubscribestotheserviceandreceiveseventsfromObservableAB.

Notethatinthiscase,NodeXwouldstillreceiveeventsfromonlyObservableAsincethatistheObservableinstancewhereitinvokedsubscribe().

Certainly,therearestepsthatcanbetakentomitigatethisproblem,suchashavinganadditionallevelofindirectionbetweenthesubscribeObservableandthecomposedObservable.However,awiseengineerwillstepbackatthispointandtakestockofthesituation.Publish-Subscribeissupposedtobearelatively"dumb"protocol,meaningthatitshouldn'tbedelegatedtoomuchresponsibilityaroundmanagingtheeventsithasbeenpassedwith—messagesinandmessagesout,withnorealconcernforwhatiscontainedaslongastheygetthere.OnecouldmakeaverystrongargumentthatintroducingObservablesinthePublishsidegreatlyovercomplicatesthings.

Inthecaseofthisrecipe,youhavedevelopedanelegantandsimpleversionofaPublish-Subscribemodule,anditfeelsrighttodelegatecomplexityoutsideofit.InthecaseofentitieswantingtousePublishwithObservables,asolutionmightbetojustpipetheObservableemissionsintotheservice'spublish()method.

SeealsoBasicutilizationofObservableswithHTTPdemonstratesthebasicsofhowtouseanobservableinterfaceImplementingaPublish-SubscribemodelusingSubjectsshowsyouhowtoconfigureinputandoutputforRxJSObservablesCreatinganObservableauthenticationserviceusingBehaviorSubjectsinstructsyouonhowtoreactivelymanagethestateinyourapplicationBuildingafullyfeaturedAutoCompletewithObservablesgivesyouabroadtourofsomeoftheutilitiesofferedtoyouaspartoftheRxJSlibrary

UsingQueryListsandObservablestofollowchangesinViewChildrenOneveryusefulpieceofbehaviorincomponentsistheabilitytotrackchangestothecollectionsofchildrenintheview.Inmanyways,thisisquiteanebuloussubject,asthenumberofwaysinwhichviewcollectionscanbealteredisnumerousandsubtle.Thankfully,Angular2providesasolidfoundationfortrackingthesechanges.

Note



GettingreadySupposeyoubeginwiththefollowingskeletonapplication:

[app/inner.component.ts]


@Component({

selector:'inner',

template:`<p>{{val}}`

})

exportclassInnerComponent{

@Input()val:number;

}

[app/outer.component.ts]


@Component({

selector:'outer',

template:`

<button(click)="add()">Moar</button>

<button(click)="remove()">Less</button>

<button(click)="shuffle()">Shuffle</button>

<inner*ngFor="letioflist"

val="{{i}}">

</inner>

`

})

exportclassOuterComponent{

list:Array<number>=[];

add():void{

this.list.push(this.list.length)

}

remove():void{

this.list.pop();

}

shuffle():void{

//simpleassignmentshuffle

this.list=this.list.sort(()=>(4*Math.random()>2)?1:-1);

}

}

Asis,thisisaverysimplelistmanagerthatgivesyoutheabilitytoadd,remove,andshufflealistinterpolatedasInnerComponentinstances.Youwanttheabilitytotrackwhenthislistundergoeschangesandkeepreferencestothecomponentinstancesthatcorrespondtotheviewcollection.

Howtodoit...BeginbyusingViewChildrentocollecttheInnerComponentinstancesintoasingleQueryList:

[app/outer.component.ts]

import{Component,ViewChildren,QueryList}from'@angular/core';

import{InnerComponent}from'./inner.component';

@Component({

selector:'outer',

template:`





val="{{i}}">

</inner>

`

})


@ViewChildren(InnerComponent)innerComponents:

QueryList<InnerComponent>;


add():void{


}

remove():void{

this.list.pop();

}

shuffle():void{



}

}

Easy!Now,oncetheviewofOuterComponentisinitialized,youwillbeabletousethis.innerComponentstoreferenceQueryList.

DealingwithQueryLists

QueryListsarestrangebirdsinAngular2,butlikemanyotherfacetsoftheframework,theyarejustaconventionthatyouwillhavetolearn.Inthiscase,theyareanimmutableanditerablecollectionthatexposesahandfulofmethodstoinspectwhattheycontainandwhenthesecontentsarealtered.

Inthiscase,thetwoinstancepropertiesyoucareaboutarelastandchanges.last,asyoumight

expect,willreturnthelastinstanceofQueryList—inthiscase,aninstanceofInnerComponentifQueryListisnotempty.changeswillreturnanObservablethatwillemitQueryListwheneverachangeoccursinsideit.InthecaseofacollectionofInnerComponentinstances,theaddition,removal,andshufflingoptionswillallberegisteredaschanges.

Usingtheseproperties,youcanveryeasilysetupOuterComponenttokeeptrackofwhatthevalueofthelastInnerComponentinstanceis:

import{Component,ViewChildren,QueryList}from'@angular/core';


@Component({

selector:'app-outer',

template:`




<app-inner*ngFor="letioflist"

val="{{i}}">

</app-inner>

<p>Valueoflast:{{lastVal}}</p>

`

})





lastVal:number;

constructor(){}

add(){


}

remove(){

this.list.pop();

}

shuffle(){


}

ngAfterViewInit(){

this.innerComponents.changes

.subscribe(e=>this.lastVal=(e.last||{}).val);

}

}

Withallofthis,youshouldbeabletofindthatlastValwillstayuptodatewithanychangesyouwouldtriggerintheInnerComponentcollection.

Correctingtheexpressionchangederror

Ifyouruntheapplicationasis,youwillnoticethatanerroristhrownafteryouclickontheMoarbuttonthefirsttime:

Expressionhaschangedafteritwaschecked

ThisisanerroryouwillmostlikelyseefrequentlyinAngular2.Themeaningissimple:sinceyouare,bydefault,operatingindevelopmentmode,Angularwillchecktwicetoseethatanyboundvaluesdonotchangeafterallofthechangedetectionlogichasbeenresolved.Inthecaseofthisrecipe,theemissionbyQueryListmodifieslastVal,whichAngulardoesnotexpect.Thus,you'llneedtoexplicitlyinformtheframeworkthatthevalueisexpectedtochangeagain.ThiscanbeaccomplishedbyinjectingChangeDetectorRef,whichallowsyoutotriggerachangedetectioncycleoncethevalueischanged:

import{Component,ViewChildren,QueryList,ngAfterViewInit,

ChangeDetectorRef}from'@angular/core';


@Component({

selector:'outer',

template:`





val="{{i}}">

</inner>

<p>Valueoflast:{{lastVal}}</p>

`

})

exportclassOuterComponentimplementsAfterViewInit{




lastVal:number;

constructor(privatechangeDetectorRef_:ChangeDetectorRef){}

add():void{


}

remove():void{

this.list.pop();

}

shuffle():void{



}

ngAfterViewInit(){

this.innerComponents.changes

.subscribe(innerComponents=>{

this.lastVal=(innerComponents.last||{}).val;

this.changeDetectorRef_.detectChanges();

});

}

}

Atthispoint,everythingshouldworkcorrectlywithnoerrors.

Howitworks...OncetheOuterComponentviewisinitialized,youwillbeabletointeractwithQueryListthatisobtainedusingViewChildren.EachtimethecollectionthatQueryListwrapsismodified,theObservableexposedbyitschangespropertywillemitQueryList,signalingthatsomethinghaschanged.

Hatetheplayer,notthegame

Importantly,Observable<QueryList>doesnottrackchangesinthearrayofnumbers.IttracksthegeneratedcollectionofInnerComponents.ThengForstructuraldirectiveisresponsibleforgeneratingthelistofInnerComponentinstancesintheview.ItisthiscollectionthatQueryListisconcernedwith,nottheoriginalarray.

Thisisagoodthing!ViewChildrenshouldonlybeconcernedwiththecomponentsastheyhavebeenrenderedinsidetheview,notthedatathatcausedthemtoberenderedinsuchafashion.

Oneimportantconsiderationofthisisthatuponeachemission,itisentirelypossiblethatQueryListwillbeempty.Asshownabove,sincetheObserveroftheQueryList.changesObservabletriestoreferenceapropertyoflast,itisnecessarytohaveafallbackobjectliteralintheeventthatlastreturnsundefined.

SeealsoBasicUtilizationofObservableswithHTTPdemonstratesthebasicsofhowtouseanobservableinterfaceBuildingafullyfeaturedAutoCompletewithObservablesgivesyouabroadtourofsomeoftheutilitiesofferedtoyouaspartoftheRxJSlibrary

BuildingafullyfeaturedAutoCompletewithObservablesRxJSObservablesaffordyoualotoffirepower,anditwouldbeashametomissoutonthem.Ahugelibraryoftransformationsandutilitiesarebakedrightinthatallowyoutoelegantlyarchitectcomplexportionsofyourapplicationinareactivefashion.

Inthisrecipe,you'lltakeanaïveautocompleteformandbuildarobustsetoffeaturestoenhancebehaviorandperformance.

Note



GettingreadyBeginwiththefollowingapplication:

[app/app.module.ts]



import{SearchComponent}from'./search.component';

import{APIService}from'./api.service';

import{HttpModule}from'@angular/http';

@NgModule({

imports:[

BrowserModule,

HttpModule

],

declarations:[

SearchComponent

],

providers:[

APIService

],

bootstrap:[

SearchComponent

]

})


[app/search.component.ts]



@Component({

selector:'search',

template:`

<input#queryField(keyup)="search(queryField.value)">

<p*ngFor="letresultofresults">{{result}}</p>

`

})

exportclassSearchComponent{

results:Array<string>=[];

constructor(privateapiService_:APIService){}

search(query:string):void{

this.apiService_

.search(query)

.subscribe(result=>this.results.push(result));

}

}

[app/api.service.ts]




@Injectable()

exportclassAPIService{

constructor(privatehttp_:Http){}

search(query:string):Observable<string>{

returnthis.http_

.get('static/response.json')

.map(r=>r.json()['prefix']+query)

//Belowisjustacleverwayofrandomly

//delayingtheresponsebetween0to1000ms

.concatMap(

x=>Observable.of(x).delay(Math.random()*1000));

}

}

YourobjectiveistodramaticallyenhancethisusingRxJS.

Howtodoit...Asis,thisapplicationislisteningforkeyupeventsinthesearchinput,performinganHTTPrequesttoastaticJSONfileandaddingtheresponsetoalistofresults.

UsingtheFormControlvalueChangesObservable

Angular2hasobservablebehavioralreadyavailabletoyouinanumberofplaces.OneofthemisinsideReactiveFormsModule,whichallowsyoutouseanObservablethatisattachedtoaforminput.ConvertthisinputtouseFormControl,whichexposesavalueChangesObservable:

[app/app.module.ts]



import{SearchComponent}from'./search.component';


import{HttpModule}from'@angular/http';


@NgModule({

imports:[

BrowserModule,

HttpModule,

ReactiveFormsModule

],

declarations:[

SearchComponent

],

providers:[

APIService

],

bootstrap:[

SearchComponent

]

})






@Component({

selector:'search',

template:`

<input[formControl]="queryField">


`

})



queryField:FormControl=newFormControl();

constructor(privateapiService_:APIService){

this.queryField.valueChanges

.subscribe(query=>this.apiService_

.search(query)

.subscribe(result=>this.results.push(result)));

}

}

Debouncingtheinput

Eachtimetheinputvaluechanges,Angularwilldutifullyfireoffarequestandhandletheresponseassoonasitisready.Inthecasewheretheuserisqueryingaverylongterm,suchassupercalifragilisticexpialidocious,itmaybenecessaryforyoutoonlysendoffasinglerequestonceyouthinkthey'redonewithtyping,asopposedto34requests,oneforeachtimetheinputchanges.

RxJSObservableshavethisbuiltin.debounceTime(delay)willcreateanewObservablethatwillonlypassalongthelatestvaluewhentherehaven'tbeenanyothervaluesfor<delay>ms.ThisshouldbeaddedtothevalueChangesObservablesincethisisthesourcethatyouwishtodebounce.200mswillbesuitableforyourpurposes:





@Component({

selector:'search',

template:`



`

})






.debounceTime(200)


.search(query)


}

}

Note

Theoriginofthetermdebouncecomesfromtheworldofcircuits.Mechanicalbuttonsorswitchesutilizemetalcontactstoopenandclosecircuitconnections.Whenthemetalcontactsareclosed,theywillbangtogetherandreboundbeforebeingsettled,causingbounce.Thisbounceisproblematicinthecircuit,asitwilloftenregisterasarepeattogglingoftheswitchorbutton—obviouslybuggybehavior.Theworkaroundforthisistofindawaytoignoretheexpectedbouncenoise—debouncing!Thiscanbeaccomplishedbyeitherignoringthebouncenoiseorintroducingadelaybeforereadingthevalue,bothofwhichcanbedonewithhardwareorsoftware.

Ignoringserialduplicates

Sinceyouarereadinginputfromatextbox,itisverypossiblethattheuserwilltypeonecharacter,thentypeanothercharacterandpressbackspace.FromtheperspectiveoftheObservable,sinceitisnowdebouncedbyadelayperiod,itisentirelypossiblethattheuserinputwillbeinterpretedinsuchawaythatthedebouncedoutputwillemittwoidenticalvaluessequentially.RxJSoffersexcellentprotectionagainstthis,distinctUntilChanged(),whichwilldiscardanemissionthatwillbeaduplicateofitsimmediatepredecessor:





@Component({

selector:'search',

template:`



`

})






.debounceTime(200)

.distinctUntilChanged()


.search(query)


}

}

FlatteningObservables

YouhavechainedquiteafewRxJSmethodsuptothispoint,andseeingnestedsubscribe()

invocationsmightfeelabitfunnytoyou.ItshouldmakesensesincethevalueChangesObservablehandlerisinvokingaservicemethod,whichreturnsaseparateObservable.InTypeScript,thisiseffectivelyrepresentedasObservable<Observable<string>>.Gross!

Sinceyouonlyreallycareabouttheemittedstringscomingfromtheservicemethod,itwouldbemucheasiertojustcombinealltheemittedstringscomingoutofeachreturnedObservableintoasingleObservable.Fortunately,RxJSmakesthiseasywithflatMap,whichflattensalltheemissionsfromtheinnerObservablesintoasingleouterObservable.InTypeScript,usingflatMapwouldconvertthisintoObservable<string>,whichisexactlywhatyouneed:





@Component({

selector:'search',

template:`



`

})






.debounceTime(200)


.flatMap(query=>this.apiService_.search(query))


}

}

Handlingunorderedresponses

Whentestinginputnow,youwillsurelynoticethatthedelayintentionallyintroducedinsidetheAPIservicewillcausetheresponsestobereturnedoutoforder.Thisisaprettyeffectivesimulationofnetworklatency,soyou'llneedagoodwayofhandlingthis.

Ideally,youwouldliketobeabletothrowoutObservablesthatareinflightonceyouhaveamorerecentquerytoexecute.Forexample,considerthatyou'vetypedgandtheno.Nowoncethesecondqueryforgoisreturnedandifthefirstqueryforghasn'treturnedyet,you'dliketojustthrowitoutandforgetaboutitsincetheresponseisnowirrelevant.

RxJSalsomakesthisveryeasywithswitchMap.ThisdoesthesamethingsasflatMap,butit

willunsubscribefromanyin-flightObservablesthathavenotemittedanyvaluesyet:





@Component({

selector:'search',

template:`



`

})






.debounceTime(200)


.switchMap(query=>this.apiService_.search(query))


}

}

YourAutoCompleteinputshouldnowbedebouncedanditshouldignoreredundantrequestsandreturnin-orderresults.

Howitworks...Therearealotofmovingpiecesgoingoninthisrecipe,butthecorethemeremainsthesame:RxJSObservablesexposemanymethodsthatcanpipetheoutputfromoneobservableintoanentirelydifferentobservable.Itcanalsocombinemultipleobservablesintoasingleobservable,aswellasintroducestate-dependentoperationsintoastreamoftheinput.Attheendofthisrecipe,thepowerofreactiveprogrammingshouldbeobvious.

SeealsoBasicUtilizationofObservableswithHTTPdemonstratesthebasicsofhowtouseanobservableinterfaceImplementingaPublish-SubscribemodelusingSubjectsshowsyouhowtoconfigureinputandoutputforRxJSObservablesCreatinganObservableauthenticationserviceusingBehaviorSubjectsinstructsyouonhowtoreactivelymanagethestateinyourapplicationBuildingageneralizedPublish-Subscribeservicetoreplace$broadcast,$emit,and$onassemblesarobustPubSubmodelforconnectingapplicationcomponentswithchannels

Chapter6.TheComponentRouterThischapterwillcoverthefollowingrecipes:

SettingupanapplicationtosupportsimpleroutesNavigatingwithrouterLinksNavigatingwiththeRouterserviceSelectingLocationStrategyforPathConstructionBuildingstatefulRouterLinkbehaviorwithRouterLinkActiveImplementingnestedviewswithrouteparametersandchildroutesWorkingwithMatrixURLparametersandroutingarraysAddingrouteauthenticationcontrolswithrouteguards

IntroductionFewfeaturesofAngular2shouldbeanticipatedmorethantheComponentRouter.ThisnewroutingimplementationaffordsyouadazzlingarrayoffeaturesthatweremissingorseverelylackinginAngular1.

Angular2implementsmatrixparameters;thisisanentirelynewsyntaxforURLstructures.OriginallyproposedbyTimBerners-Leein1996,thissemicolon-basedsyntaxgivesyoutheabilitytorobustlyassociateparametersnotjustwithasingleURL,butwithdifferentlevelsinthatURL.YourapplicationcannowintroduceanadditionaldimensionofapplicationstateintheURLs.

Additionally,ComponentRoutergivesyouamethodofelegantlynestingviewswithineachotheraswellasasimplewayofdefiningroutesandlinkstothesecomponenthierarchies.Foryou,thismeansyourapplicationscantrulytakemaximaladvantageofdefininganapplicationasanindependentmodule.

Finally,ComponentRouterfullyembracesintegrationwithObservablestructuresandprovidesyouwithsomebeautifulwaysofnavigatingandcontrollingnavigationwithinyourapplication.

SettingupanapplicationtosupportsimpleroutesCentraltothebehaviorofsingle-pageapplicationsistheabilitytoperformnavigationwithoutaformalbrowserpagereload.Angular2iswell-equippedtoworkaroundthedefaultbrowserpagereloadbehaviorandallowyoutodefinearoutingstructurewithinit,whichwillmakeitlookandfeellikeactualpagenavigation.

Note

Thecode,links,andaliveexampleofthisareavailableathttp://ngcookbook.herokuapp.com/6214.


GettingreadySupposeyouhavethefollowingfunctiondefinedglobally:

functionvisit(uri){

//Forthisrecipe,youdon'tcareaboutthestateortitle

window.history.pushState(null,null,uri);

}

ThepurposeofthisistomerelyallowyoutonavigateinsidethebrowserfromJavaScriptusingtheHTML5HistoryAPI.

Howtodoit...InorderforAngulartosimulatepagenavigationinsidethebrowser,thereareseveralstepsyoumusttaketocreateanavigablesingle-pageapplication.

SettingthebaseURL

ThefirststepinconfiguringyourapplicationistospecifythebaseURL.ThisinstructsthebrowserwhatnetworkrequestsperformedwitharelativeURLshouldbeginwith.

AnytimethepagemakesarequestusingarelativeURL,whengeneratingthenetworkrequest,itwillusethecurrentdomainandthenappendtherelativeURL.ForrelativeURLs,aprepended"/"meansitwillalwaysusetherootdirectory.Iftheforwardslashisunavailable,therelativepathwillprependwhateverisspecifiedasthebasehref.AnyURLbehavior,includingrequestingstaticresources,anchorlinks,andthehistoryAPI,willexhibitthisbehavior.

Note

<base>isnotapartofAngularbutratheradefaultHTML5element.

Herearesomeexamplesofthis:

[Example1]

//<basehref="/">

//initialpagelocation:foo.com

visit('bar');

//newpagelocation:foo.com/bar

visit('bar');

//newpagelocation:foo.com/bar

//Thebrowserrecognizesthatthisisarelativepath

//withnoprepended/andsoitwillvisitthepageatthe

//same"depth"asbefore.

visit('bar/');

//newpagelocation:foo.com/bar/

//Sameasbefore,butthetrailingslashwillbeimportantonce

//youinvokethisagain.

visit('bar/');

//newpagelocation:foo.com/bar/bar/

//ThebrowserrecognizesthattheURLendswitha/,andso

//visitingarelativepathistreatedasanavigationintoa

//subpath

visit('/qux');

//newpagelocation:foo.com/qux

//Witha/prependedtotheURL,thebrowserrecognizesthatit

//shouldnavigatefromtherootdomain

[Example2]

//<basehref="xyz/">

//initialpagelocation:foo.com

visit('bar');

//newpagelocation:foo.com/xyz/bar

//BaseURLisprependedtotherelativeURL

visit('bar');

//newpagelocation:foo.com/xyz/bar

//Aswasthecasebefore,thelocalpathistreatedthesame

//bythebrowser

visit('/qux');

//newpagelocation:foo.com/qux

//Notethatinthiscase,youspecifiedarelativepath

//originatingfromtherootdomain,sothebasehrefisignored

Definingroutes

Next,youneedtodefinewhatyourapplication'sroutesare.Forthepurposeofthisrecipe,itismoreimportanttounderstandthesetupofroutingthanhowtodefineandnavigatebetweenroutes.So,fornow,youwilljustdefineasinglecatchallroute.

Asyoumightsuspect,routeviewsinAngular2aredefinedascomponents.Eachroutepathisrepresentedattheveryleastbythestringthatthebrowser'slocationwillmatchagainstandthecomponentthatitwillmapto.ThiscanbedonewithanobjectimplementingtheRoutesinterface,whichisanarrayofroutedefinitions.

Itmakessensethattheroutedefinitionsshouldhappenveryearlyintheapplicationinitialization,soyou'lldoitinsidethetop-levelmoduledefinition.

First,createyourviewcomponentthatthisroutewillmapto:

[app/default.component.ts]


@Component({

template:'Defaultcomponent!'

})

exportclassDefaultComponent{}

Next,whereveryourapplicationmoduleisdefined,importRouterModuleandtheRoutesinterface,namelyDefaultComponent,anddefineacatchallrouteinsidetheRoutesarray:

[app/app.module.ts]



import{RouterModule,Routes}from'@angular/router';


import{DefaultComponent}from'./default.component';

constappRoutes:Routes=[

{path:'**',component:DefaultComponent}

];

@NgModule({

imports:[

BrowserModule

],

declarations:[

DefaultComponent,

RootComponent

],

bootstrap:[

RootComponent

]

})


Providingroutestotheapplication

You'vedefinedtheroutesinanobject,butyourapplicationstillisnotawarethattheyexist.YoucandothiswiththeforRootmethoddefinedinRouterModule.Thisfunctiondoesallthedirtyworkofinstallingyourroutesintheapplicationaswellaspassingalonganumberofroutingprovidersforuseelsewhereintheapplication:

[app/app.module.ts]








];

@NgModule({

imports:[

BrowserModule,

RouterModule.forRoot(appRoutes)

],

declarations:[

DefaultComponent,

RootComponent

],

bootstrap:[

RootComponent

]

})


Withthis,yourapplicationisfullyconfiguredtounderstandtherouteyouhavedefined.

RenderingroutecomponentswithRouterOutlet

Thecomponentneedsaplacetoberendered,andinAngular2,thistakestheformofaRouterOutlettag.Thisdirectivewillbetargetedbythecomponentattachedtotheactiveroute,andthecomponentwillberenderedinsideit.Tokeepthingssimple,inthisrecipe,youcanusethedirectiveinsidetherootapplicationcomponent:

[app/app.component.ts]


@Component({

selector:'root',

template:`

<h1>Rootcomponent</h1>

<router-outlet></router-outlet>

`

})


That'sall!YourapplicationnowhasasingleroutedefinedthatwillrenderDefaultComponentinsideRootComponent.

Howitworks...Thisrecipedoesn'tshowaverycomplicatedexampleofrouting,sinceeverypossibleroutethatyoucanvisitwillleadyoutothesamecomponent.

Nonetheless,itdemonstratesseveralfundamentalprinciplesofAngularrouting:

Initsmostbasicform,arouteiscomprisedofastringpath(matchedagainstthebrowserpath)andthecomponentthatshouldberenderedwhenthisrouteisactive.RoutesareinstalledviaRouterModule.Inthisexample,sincethereisonlyonemodule,youcandothisonceusingforRoot().However,keepinmindthatyoucanbreakyourroutingstructureintopiecesandbetweendifferentNgModules.Navigatingtoaroutewillcauseacomponenttoberenderedinsideadifferentcomponent-morespecifically,whereverthe<router-outlet>tagexists.Therearemanywaysinwhichthiscanbeconfiguredandmademorecomplex,butforthepurposeofthissimplemodule,youdon'tneedtoworryaboutthesedifferentways.

There'smore...Angular2applicationswillnotraiseissueswhenoperatingwithnoformofrouting.IfyourapplicationdoesnotneedtounderstandandmanagethepageURL,thenfeelfreetototallydiscardtheroutingfilesandmodulesfromyourapplication.

Initialpageload

Theflowyouarehopingyouruserswouldgothroughisasfollows:

1. Theuservisitshttp://www.foo.com/.2. Theservermatchestheemptyroutetoindex.html.3. Thepageloads,requestingstaticfiles.4. TheAngularstaticfilesareloadedandapplicationisbootstrapped.5. Theuserclicksonthelinksandnavigatesaroundthesite.6. SinceAngulariswhollymanagingthenavigationandrouting,everythingworksasexpected.

Thisistheidealcase.Consideradifferentcase:

1. Theuserhasalreadyvisitedhttp://www.foo.com/beforeandbookmarkedit.2. Theuserentersfoo.com/barintheirURLbarandnavigatestoitfromtheredirectly.3. Theserverseestherequestpathas/barandtriestohandletherequest.

Dependingonhowyourserverisconfigured,thismightcauseproblemsforyou.Thisisbecausethelasttimetheuservisitedfoo.com/bar,norequestforthatresourcereachedtheserverbecauseAngularwasonlyemulatingarealnavigationevent.

Thisscenarioisdiscussedelsewhereinthischapter,butkeepinmindthatwithoutacorrectlyconfiguredserver,theuserinthesecondcasemightseea404pageerrorinsteadofyourapplication.

http://www.foo.com/

http://www.foo.com/

SeealsoNavigatingwithrouterLinksdemonstrateshowtonavigatearoundAngularapplicationsNavigatingwiththeRouterserviceusesanAngularservicetonavigatearoundanapplicationBuildingstatefulRouterLinkbehaviorwithRouterLinkActiveshowshowtointegrateapplicationbehaviorwithaURLstate

NavigatingwithrouterLinksNavigatingaroundasinglepageapplicationisafundamentaltask,andAngularoffersyouabuilt-indirective,routerLink,toaccomplishthis.

Note



GettingreadyBeginwiththeapplicationsetupassembledintheSettingupanapplicationtosupportsimpleroutesrecipe.

Yourgoalistoaddanadditionalroutetothisapplicationaccompaniedbyacomponent;also,youwanttobeabletonavigatebetweenthemusinglinks.

Howtodoit...Tobegin,createanothercomponent,ArticleComponent,andanassociatedroute:

[app/article/article.component.ts]


@Component({

template:'Articlecomponent!'

})


Next,installanarticlerouteaccompaniedbythisnewcomponent:

[app/app.module.ts]








{path:'article',component:ArticleComponent},


];

@NgModule({

imports:[

BrowserModule,


],

declarations:[

DefaultComponent,

ArticleComponent,

RootComponent

],

bootstrap:[

RootComponent

]

})


Withtheroutesdefined,youcannowbuildarudimentarynavbarcomprisedofrouterLinks.Themarkupsurroundingthe<router-outlet>tagwillremainirrespectiveoftheroute,sotherootappcomponentseemslikeasuitableplaceforthenavlinks.

TherouterLinkdirectiveisavailableaspartofRouterModule,soyoucangostraighttoadding

someanchortags:



@Component({

selector:'root',

template:`


<a[routerLink]="''">Default</a>

<a[routerLink]="'article'">Article</a>


`

})


Inthiscase,sincetheroutesaresimpleandstatic,bindingrouterLinktoastringisallowed.routerLinkalsoacceptsthearraynotation:



@Component({

selector:'root',

template:`


<a[routerLink]="['']">Default</a>

<a[routerLink]="['article']">Article</a>


`

})


Tip

Forthepurposeofthisrecipe,thearraynotationdoesn'taddanything.However,whendevelopingmorecomplicatedURLstructures,thearraynotationbecomesuseful,asitallowsyoutogeneratelinksinapiecewisefashion.

Howitworks...Atahighlevel,thisisnodifferentthanthebehaviorofavanillahrefattribute.Afterall,theroutesbehaveinthesamewayandarestructuredsimilarly.TheimportantdifferencehereisthatusingarouterLinkdirectiveinsteadofhrefallowsyoutomovearoundyourapplicationtheAngularway,withouteverhavingtheanchortagclickinterpretedbythebrowserasanon-Angularnavigationevent.

There'smore...Ofcourse,therouterLinkdirectiveisalsosuperiorasitismoreextensibleasatoolfornavigating.SinceitisanHTMLattributeafterall,there'snoreasonrouterLinkcan'tbeattachedto,forexample,abuttoninstead:



@Component({

selector:'root',

template:`


<button[routerLink]="['']">Default</button>

<button[routerLink]="['article']">Article</button>


`

})


What'smore,you'llalsonotethatthearraynotationallowsthedynamicgenerationoflinksviaallofthetremendousdatabindingthatAngularaffordsyou:



@Component({

selector:'root',

template:`


<a[routerLink]="[defaultPath]">Default</a>

<a[routerLink]="[articlePath]">Article</a>


`

})

exportclassRootComponent{

defaultPath:string='';

articlePath:string='article';

}

AstheURLstructuregetsevermoreadvanced,itwillbeeasytoseehowacleverapplicationofdatabindingcouldmakeforsomeveryelegantdynamiclinkgeneration.

Routeorderconsiderations

TheorderingofroutesinsidetheRoutesdefinitionspecifiesthedescendingpriorityofeachofthem.Inthisrecipe'sexample,supposeyouweretoreversetheorderoftheroutes:

[app/app.module.ts]








{path:'**',component:DefaultComponent},

{path:'article',component:ArticleComponent}

];

@NgModule({

imports:[

BrowserModule,


],

declarations:[

DefaultComponent,

ArticleComponent,

RootComponent

],

bootstrap:[

RootComponent

]

})


Whenexperimenting,youwillfindthatthebrowser'sURLchangescorrectlywiththevariousrouterLinkinteractions,butbothrouteswilluseDefaultComponentastherenderedview.Thisissimplybecausealltheroutesmatchthe**catchall,andAngulardoesn'tbothertotraversetheroutesanyfurtheronceithasamatchingroute.Keepthisinmindwhenauthoringlargeroutetables.

SeealsoSettingupanapplicationtosupportsimpleroutesshowsyouthebasicsofAngularroutingNavigatingwiththeRouterserviceusesanAngularservicetonavigatearoundanapplicationBuildingstatefulRouterLinkbehaviorwithRouterLinkActiveshowshowtointegrateapplicationbehaviorwithaURLstateImplementingnestedviewswithrouteparametersandchildroutesgivesanexampleofhowtoconfigureAngularURLstosupportnestinganddatapassingWorkingwithmatrixURLparametersandroutingarraysdemonstratesAngular'sbuilt-inmatrixURLsupport

NavigatingwiththeRouterserviceThecompaniontousingrouterLinkinsidethetemplatetonavigateisdoingitfrominsideJavaScript.Angularexposesthenavigate()methodfrominsideaservice,whichallowsyoutoaccomplishexactlythis.

Note



GettingreadyBeginwiththeapplicationthatexistsattheendoftheHowtodoit...sectionoftheNavigatingwithrouterLinksrecipe.

Yourgoalistoaddanadditionalrouteaccompaniedbyacomponenttothisapplication;also,youwishtobeabletonavigatebetweenthemusinglinks.

Howtodoit...InsteadofusingrouterLink,whichisthemostsensiblechoiceinthissituation,youcanalsotriggeranavigationusingtheRouterservice.First,addnavbuttonsandattachsomeemptyclickhandlerstothem:



@Component({

selector:'root',

template:`


<button(click)="visitDefault()">Default</button>

<button(click)="visitArticle()">Article</button>


`

})


visitDefault():void{}

visitArticle():void{}

}

Next,importtheRouterserviceanduseitsnavigate()methodtochangethepagelocation:



import{Router}from'@angular/router';

@Component({

selector:'root',

template:`


<button(click)="visitDefault()">Default</button>

<button(click)="visitArticle()">Article</button>


`

})


constructor(privaterouter:Router){}

visitDefault():void{

this.router.navigate(['']);

}

visitArticle():void{

this.router.navigate(['article']);

}

}

Withthisaddition,youshouldbeabletonavigatearoundyourapplicationinthesamewayyou

didbefore.

Howitworks...TheRouterserviceexposesanAPIwithwhichyoucancontrolyourapplication'snavigationbehavior,amongmanyotherthings.Itsnavigate()methodacceptsanarray-structuredroute,whichoperatesidenticallytotheArraysboundtorouterLink.

There'smore...Obviously,thisisanutterantipatternforbuildingapplicationsthataredesignedtoscale.Inthisscenario,routerLinkisamuchmoresuccinctandeffectivechoiceforbuildingasimplenavbar.Nevertheless,theRouterserviceisanequallyeffectivetoolfortraversinganAngularapplication'sroutestructure.

SeealsoNavigatingwithrouterLinksdemonstrateshowtonavigatearoundAngularapplicationsBuildingstatefulRouterLinkbehaviorwithRouterLinkActiveshowshowtointegrateapplicationbehaviorwithaURLstateWorkingwithmatrixURLparametersandroutingarraysdemonstratesAngular'sbuilt-inmatrixURLsupportAddingrouteauthenticationcontrolswithrouteguardsdetailstheentireprocessofconfiguringprotectedroutesinyourapplication

SelectingaLocationStrategyforpathconstructionAsimplebutimportantchoiceforyourapplicationiswhichtypeofLocationStrategyyouwanttomakeuseof.ThefollowingtwoURLsareequivalentwhentheirrespectiveLocationStrategyisselected:

PathLocationStrategy:foo.com/barHashLocationStrategy:foo.com/#/bar

Note



Howtodoit...Angular2willdefaulttoPathLocationStrategy.ShouldyouwanttoselectHashLocationStrategy,itcanbeimportedfromthe@angular/commonmodule.Onceimported,itcanbelistedasaproviderinsideanobjectliteral:

[app/app.module.ts]







import{LocationStrategy,HashLocationStrategy}

from'@angular/common';


{path:'article',component:ArticleComponent},


];

@NgModule({

imports:[

BrowserModule,


],

declarations:[

DefaultComponent,

ArticleComponent,

RootComponent

],

providers:[

{provide:LocationStrategy,useClass:HashLocationStrategy}

],

bootstrap:[

RootComponent

]

})


Withthisaddition,yourapplicationwilltransitiontoprefix#/toallapplication-definedURLs.Thiswilloccurintransparencewiththerestofyourapplication,whichcanuseitsroutingdefinitionsnormallywithouthavingtoworryaboutprefixing#/.

There'smore...Therearetradeoffsforeachofthesestrategies.AstheAngulardocumentationnotes,onceyouchooseone,itisinadvisabletoswitchtotheothersincebookmarks,SEO,anduserhistorywillallbecoupledtotheURLstrategyutilizedduringthatvisit.

PathLocationStrategy:

Here,theURLsappearnormaltotheenduserTheservermustbeconfiguredtohandlepageloadsfromanyapplicationpathThisallowsthehybridserver-siderenderingofroutesforimprovedperformance

HashLocationStrategy:

Here,theURLsmaylookfunnytotheenduser.Noserverconfigurationisrequirediftherootdomainservesindex.html.Thisisagoodoptionifyouonlywanttoservestaticfiles(forexample,anAmazonAWS-basedsite).Itcannotbeeasilyintermixedwithhybridserver-siderendering.

ConfiguringyourapplicationserverforPathLocationStrategy

Angularissmartenoughtorecognizethebrowserstateandmanageitaccordinglyoncebootstrappingoccurs.However,bootstrappingrequiresaninitialloadofthestaticcompiledJSassets,whichwillbootstrapAngularoncethebrowserloadsthem.Whentheuserinitiallyvisitsarootdomain,suchasfoo.com,theserverisnormallyconfiguredtorespondwithindex.html,whichwillinturnrequestthestaticassetsatrendertime.So,Angularwillwork!

However,incaseswheretheuserinitiallyvisitsanon-rootpath,suchasfoo.com/bar,thebrowserwillsendarequesttotheserveratfoo.com/bar.Ifyouaren'tcarefulwhensettingupyourserver,acommonmistakeyoumaycommitishavingonlytherootfoo.compathreturnindex.html.

InorderforPathLocationStrategytoworkcorrectlyinallcases,youmustconfigureyourwebservertosetupacatchallrouteforalltherequeststhathavepathsintendedforthesingle-pageapplication'srouteintheclient,andtoinvariablyreturnindex.html.Inotherwords,visitingfoo.com,foo.com/bar,orfoo.com/bar/bazasthefirstpageinthebrowserwillallreturnthesamething:index.html.Onceyoudothis,postbootstrapAngularwillexaminethecurrentbrowserpathandrecognizewhichpathitisonandwhatviewneedstobedisplayed.

BuildingstatefulroutebehaviorwithRouterLinkActiveItisoftenthecasewhenbuildingapplicationsthatyouwillwanttobuildfeaturesthatwouldinvolvewhichpagetheapplicationiscurrentlyon.Whenthisisaone-timeinspection,itisn'taproblem,asbothAngularanddefaultbrowserAPIsallowyoutoeasilyinspectthecurrentpage.

ThingsgetabitstickierwhenyouwantthestateofthepagetoreflectthestateoftheURL,forexample,ifyouwanttovisuallyindicatewhichlinkcorrespondstothecurrentpage.Afrom-scratchimplementationofthiswouldrequiresomesortofstatemachinethatwouldknowwhennavigationeventsoccurandwhatandhowtomodifyateachgivenroute.

Fortunately,Angular2givesyousomeexcellenttoolstodothisrightoutofthebox.

Note

Thecode,links,andaliveexampleofthisareallavailableathttp://ngcookbook.herokuapp.com/3308/.


GettingreadyBeginwiththeArrayandanchor-tag-basedimplementationshownintheNavigatingwithrouterLinksrecipe.

YourgoalistouseRouterLinkActivetointroducesomesimplestatefulroutebehavior.

Howtodoit...RouterLinkActiveallowsyoutoconditionallyapplyclasseswhenthecurrentroutematchesthecorrespondingrouterLinkonthesameelement.ProceeddirectlytoaddingitasanattributedirectivetoeachlinkaswellasamatchingCSSclass:



@Component({

selector:'root',

template:`


<a[routerLink]="['']"

[routerLinkActive]="'active-navlink'">Default</a>

<a[routerLink]="['article']"

[routerLinkActive]="'active-navlink'">Article</a>


`,

styles:[`

.active-navlink{

color:red;

text-transform:uppercase;

}

`]

})


Thisisallyouneedforlinkstobecomeactive!YouwillnoticethatAngularwillconditionallyapplytheactive-navlinkclassbasedonthecurrentroute.

However,whentestingthis,youwillnoticethatthe/articleroutemakesboththelinksappearactive.Thisisduetothefactthatbydefault,AngularmarksallrouterLinksthatmatchthecurrentrouteasactive.

Note

Thisbehaviorisusefulincaseswhereyoumaywanttoshowahierarchyoflinksasactiveforexample,atroute/user/123/detail,itcouldmakesensethattheseparatelinks/user,/user/123,and/user/123/detailareallshownasactive.

However,inthecaseofthisrecipe,thisbehaviorisnotusefultoyou,andAngularhasanotherrouterdirective,routerLinkActiveOptions,whichbindstoanoptionsobject.Theexactpropertyinsidetheoptionsobjectisusefulinthiscase;itcontrolswhethertheactivestateshouldonlybeappliedincasesofanexactmatch:




@Component({

selector:'root',

template:`



[routerLinkActive]="'active-navlink'"

[routerLinkActiveOptions]="{exact:true}">Default</a>


[routerLinkActive]="'active-navlink'"

[routerLinkActiveOptions]="{exact:true}">Article</a>


`,

styles:[`

.active-navlink{

color:red;


}

`]

})


Nowyouwillfindthateachlinkwillonlybeactiveatitsrespectiveroute.

Howitworks...TherouterLinkActiveimplementationsubscribestonavigationchangeeventsthatAngularemitsfromtheRouterservice.WhenitseesaNavigationEndevent,itperformsanupdateofalltheattachedHTMLtags,whichincludesaddingandstrippingapplicable"active"CSSclassesthattheelementisboundtoviathedirective.

There'smore...IfyouneedtobindrouterLinkActivetoadynamicvalue,theprecedingsyntaxwillallowyoutodoexactlythat.Forexample,youcanbindtoa

component

memberand

modify

itelsewhere,andAngularwillhandleeverythingforyou.However,ifthisisnotrequired,AngularwillhandlerouterLinkActivewithoutthedatabindingbrackets.Inthiscase,thevalueofthedirectivenolongerneedstobeanAngularexpression,soyoucanremovethenestedquotes.

Thefollowingisbehaviorallyidentical:




@Component({

selector:'root',

template:`



routerLinkActive="active-navlink"

[routerLinkActiveOptions]="{exact:true}">

Default</a>


routerLinkActive="active-navlink"

[routerLinkActiveOptions]="{exact:true}">

Article</a>


`,

styles:[`

.active-navlink{

color:red;


}

`]

})


SeealsoSettingupanapplicationtosupportsimpleroutesshowsyouthebasicsofAngularroutingNavigatingwithrouterLinksdemonstrateshowtonavigatearoundAngularapplicationsBuildingstatefulRouterLinkbehaviorwithRouterLinkActiveshowshowtointegrateapplicationbehaviorwithaURLstateImplementingnestedviewswithrouteparametersandchildroutesgivesanexampleofhowtoconfigureAngularURLstosupportnestinganddatapassingAddingrouteauthenticationcontrolswithrouteguardsdetailstheentireprocessofconfiguringprotectedroutesinyourapplication

ImplementingnestedviewswithrouteparametersandchildroutesAngular2'scomponentrouteroffersyouthenecessaryconceptofchildroutes.Asyoumightexpect,thisbringstheconceptofrecursivelydefinedviewstothetable,whichaffordsyouanincrediblyusefulandelegantwayofbuildingyourapplication.

Note



GettingreadyBeginwiththeArrayandanchor-tag-basedimplementationshowninNavigatingwithrouterLinksrecipe.

Yourgoalistoextendthissimpleapplicationtoinclude/article,whichwillbethelistview,and/article/:id,whichwillbethedetailview.

Howtodoit...First,modifytheroutestructureforthissimpleapplicationbyextendingthe/articlepathtoincludeitssubpaths:/and/:id.Routesaredefinedhierarchically,andeachroutecanhavechildroutesusingthechildrenproperty.

Addingaroutingtargettotheparentcomponent

First,youmustmodifytheexistingArticleComponentsothatitcancontainchildviews.Asyoumightexpect,thechildviewisrenderedinexactlythesamewayasitisdonefromtherootcomponent,usingRouterOutlet:



@Component({

template:`

<h2>Article</h2>


`

})


Thiswon'tdoanythingyet,butaddingRouterOutletdescribestoAngularhowroutecomponenthierarchiesshouldberendered.

Definingnestedchildviews

Inthisrecipe,youwouldliketohavetheparentArticleComponentcontainachildview,eitherArticleListComponentorArticleDetailComponent.Forthesimplicityofthisrecipe,youcanjustdefineyourlistofarticlesasanarrayofintegers.

Definetheskeletonofthesetwocomponentsasfollows:



@Component({

template:`

<h3>ArticleList</h3>

`

})


articleIds:Array<number>=[1,2,3,4,5];

}

[app/article-detail.component.ts]


@Component({

template:`

<h3>ArticleDetail</h3>

<p>Showingarticle{{articleId}}</p>

`

})

exportclassArticleDetailComponent{

articleId:number;

}

Definingthechildroutes

Atthispoint,nothingintheapplicationyetpointstoeitherofthesechildroutes,soyou'llneedtodefinethemnow.

ThechildrenpropertyofarouteshouldjustbeanotherRoute,whichshouldrepresentthenestedroutesthatareappendedtotheparentroute.

Note

Inthisway,youaredefiningasortofrouting"tree,"whereeachrouteentrycanhavemanychildroutesdefinedrecursively.Thiswillbediscussedingreaterdetaillaterinthischapter.

Furthermore,youshouldalsousetheURLparameternotationtodeclare:articleIdasavariableintheroute.Thisallowsyoutopassvaluesinsidetherouteandthenretrievethesevaluesinsidethecomponentthatisrendered.

Addtheseroutedefinitionsnow:

[app/app.module.ts]







import{ArticleListComponent}from'./article-list.component';

import{ArticleDetailComponent}from'./article-detail.component';


{path:'article',component:ArticleComponent,

children:[

{path:'',component:ArticleListComponent},

{path:':articleId',component:ArticleDetailComponent}

]

},


];

@NgModule({

imports:[

BrowserModule,


],

declarations:[

DefaultComponent,

ArticleComponent,

ArticleListComponent,

ArticleDetailComponent,

RootComponent

],

bootstrap:[

RootComponent

]

})


You'llnotethatArticleListComponentiskeyedbyanemptystring.Thisshouldmakesense,aseachoftheseroutesarejoinedtotheirparentroutestocreatethefullroute.Ifyouweretojoineachrouteinthistreewithitsancestralpathtogetthefullroute,theroutedefinitionyou'vejustcreatedwouldhavethefollowingthreeentries:

/article=>ArticleComponent

ArticleListComponent

/article/4=>ArticleComponent

ArticleDetailComponent<articleId=4>

/**=>DefaultComponent

Note

Notethatinthiscase,thenumberofactualroutescorrespondstothenumberofleavesoftheURLtreesincethearticleparentroutewillalsomaptothechildarticle's+''route.Dependingonhowyouconfigureyourroutestructure,theleaf/routeparitywillnotalwaysbethecase.

Definingchildviewlinks

Withtheroutesbeingmappedtothechildcomponents,youcanfleshoutthechildviews.StartingwithArticleList,createarepeatertogeneratethelinkstoeachofthechildviews:



@Component({

template:`


<p*ngFor="letarticleIdofarticleIds">

<a[routerLink]="articleId">

Article{{articleId}}

</a>

</p>

`

})



}

Note

NotethatrouterLinkislinkingtotherelativepathofthedetailview.Sincethecurrentpathforthisviewis/article,arelativerouterLinkof4willnavigatetheapplicationto/article/4uponaclick.

Theselinksshouldwork,butwhenyouclickonthem,theywilltakeyoutothedetailviewthatcannotdisplayarticleIdfromtheroutesinceyouhavenotextractedityet.

InsideArticleDetailComponent,createalinkthatwilltaketheuserbacktothearticle/route.Sinceroutesbehavelikedirectories,youcanjustusearelativepaththatwilltaketheuseruponelevel:



@Component({

template:`



<a[routerLink]="'../'">Backup</a>

`

})


articleId:number;

}

Extractingrouteparameters

AcrucialdifferencebetweenAngular1and2istherelianceonObservableconstructs.Inthecontextofrouting,Angular2wieldsObservablestoencapsulatethatroutingoccursasasequenceofeventsandthatvaluesareproducedatdifferentstatesintheseeventsandwillbereadyeventually.

Moreconcretely,routeparamsinAngular2arenotexposeddirectly,butratherthroughanObservableinsideActivatedRoute.YoucansetObserveronitsparamsObservabletoextracttherouteparamsoncetheyareavailable.

InjecttheActivatedRouteinterfaceandusetheparamsObservabletoextractarticleIdand

assignittotheArticleDetailComponentinstancemember:

[app/article-detail/article-detail.component.ts]


import{ActivatedRoute}from'@angular/router';

@Component({

template:`




`

})


articleId:number;

constructor(privateactivatedRoute_:ActivatedRoute){

activatedRoute_.params

.subscribe(params=>this.articleId=params['articleId']);

}

}

Withthis,youshouldbeabletoseethearticleIdparameterinterpolatedintoArticleDetailComponent.

Howitworks...Inthisapplication,youhavenestedcomponents,AppComponentandArticleComponent,bothofwhichcontainRouterOutlet.Angularisabletotaketheroutinghierarchyyoudefinedandapplyittothecomponenthierarchythatitmapsto.Morespecifically,foreveryRouteyoudefineinyourroutinghierarchy,thereshouldbeanequalnumberofRouterOutletsinwhichtheycanrender.

There'smore...Tosome,itwillfeelstrangetoneedtoextracttherouteparamsfromanObservableinterface.Ifthissolutionfeelsabitclunkytoyou,therearewaysoftidyingitup.

Refactoringwithasyncpipes

RecallthatAngularhastheabilitytointerpolateObservabledatadirectlyintothetemplateasitbecomesready.EspeciallysinceyoushouldonlyeverexpecttheparamObservabletoemitonce,youcanuseittoinsertarticleIdintothetemplatewithoutexplicitlysettinganObserver:




@Component({

template:`


<p>Showingarticle

{{(activatedRoute.params|async).articleId}}</p>


`

})


constructor(activatedRoute:ActivatedRoute){}

}

Eventhoughthisworksperfectlywell,usingaprivatereferencetoaninjectedservicedirectlyintothetemplatemayfeelabitfunnytoyou.AsuperiorstrategyistograbareferencetothepublicObservableinterfaceyouneedandinterpolatethatinstead:




import{ActivatedRoute,Params}from'@angular/router';

@Component({

template:`


<p>Showingarticle{{(params|async).articleId}}</p>


`

})


params:Observable<Params>;


this.params=activatedRoute_.params;

}

SeealsoNavigatingwithrouterLinksdemonstrateshowtonavigatearoundAngularapplicationsNavigatingwiththeRouterserviceusesanAngularservicetonavigatearoundanapplicationBuildingstatefulRouterLinkbehaviorwithRouterLinkActiveshowshowtointegrateapplicationbehaviorwithaURLstateWorkingwithmatrixURLparametersandroutingarraysdemonstratesAngular'sbuilt-inmatrixURLsupportAddingrouteauthenticationcontrolswithrouteguardsdetailstheentireprocessofconfiguringprotectedroutesinyourapplication

WorkingwithmatrixURLparametersandroutingarraysAngular2introducesnativesupportforanawesomefeaturethatseemstobefrequentlyoverlooked:matrixURLparameters.Essentially,theseallowyoutoattachanarbitraryamountofdatainsideaURLtoanyroutinglevelinAngular,andgivingyoutheabilitytoreadthatdataoutasaregularURLparameter.

Note



GettingreadyBeginwiththecodecreatedattheendoftheHowtodoit...sectioninImplementingnestedviewswithrouteparametersandchildroutes.

YourgoalistopassarbitrarydatatoboththeArticleListandArticleDetaillevelsofthisapplicationviaonlytheURL.

Howtodoit...routerLinkarraysareprocessedserially,soanystringthatwillbecomepartoftheURLthatisfollowedbyanobjectwillhavethatobjectconvertedintomatrixURLparameters.Itwillbeeasiertounderstandthisbyexample,sobeginbypassinginsomedummydatatotheArticleListviewfromrouterLink:



@Component({

selector:'root',

template:`


<a[routerLink]="['']">

Default</a>

<a[routerLink]="['article',{listData:'foo'}]">

Article</a>


`

})


Now,ifyouclickonthislink,youwillseeyourbrowsernavigatetothefollowingpathwhilestillsuccessfullyrenderingtheArticleListview:

/article;listData=foo

Toaccessthisdata,simplyextractitfromtheActivatedRouteparams:




@Component({

template:`



<a[routerLink]="[articleId]">


</a>

</p>

`

})





.subscribe(params=>{

console.log('Listparams:');

console.log(window.location.href)

console.log(params);

});

}

}

Whentheviewisloaded,you'llseethefollowing:

Listparams:

/article;listData=foo

Object{listData:"foo"}

Awesome!Dothesameforthedetailview:




@Component({

template:`



<a[routerLink]="[articleId,{detailData:'bar'}]">


</a>

</p>

`

})






console.log('Listparams:');



});

}

}

Addthesameamountofloggingtothedetailview:




@Component({

template:`




`

})


articleId:number;




console.log('Detailparams:');



this.articleId=params['articleId']

});

}

}

Whenyouvisitadetailpage,you'llseethefollowinglogged:

Detailparams:

/article;listData=foo/1;detailData=bar

Object{articleId:"1",detailData:"foo"}

Veryinteresting!NotonlyisAngularabletoassociatedifferentmatrixparameterswithdifferentroutinglevels,butithascombinedboththeexpectedarticleIdparameterandtheunexpecteddetailDataparameterintothesameObservableemission.

Howitworks...AngularisabletoseamlesslyconvertfromaroutingarraycontainingamatrixparamobjecttoaserializedURLcontainingthematrixparams,thenbackintoadeserializedJavaScriptobjectcontainingtheparameterdata.ThisallowsyoutostorearbitrarydatainsideURLsatdifferentlevels,withouthavingtocramitallintoaquerystringattheend.

There'smore...NoticethatwhenyouclickonBackupinthedetailview,thelistDataURLparamispreserved.Angularwilldutifullymaintainthestateasyounavigatethroughouttheapplication,sousingmatrixparameterscanbeaveryeffectivewayofstoringstatefuldatathatsurvivesnavigationorpagereloads.

SeealsoNavigatingwithrouterLinksdemonstrateshowtonavigatearoundAngularapplicationsNavigatingwiththeRouterserviceusesanAngularservicetonavigatearoundanapplicationBuildingstatefulRouterLinkbehaviorwithRouterLinkActiveshowshowtointegrateapplicationbehaviorwithaURLstateImplementingnestedviewswithrouteparametersandchildroutesgivesanexampleofhowtoconfigureAngularURLstosupportnestinganddatapassing

AddingrouteauthenticationcontrolswithrouteguardsThenatureofsingle-pageapplicationswhollycontrollingtheprocessofroutingaffordsthemtheabilitytocontroleachstageoftheprocess.Foryou,thismeansthatyoucaninterceptroutechangesastheyhappenandmakedecisionsaboutwheretheusershouldgo.

Note



GettingreadyInthisrecipe,you'llbuildasimplepseudo-authenticatedapplicationfromscratch.

Yougoalistoprotectusersfromcertainviewswhentheyarenotauthenticated,andatthesametime,implementasensiblelogin/logoutflow.

Howtodoit...Beginbydefiningtwoinitialviewswithroutesinyourapplication.OnewillbeaDefaultview,whichwillbevisibletoeverybody,andonewillbeaProfileview,whichwillbeonlyvisibletoauthenticatedusers:

[app/app.module.ts]






import{ProfileComponent}from'./profile.component';


{path:'profile',component:ProfileComponent},


];

@NgModule({

imports:[

BrowserModule,


],

declarations:[

DefaultComponent,

ProfileComponent,

RootComponent

],

bootstrap:[

RootComponent

]

})


[app/default.component.ts]


@Component({

template:`

<h2>Defaultview!</h2>

`

})

exportclassDefaultComponent{}

[app/profile.component.ts]


@Component({

template:`

<h2>Profileview</h2>

Username:<input>

<button>Update</button>

`

})

exportclassProfileComponent{}

Obviously,thisdoesnotdoanythingyet.

ImplementingtheAuthservice

AsdoneintheObservableschapter,youwillimplementaservicethatwillmaintainthestateentirelywithinaBehaviorSubject.

Note

RecallthataBehaviorSubjectwillrebroadcastitslastemittedvaluewheneveranObserverissubscribedtoit.Thismeansitrequiressettingtheinitialstate,butforanauthenticationservicethisiseasy;itcanjuststartintheunauthenticatedstate.

Forthepurposeofthisrecipe,let'sassumethatausernameofnullmeanstheuserisnotauthenticatedandanyotherstringvaluemeanstheyareauthenticated:

[app/auth.service.ts]




@Injectable()


privateauthSubject_:BehaviorSubject<any>=

newBehaviorSubject(null);

usernameEmitter:Observable<string>;

constructor(){

this.usernameEmitter=this.authSubject_.asObservable();

this.logout();

}

login(username:string):void{

this.setAuthState_(username);

}

logout():void{

this.setAuthState_(null);

}

privatesetAuthState_(username:string):void{

this.authSubject_.next(username);

}

}

Notethatnowherearewestoringtheusernameasastring.ThestateoftheauthenticationlivesentirelywithinBehaviorSubject.

Wiringuptheprofileview

Next,makethisserviceavailabletotheentireapplicationandwireuptheprofileview:

[app/app.module.ts]







import{AuthService}from'./auth.service';


{path:'profile',component:ProfileComponent},


];

@NgModule({

imports:[

BrowserModule,


],

declarations:[

DefaultComponent,

ProfileComponent,

RootComponent

],

providers:[

AuthService

],

bootstrap:[

RootComponent

]

})


[app/profile.component.ts]




@Component({

template:`

<h2>Profileview</h2>

Username:<input#unvalue="{{username|async}}">

<button(click)=update(un.value)>Update</button>

`

})

exportclassProfileComponent{

username:Observable<string>;


this.username=authService_.usernameEmitter;

}

update(username:string):void{

this.authService_.login(username);

}

}

Tip

It'sveryhandytousetheasyncpipewheninterpolatingvalues.Recallthatwhenyouinvokesubscribe()onaserviceObservablefrominsideaninstantiatedviewcomponent,youmustinvokeunsubscribe()ontheSubscriptionwhenthecomponentisdestroyed;otherwise,yourapplicationwillhavealeakedlistener.MakingtheObservableavailabletotheviewsavesyouthistrouble!

Withtheprofileviewwiredup,addlinksandinterpolatetheusernameintotherootappviewinanavbar,togiveyourselftheabilitytonavigatearound.Youdon'thavetorevisitthefile;justaddallthelinksyou'llneedinthisrecipenow:






@Component({

selector:'root',

template:`

<h3*ngIf="!!(username|async)">

Hello,{{username|async}}.

</h3>

<a[routerLink]="['']">Default</a>

<a[routerLink]="['profile']">Profile</a>

<a*ngIf="!!(username|async)"

[routerLink]="['login']">Login</a>

<a*ngIf="!!(username|async)"

[routerLink]="['logout']">Logout</a>


`

})


username:Observable<string>;


this.username=authService_.usernameEmitter;

}

}

Tip

Forconsistency,hereyouareusingtheasyncpipetomakethecomponentdefinitionsimpler.However,sinceyouhavefourinstancesinthetemplatereferencingthesameObservable,itmightbebetterdowntheroadtoinsteadsetonesubscribertoObservable,bindittoastringmemberinRootComponent,andinterpolatethisinstead.Angular'sdatabindingmakesthiseasyforyou,butyouwouldstillneedtoderegisterthesubscriberwhenthisisdestroyed.However,sinceitistheapplication'srootcomponent,youshouldn'treallyexpectthistohappen.

Restrictingrouteaccesswithrouteguards

Sofarsogood,butyouwillnoticethattheprofileviewisallowingtheusertoeffectivelyloginwilly-nilly.Youwouldinsteadliketorestrictaccesstothisviewandonlyallowtheusertovisititwhentheyarealreadyauthenticated.

Angulargivesyoutheabilitytoexecutecode,inspecttheroute,andredirectitasnecessarybeforethenavigationoccursusingaRouteGuard.

Note

Guardisabitofamisleadingtermhere.YoushouldthinkofthisfeatureasarouteshimthatletsyouaddlogicthatexecutesbeforeAngularactuallygoestothenewroute.Itcanindeed"Guard"aroutefromanunauthenticateduser,butitcanalsojustaseasilyconditionallyredirect,savethecurrentURL,orperformothertasks.

SincetheRouteGuardneedstohavethe@Injectabledecorator,itmakesgoodsensetotreatitasaservicetype.

StartoffwiththeskeletonAuthGuardServicedefinedinsideanewfileforrouteguards:

[app/route-guards.service.ts]


import{CanActivate}from'@angular/router';

@Injectable()

exportclassAuthGuardServiceimplementsCanActivate{

constructor(){}

canActivate(){

//Thismethodisinvokedduringroutechangesifthis

//classislistedintheRoutes

}

}

Beforehavingthisdoanything,importthemoduleandaddittoRoutes:

[app/app.module.ts]








import{AuthGuardService}from'./route-guards.service';


{

path:'profile',

component:ProfileComponent,

canActivate:[AuthGuardService]

},

{

path:'**',

component:DefaultComponent

}

];

@NgModule({

imports:[

BrowserModule,


],

declarations:[

DefaultComponent,

ProfileComponent,

RootComponent

],

providers:[

AuthService,

AuthGuardService

],

bootstrap:[

RootComponent

]

})


Now,eachtimetheapplicationmatchesaroutetoaprofileandtriestonavigatethere,thecanActivatemethoddefinedinsideAuthGuardServicewillbecalled.Thereturnvalueoftruemeansthenavigationcanoccur;thereturnvalueoffalsemeansthenavigationiscancelled.

Tip

canActivatecaneitherreturnabooleanoranObservable<boolean>.Beaware,shouldyoureturnObservable,theapplicationwilldutifullywaitfortheObservabletoemitavalueandcompleteitbeforenavigating.

Sincetheapplication'sauthenticationstatelivesinsideBehaviorSubject,allthismethodneedstodoissubscribe,checktheusername,andnavigateifitisnotnull.ItsuitsthistoreturnObservable<boolean>:



import{CanActivate,Router}from'@angular/router';



@Injectable()


constructor(privateauthService_:AuthService,

privaterouter_:Router){}

canActivate():Observable<boolean>{

returnthis.authService_.usernameEmitter.map(username=>{

if(!username){

this.router_.navigate(['login']);

}else{

returntrue;

}

});

}

}

Onceyouimplementthis,youwillnoticethatthenavigationwillneveroccur,eventhoughtheserviceisemittingtheusernamecorrectly.ThisisbecausetherecipientofthereturnvalueofcanActivateisn'tjustwaitingforanObservableemission;itiswaitingfortheObservabletocomplete.SinceyoujustwanttopeekattheusernamevalueinsideBehaviorSubject,youcanjustreturnanewObservablethatreturnsonevalueandtheniscompletedusingtake():






import'rxjs/add/operator/take';

@Injectable()




canActivate():Observable<Boolean>{


if(!username){


}else{

returntrue;

}

}).take(1);

}

}

Superb!However,thisapplicationstilllacksamethodtoformallyloginandlogout.

Addingloginbehavior

Sincetheloginpagewillneeditsownview,itshouldgetitsownrouteandcomponent.Oncetheuserlogsin,thereisnoneedtokeepthemontheloginpage,soyouwanttoredirectthemtothedefaultviewoncetheyaredone.

First,createthelogincomponentanditscorrespondingview:





@Component({

template:`

<h2>Loginview</h2>

<input#un>

<button(click)="login(un.value)">Login</button>

`

})




login(newUsername:string):void{

this.authService_.login(newUsername);

this.authService_.usernameEmitter

.subscribe(username=>{

if(!!username){

this.router_.navigate(['']);

}

});

}

}

[app/app.module.ts]









import{AuthGuardService}from'./route-guards.service';


{

path:'login',

component:LoginComponent

},

{

path:'profile',



},

{

path:'**',


}

];

@NgModule({

imports:[

BrowserModule,


],

declarations:[

LoginComponent,

DefaultComponent,

ProfileComponent,

RootComponent

],

providers:[

AuthService,

AuthGuardService

],

bootstrap:[

RootComponent

]

})


Youshouldnowbeabletologin.Thisisallwellandgood,butyouwillnoticethatwiththisimplemented,updatingtheusernameintheprofileviewwillnavigatetothedefaultview,exhibitingthesamebehaviordefinedinthelogincomponent.ThisisbecausethesubscriberisstilllisteningtoAuthServiceObservable.YouneedtoaddinanOnDestroymethodtocorrectlyteardowntheloginview:


import{Component,ngOnDestroy}from'@angular/core';




@Component({

template:`

<h2>Loginview</h2>

<input#un>

<button(click)="login(un.value)">Login</button>

`

})

exportclassLoginComponentimplementsOnDestroy{

privateusernameSubscription_:Subscription;



login(newUsername:string):void{

this.authService_.login(newUsername);

this.usernameSubscription_=this.authService_

.usernameEmitter

.subscribe(username=>{

if(!!username){


}

});

}

ngOnDestroy(){

//Onlyinvokeunsubscribe()ifthisexists

this.usernameSubscription_&&

this.usernameSubscription_.unsubscribe();

}

}

Addingthelogoutbehavior

Finally,youwanttoaddawayforuserstologout.Thiscanbeaccomplishedinanumberofways,butagoodimplementationwillbeabletodelegatethelogoutbehaviortoitsassociatedmethodswithoutintroducingtoomuchboilerplatecode.

Ideally,youwouldlikefortheapplicationtojustbeabletonavigatetothelogoutrouteandletAngularhandletherest.This,too,canbeaccomplishedwithcanActivate.First,defineanewRouteGuard:






import'rxjs/add/operator/take';

@Injectable()




canActivate():Observable<boolean>{


if(!username){


}else{

returntrue;

}

}).take(1);

}

}

@Injectable()

exportclassLogoutGuardServiceimplementsCanActivate{



canActivate():boolean{



returntrue;

}

}

Thisbehaviorshouldbeprettyself-explanatory.

Tip

YourcanActivatemethodmustmatchthesignaturedefinedintheCanActivateinterface,soeventhoughitwillalwaysnavigatetoanewview,youshouldaddareturnvaluetopleasethecompilerandtohandleanycaseswheretheprecedingcodeshouldfallthrough.

Next,addthelogoutcomponentandtheroute.Thelogoutcomponentwillneverberendered,buttheroutedefinitionrequiresthatitismappedtoavalidcomponent.SoLogoutComponentwillconsistofadummyclass:

[app/logout.component.ts}


@Component({

template:''

})

exportclassLogoutComponent{}

[app/app.module.ts]








import{LogoutComponent}from'./logout.component';


import{AuthGuardService,LogoutGuardService}

from'./route-guards.service';


{

path:'login',

component:LoginComponent

},

{

path:'logout',

component:LogoutComponent,

canActivate:[LogoutGuardService]

},

{

path:'profile',



},

{

path:'**',


}

];

@NgModule({

imports:[

BrowserModule,


],

declarations:[

LoginComponent,

LogoutComponent,

DefaultComponent,

ProfileComponent,

RootComponent

],

providers:[

AuthService,

AuthGuardService,

LogoutGuardService

],

bootstrap:[

RootComponent

]

})


Withthis,youshouldhaveafullyfunctionallogin/logoutbehaviorprocess.

Howitworks...ThecoreofthisimplementationisbuiltaroundObservablesandRouteGuards.ObservablesallowyourAuthServicemoduletomaintainthestateandexposeitsimultaneouslythroughBehaviorSubject,andRouteGuardsallowyoutoconditionallynavigateandredirectatyourapplication'sdiscretion.

There'smore...Applicationsecurityisabroadandinvolvedsubject.Therecipeshownhereinvolveshowtosmoothlymoveyouruseraroundtheapplication,butitisbynomeansarigoroussecuritymodel.

Theactualauthentication

Youshouldalwaysassumetheclientcanmanipulateitsownexecutionenvironment.Inthisexample,evenifyouprotectthelogin/logoutmethodsonAuthServiceaswellasyoucan,itwillbeeasyfortheusertogainaccesstothesemethodsandauthenticatethemselves.

Userinterfaces,whichAngularapplicationssquarelyfallinto,arenotmeanttobesecure.Securityresponsibilitiesfallontheserversideoftheclient/servermodelsincetheuserdoesnotcontrolthatexecutionenvironment.Inanactualapplication,thelogin()methodherewouldmakeanetworkrequestgetsomesortofatokenfromtheserver.Twoverypopularimplementations,JSONWebTokensandCookieauth,dothisindifferentways,buttheyareessentiallyvariationsofthesametheme.Angularorthebrowserwillstoreandsendthesetokens,butultimatelytheservershouldactasthegatekeeperofsecureinformation.

Securedataandviews

Anysecureinformationyoumightsendtotheclientshouldbebehindserver-basedauthentication.Formanydevelopers,thisisanobviousfact,especiallywhendealingwithanAPI.However,Angularalsorequeststemplatesandstaticfilesfromtheserver,andsomeoftheseyoumightnotwanttoservetothewrongpeople.Inthiscase,youwillneedtoconfigureyourservertoauthenticaterequestsforthesestaticfilesbeforeyouservethemtotheclient.

SeealsoNavigatingwiththeRouterserviceusesanAngularservicetonavigatearoundanapplicationBuildingstatefulRouterLinkbehaviorwithRouterLinkActiveshowshowtointegrateapplicationbehaviorwithaURLstateImplementingnestedviewswithrouteparametersandchildroutesgivesanexampleofhowtoconfigureAngularURLstosupportnestinganddatapassingWorkingwithmatrixURLparametersandroutingarraysdemonstratesAngular'sbuilt-inmatrixURLsupport

Chapter7.Services,DependencyInjection,andNgModuleThischapterwillcoverthefollowingrecipes:

InjectingasimpleserviceintoacomponentControllingserviceinstancecreationandinjectionwithNgModuleServiceinjectionaliasingwithuseClassanduseExistingInjectingavalueasaservicewithuseValueandOpaqueTokensBuildingaprovider-configuredservicewithuseFactory

IntroductionAngular1gaveyouahodgepodgeofdifferentservicetypes.Manyofthemhadagreatdealofoverlap.Manyofthemwereconfusing.Andallofthemweresingletons.

Angular2hastotallythrownawaythisconcept.Initsplace,thereisashinynewdependencyinjectionsystemthatisfarmoreextensibleandsensiblethanitspredecessor.Itallowsyoutohaveatomicandnon-atomicservicetypes,aliasing,factories,andallkindsofincrediblyusefultoolsforuseinyourapplication.

Ifyouarelookingtouseservicesmuchinthesamewayasearlier,youwillfindthatyourunderstandingofservicetypeswilleasilycarryovertothenewsystem.Butfordeveloperswhowantmoreoutoftheirapplications,thenewworldofdependencyinjectionisincrediblypowerfulandobviouslybuiltforapplicationsthatcanscale.

InjectingasimpleserviceintoacomponentThemostcommonusecasewillbeforacomponenttodirectlyinjectaserviceintoitself.Althoughtherhythmsofdefiningservicetypesandusingdependencyinjectionremainmostlythesame,it'simportanttogetagoodholdofthefundamentalsofAngular2'sdependencyinjectionschema,asitdiffersinseveralimportantways.

Note

Thecode,links,andaliveexampleofthisareavailableathttp://ngcookbook.herokuapp.com/4263.


GettingreadySupposeyouhadthefollowingskeletonapplication:



@Component({

selector:'root',

template:`

<h1>rootcomponent!</h1>

<button(click)="fillArticle()">Showarticle</button>

<h2>{{title}}</h2>

`

})


title:string;

constructor(){}

fillArticle(){}

}

Yourobjectiveistoimplementaservicethatcanbeinjectedintothiscomponentandreturnanarticletitletofillthetemplate.

Howtodoit...Asyoumightexpect,servicesinAngular2arerepresentedasclasses.Similartocomponents,servicesaredesignatedassuchwithan@Injectabledecorator.Createthisserviceinitsownfile:



@Injectable()


privatetitle_:string=`

CFOYodelsQuarterlyEarningsCall,StockSkyrockets

`

}

Thisservicehasaprivatetitlethatyouneedtotransfertothecomponent,butfirstyoumustmaketheserviceitselfavailabletothecomponent.Thiscanbedonebyimportingtheservice,thenlistingitintheproviderspropertyoftheapplicationmodule:

[app/app.module.ts]





@NgModule({

imports:[

BrowserModule

],

declarations:[

RootComponent

],

providers:[

ArticleService

],

bootstrap:[

RootComponent

]

})


Nowthattheservicecanbeprovided,injectitintothecomponent:




@Component({

selector:'root',

template:`



<h2>{{title}}</h2>

`

})


title:string;

constructor(privatearticleService_:ArticleService){}

fillArticle(){}

}

ThisnewcodewillcreateanewinstanceofArticleServicewhenRootComponentisinstantiated,andtheninjectitintotheconstructor.Anythinginjectedintoacomponentwillbeavailableasacomponentinstancemember,whichyoucanusetoconnectaservicemethodtoacomponentmethod:



@Injectable()


privatetitle_:string=`

CFOYodelsQuarterlyEarningsCall,StockSkyrockets

`;

getTitle(){

returnthis.title_;

}

}




@Component({

selector:'root',

template:`



<h2>{{title}}</h2>

`

})


title:string;


fillArticle():void{

this.title=this.articleService_.getTitle();

}

}

Howitworks...Withoutthedecorator,theserviceyouhavejustbuiltisratherplainincomposition.Withthe@Injectable()decoration,theclassisdesignatedtotheAngularframeworkasonethatwillbeinjectedelsewhere.

Note

Designationasaninjectablehasanumberofconsiderationsthatareimportantlydistinctfromjustbeingpassedinparametrically.Whenistheinjectedclassinstantiated?Howisitlinkedtothecomponentinstance?Howareglobalandlocalinstancescontrolled?Thesearealldiscussedinthemoreadvancedrecipesinthischapter.

Designationasaninjectableserviceisonlyonepieceofthepuzzle.Thecomponentneedstobeinformedoftheexistenceoftheservice.Youmustfirstimporttheserviceclassintothecomponentmodule,butthisaloneisnotsufficient.Recallthatthesyntaxusedtoinjectaservicewassimplyawaytolistitasaconstructorparameter.Behindthescenes,Angularissmartenoughtorecognizethatthesecomponentargumentsaretobeinjected,butitrequiresthefinalpiecetoconnecttheimportedmoduletoitsplaceasaninjectedresource.

ThisfinalpiecetakestheformoftheproviderspropertyoftheNgModuledefinition.Forthepurposeofthisrecipe,itisn'timportantthatyouknowthedetailsoftheproperty.Inshort,thisarraydesignatesthearticleServiceconstructorparameterasaninjectableandidentifiesthatArticleServiceshouldbeinjectedintotheconstructor.

There'smore...It'simportanttoacknowledgeherehowtheTypeScriptdecoratorshelpthedependencyinjectionsetup.Decoratorsdonotmodifyaninstanceofaclass;rather,theymodifytheclassdefinition.TheNgModulecontainingtheproviderslistwillbeinitializedpriortoanyinstanceoftheactualcomponentbeinginstantiated.Thus,Angularwillbeawareofalltheservicesthatyoumightwanttoinjectintotheconstructor.

SeealsoControllingserviceinstancecreationandinjectionwithNgModulegivesabroadoverviewofhowAngular2architectsproviderhierarchiesusingmodules

ControllingserviceinstancecreationandinjectionwithNgModuleInastarkdeparturefromAngular1.x,Angular2featuresahierarchicalinjectionscheme.Thishasasubstantialnumberofimplications,andoneofthemoreprominentoneistheabilitytocontrolwhen,andhowmany,servicesarecreated.

Note



GettingreadySupposeyoubeginwiththefollowingsimpleapplication:



@Component({

selector:'root',

template:`


<article></article>

<article></article>

`

})




@Component({

selector:'article',

template:`

<p>Articlecomponent!</p>

`

})




@Injectable()


constructor(){

console.log('ArticleServiceconstructor!');

}

}

[app/app.module.ts]




import{ArticleComponent}from'./article.component;

@NgModule({

imports:[

BrowserModule,

],

declarations:[

RootComponent,

ArticleComponent

],

bootstrap:[

RootComponent

]

})


YourobjectiveistoinjectasingleinstanceofArticleServiceintothetwochildcomponents.Inthisrecipe,console.loginsidetheArticleServiceconstructorallowsyoutoseewhenoneisinstantiated.

Howtodoit...BeginbyimportingtheserviceintoAppModule,thenprovidingitwiththefollowing:

[app/app.module.ts]




import{ArticleComponent}from'./article.component;

import{ArticleService}from'./article.service;

@NgModule({

imports:[

BrowserModule,

],

declarations:[

RootComponent,

ArticleComponent

],

providers:[

ArticleService

]

bootstrap:[

RootComponent

]

})


SinceArticleServiceisprovidedinthesamemodulewhereArticleComponentisdeclared,youarenowabletoinjectArticleServiceintothechildArticleComponentinstances:

[app/article/article.component.ts]



@Component({

selector:'article',

template:`


`

})



}

Withthis,youwillfindthatthesameserviceinstanceisinjectedintoboththechildcomponentsastheArticleServiceconstructor,namelyconsole.log,isonlyexecutedonce.

Splittinguptherootmodule

Astheapplicationgrows,itwillmakelessandlesssensetocrameverythingintothesametop-levelmodule.Instead,itwouldbeidealforyoutobreakapartmodulesintochunksthatmakesense.Inthecaseofthisrecipe,itwouldbepreferabletoprovideArticleServicetotheapplicationpiecesthatareactuallygoingtoinjectit.

DefineanewArticleModuleandmovetherelevantmoduleimportsintothatfileinstead:

[app/article.module.ts]




@NgModule({

declarations:[

ArticleComponent

],

providers:[

ArticleService

],

bootstrap:[

ArticleComponent

]

})

exportclassArticleModule{}

Then,importthisentiremoduleintoAppModuleinstead:

[app/app.module.ts]




import{ArticleModule}from'./article.module';

@NgModule({

imports:[

BrowserModule,

ArticleModule

],

declarations:[

RootComponent

],

bootstrap:[

RootComponent

]

})


Ifyoustophere,you'llfindthattherearenoerrors,butAppModuleisn'tabletorenderArticleComponent.ThisisbecauseAngularmodules,likeothermodulesystems,needtoexplicitlydefinewhatisbeingexportedtoothermodules:





@NgModule({

declarations:[

ArticleComponent

],

providers:[

ArticleService

],

bootstrap:[

ArticleComponent

],

exports:[

ArticleComponent

]

})


Withthis,youwillstillseethatArticleServiceisinstantiatedonce.

Howitworks...Angular2'sdependencyinjectiontakesadvantageofitshierarchystructurewhenprovidingandinjectingservices.Fromwhereaserviceisinjected,Angularwillinstantiateaservicewhereveritisprovided.Insideamoduledefinition,thiswillonlyeverhappenonce.

Inthiscase,youprovidedArticleServicetobothAppModuleandArticleModule.Eventhoughtheserviceisinjectedtwice(onceforeachArticleComponent),Angularusestheprovidersdeclarationtodecidewhentocreatetheservice.

There'smore...Atthispoint,acuriousdevelopershouldhavelotsofquestionsabouthowexactlythisinjectionschemabehaves.Therearenumerousdifferentconfigurationflavorsthatcanbeusefultothedeveloper,andtheseconfigurationsonlyrequireaminorcodeadjustmentfromtheprecedingresult.

Injectingdifferentserviceinstancesintodifferentcomponents

Asyoumightanticipatefromtheprecedingexplanation,youcanreconfigurethisapplicationtoinjectadifferentArticleServiceinstanceintoeachchild,twointotal.ThiscanbedonebymigratingtheprovidersdeclarationoutofthemoduledefinitionandintotheArticleComponentdefinition:




@NgModule({

declarations:[

ArticleComponent

],

bootstrap:[

ArticleComponent

],

exports:[

ArticleComponent

]

})





@Component({

selector:'article',

template:`


`,

providers:[

ArticleService

]

})



}

Youcanverifythattwoinstancesarebeingcreatedbyobservingthetwoconsole.logstatements

calledfromtheArticleServiceconstructor.

Serviceinstantiation

Thelocationoftheprovidersalsomeansthatserviceinstanceinstantiationisboundtothelifetimeofthecomponent.Forthisapplication,thismeansthatwheneveracomponentiscreated,ifaserviceisprovidedinsidethatcomponentdefinition,anewserviceinstancewillbecreated.

Forexample,ifyouweretotoggletheexistenceofachildcomponentwithArticleServiceprovidedinsideit,itwillcreateanewArticleServiceeverytimeArticleComponentisconstructed:



@Component({

selector:'root',

template:`


<button(click)="toggle=!toggle">Toggle</button>

<article></article>

<article*ngIf="toggle"></article>

`

})


YoucanverifythatnewinstancesarebeingcreatedeachtimengIfevaluatestotruebyobservingadditionalconsole.logstatementscalledfromtheArticleServiceconstructor.

SeealsoInjectingasimpleserviceintoacomponentwalksyouthroughthebasicsofAngular2'sdependencyinjectionschemaServiceinjectionaliasingwithuseClassanduseExistingdemonstrateshowtointerceptdependencyinjectionproviderrequests

ServiceinjectionaliasingwithuseClassanduseExistingAsyourapplicationbecomesmorecomplex,youmaycometoasituationwhereyouwouldliketouseyourservicesinapolymorphicstyle.Morespecifically,someplacesinyourapplicationmaywanttorequestServiceA,butaconfigurationsomewhereinyourapplicationwillactuallygiveitServiceB.Thisrecipewilldemonstrateonewayinwhichthiscanbeuseful,butthisbehaviorallowsyourapplicationtobemoreextensibleinmultipleways.

Note



GettingreadySupposeyoubeginwiththefollowingskeletonapplication.

Dualservices

Youbeginwithtwoservices,ArticleServiceandEditorArticleService,andtheirsharedinterface,ArticleSourceInterface.EditorArticleServiceinheritsfromArticleService:

[app/article-source.interface.ts]

exportinterfaceArticleSourceInterface{

getArticle():Article

}

exportinterfaceArticle{

title:string,

body:string,

//?denotesanoptionalproperty

notes?:string

}



import{Article,ArticleSourceInterface}

from'./article-source.interface';

@Injectable()

exportclassArticleServiceimplementsArticleSourceInterface{

privatetitle_:string=

"ResearchersDetermineHamSandwichNotTuringComplete";

privatebody_:string=

"Computersciencecommunityremainsskeptical";

getArticle():Article{

return{

title:this.title_,

body:this.body_

};

}

}

[app/editor-article.service.ts]



import{Article,ArticleSourceInterface}

from'./article-source.interface';

@Injectable()

exportclassEditorArticleServiceextendsArticleService

implementsArticleSourceInterface{

privatenotes_:string="Swingandamiss!";

constructor(){

super();

}


//Combineobjectsandreturnthejoinedobject

returnObject.assign(

{},

super.getArticle(),

{

notes:this.notes_

});

}

}

Aunifiedcomponent

Yourobjectiveistobeabletousethefollowingcomponentsothatboththeseservicescanbeinjectedintothefollowingcomponent:




import{Article}from'./article-source.interface';

@Component({

selector:'article',

template:`


<p>{{article.body}}</p>

<p*ngIf="article.notes">

<i>Notes:{{article.notes}}</i>

</p>

`

})


article:Article;

constructor(privatearticleService_:ArticleService){

this.article=articleService.getArticle();

}

}

Howtodoit...Whenlistingproviders,Angular2allowsyoutodeclareanaliasedreferencethatspecifieswhatserviceshouldactuallybeprovidedwhenoneofthecertaintypesisrequested.SinceAngular2injectionwillfollowthecomponenttreeupwardstofindtheprovider,onewaytodeclarethisaliasisbywrappingthecomponentwithaparentcomponentthatwillspecifythisalias:

[app/default-view.component.ts]



@Component({

selector:'default-view',

template:`

<h3>Defaultview</h3>


`,

providers:[ArticleService]

})

exportclassDefaultViewComponent{}

[app/editor-view.component.ts]



import{EditorArticleService}from'./editor-article.service';

@Component({

selector:'editor-view',

template:`

<h3>Editorview</h3>


`,

providers:[

{provide:ArticleService,useClass:EditorArticleService}

]

})

exportclassEditorViewComponent{}

Note

Notethatboththeseclassesareactingaspassthroughcomponents.Otherthanaddingaheader(whichismerelyforlearningthepurposeofinstructioninthisrecipe),theseclassesareonlyspecifyingaproviderandareunconcernedwiththeircontent.

Withthewrapperclassesdefined,youcannowaddthemtotheapplicationmodule,thenusethemtocreatetwoinstancesofArticleComponent:

[app/app.module.ts]





import{DefaultViewComponent}from'./default-view.component';

import{EditorViewComponent}from'./editor-view.component';




@NgModule({

imports:[

BrowserModule

],

declarations:[

RootComponent,

ArticleComponent,

DefaultViewComponent,

EditorViewComponent

],

bootstrap:[

RootComponent

]

})




@Component({

selector:'root',

template:`

<default-view>

<article></article>

</default-view>

<hr/>

<editor-view>

<article></article>

</editor-view>

`

})


Withthis,youshouldnowseethattheeditorversionofArticleComponentgetsthenotes,butthedefaultversiondoesnot.

Howitworks...InAngular1,theservicetypethatwassupposedtobeinjectedwasidentifiedfromafunctionparameterbydoingadirectmatchoftheparametersymbol.function(Article)wouldinjecttheArticleservice,function(User)theUserservice,andsoon.Thisledtonastiness,suchastheminification-proofingofconstructorsbyprovidinganarrayofstringstomatchagainst['Article',function(Article){}].

Thisisnolongerthecase.Whenaproviderisregistered,theuseClassoptionutilizesthetwo-partdependencyinjectionmatchingschemeinAngular2.Thefirstpartistheprovidertoken,whichistheparametertypeoftheservicebeinginjected.Inthiscase,privatearticleService_:ArticleServiceusestheArticleServicetokentorequestthataninstancebeinjected.Angular2takesthisandmatchesthistokenagainstthedeclaredprovidersinthecomponenthierarchy.Whenatokenismatched,Angular2willusethesecondpart,theprovideritself,toinjectaninstanceoftheservice.

Inreality,providers:[ArticleService]isashorthandforproviders:[{provide:ArticleService,useClass:ArticleService}].Theshorthandisusefulsinceyouwillalmostalwaysberequestingtheserviceclassthatwouldmatchtheinjectedclass.However,inthisrecipe,youareconfiguringAngular2torecognizeanArticleServicetokenandsousetheEditorArticleServiceprovider.

There'smore...AnattentivedeveloperwillhaverealizedbythispointthattheutilityofuseClassislimitedinthesensethatitdoesnotallowyoutoindependentlycontrolwheretheactualserviceisprovided.Inotherwords,theplacewhereyouintercepttheproviderdefinitionwithuseClassisalsotheplacewherethereplacementclasswillbeprovided.

Inthisexample,useClassissuitablesinceyouareperfectlyhappytoprovideEditorArticleServiceinthesameplacewhereyouarespecifyingthatitshouldbeusedtoreplaceArticleService.However,itisnotdifficulttoimagineascenarioinwhichyouwouldliketospecifythereplacementservicetypebuthaveitinjectedhigherupinthecomponenttree.This,afterall,wouldallowyoutoreuseinstancesofaserviceinsteadofhavingtocreateanewoneforeachuseClassdeclaration.

Forthispurpose,youcanuseuseExisting.Itrequiresyoutoexplicitlyprovidetheservicetypeseparately,butitwillreusetheprovidedinstanceinsteadofcreatinganewone.Fortheapplicationyoujustcreated,youcannowreconfigureitwithuseExisting,andprovideboththeservicesattheRootComponentlevel.

Todemonstratethatyourreasoningabouttheservicebehavioriscorrect,doublethenumberofArticlecomponents,andaddalogstatementtotheconstructorofArticleServicetoensureyouareonlycreatingoneofeachservice:



@Component({

selector:'root',

template:`

<default-view>

<article></article>

</default-view>

<editor-view>

<article></article>

</editor-view>

<default-view>

<article></article>

</default-view>

<editor-view>

<article></article>

</editor-view>

`

})




import{Article,ArticleSourceInterface}from'./article-source.interface';

@Injectable()

exportclassArticleServiceimplementsArticleSourceInterface{


"ResearchersDetermineHamSandwichNotTuringComplete";


"Computersciencecommunityremainsskeptical";

constructor(){

console.log('InstantiatedArticleService!');

}


return{

title:this.title_,

body:this.body_

};

}

}

[app/editor-view.component.ts]




@Component({

selector:'editor-view',

template:`

<h3>Editorview</h3>


`,

providers:[

{provide:ArticleService,useExisting:EditorArticleService}

]

})

exportclassEditorViewComponent{}

[app/default-view.component.ts]



@Component({

selector:'default-view',

template:`

<h3>Defaultview</h3>


`

//providersremoved

})

exportclassDefaultViewComponent{}

Inthisconfiguration,withuseClass,youwillseethatoneinstanceofArticleServiceandtwoinstancesofEditorArticleServicearecreated.WhenreplacedwithuseExisting,youwillfindthatonlyoneinstanceofeachiscreated.

Thus,inthisreconfiguredversionoftherecipe,yourapplicationisdoingthefollowing:

AttheRootComponentlevel,itisprovidingEditorArticleServiceAttheEditorViewComponentlevel,itisredirectingArticleServiceinjectiontokenstoEditorArticleService

AttheArticleComponentlevel,itisinjectingArticleServiceusingtheArticleServicetoken

Refactoringwithdirectiveproviders

Ifthisimplementationseemsclunkyandverbosetoyou,youarecertainlyontosomething.Theintermediatecomponentsareperformingtheirjobsquitewell,butaren'treallydoinganythingotherthanshimminginanintermediateprovider'sdeclaration.Insteadofwrappinginacomponent,youcanmigratetheprovider'sstatementintoadirectiveanddoawaywithboththeviewcomponents:






@Component({

selector:'root',

template:`

<article></article>

<articleeditor-view></article>

<article></article>


`

})


[app/editor-view.directive.ts]




@Directive({

selector:'[editor-view]',

providers:[

{provide:ArticleService,useExisting:EditorArticleService}

]

})

exportclassEditorViewDirective{}

[app/app.module.ts]





import{DefaultViewComponent}from'./default-view.component';

import{EditorViewDirective}from'./editor-view.directive';




@NgModule({

imports:[

BrowserModule

],

declarations:[

RootComponent,

ArticleComponent,

DefaultViewComponent,

EditorViewDirective

],

providers:[

ArticleService,

EditorArticleService

],

bootstrap:[

RootComponent

]

})


Yourapplicationshouldworkjustthesame!

SeealsoInjectingasimpleserviceintoacomponentwalksyouthroughthebasicsofAngular2'sdependencyinjectionschemaControllingserviceinstancecreationandinjectionwithNgModulegivesabroadoverviewofhowAngular2architectsproviderhierarchiesusingmodulesInjectingavalueasaservicewithuseValueandOpaqueTokensshowshowyoucanusedependency-injectedtokenstoinjectgenericobjectsBuildingaprovider-configuredservicewithuseFactorydetailstheprocessofsettingupaservicefactorytocreateconfigurableservicedefinitions

InjectingavalueasaservicewithuseValueandOpaqueTokensInAngular1,therewasabroadselectionofservicetypesyoucoulduseinyourapplication.Asubsetofthesetypesallowedyoutoinjectastaticvalueinsteadofaserviceinstance,andthisusefulabilityiscontinuedinAngular2.

Note



GettingreadyBeginwiththefollowingsimpleapplication:

[app/app.module.ts]





@NgModule({

imports:[

BrowserModule

],

declarations:[

RootComponent,

ArticleComponent

],

bootstrap:[

RootComponent

]

})




@Component({

selector:'root',

template:`

<article></article>

`

})




@Component({

selector:'article',

template:`

<imgsrc="{{logoUrl}}">

<h2>FoolandHisMoneyReunitedatLast</h2>

<p>Author:JakeHsu</p>

`

})


Howtodoit...Althoughaformalserviceclassdeclarationand@Injectabledecoratordesignationisnolongernecessaryforinjectingavalue,token/providermappingisstillneeded.Sincethereisnolongeraclassavailablethatcanbeusedtotypetheinjectable,somethingelsewillhavetoactasitsreplacement.

Angular2solvesthisproblemwithOpaqueToken.Thismoduleallowsyoutocreateaclasslesstokenthatcanbeusedtopairtheinjectedvaluewiththeconstructorargument.ThiscanbeusedalongsidetheuseValueprovideoption,whichsimplydirectlyprovideswhateveritscontentsareasinjectedvalues.

Defineatokenusingauniquestringinitsconstructor:

[app/logo-url.token.ts]

import{OpaqueToken}from'@angular/core';

exportconstLOGO_URL=newOpaqueToken('logo.url');

Incorporatethistokenintotheapplicationmoduledefinitionasyounormallywould.However,youmustspecifywhatitwillactuallypointtowhenitisinjected.Inthiscase,itshouldresolvetoanimageURLstring:

[app/app.module.ts]





import{LOGO_URL}from'./logo-url.token';

@NgModule({

imports:[

BrowserModule

],

declarations:[

RootComponent,

ArticleComponent

],

providers:[

{provide:LOGO_URL,useValue:

'https://angular.io/resources/images/logos/standard/logo-nav.png'}

],

bootstrap:[

RootComponent

]

})


Finally,you'llbeabletoinjectthisintoacomponent.However,sinceyou'reinjectingsomethingthatwasn'tdefinedwiththe@Injectable()decoration,you'llneedtouse@Inject()insidetheconstructortotellAngularthatitshouldbeprovided,usingdependencyinjection.Furthermore,theinjectionwillnotattachitselftothecomponent'sthis,soyou'llneedtodothismanuallyaswell:



import{LOGO_URL}from'./logo-url.token';

@Component({

selector:'article',

template:`

<imgsrc="{{logoUrl}}">

<h2>FoolandHisMoneyReunitedatLast</h2>

<p>Author:JakeHsu</p>

`

})


logoUrl:string;

constructor(@Inject(LOGO_URL)privatelogoUrl_){

this.logoUrl=logoUrl_;

}

}

Withthis,youshouldbeabletoseetheimagerenderedinyourbrowser!

Howitworks...OpaqueTokenallowsyoutousenon-classtypesinsideAngular2'sclass-centricproviderschema.Itgeneratesasimpleclassinstancethatessentiallyisjustawrapperforthecustomstringyouprovided.Thisclassiswhatthedependencyinjectionframeworkwillusewhenattemptingtomapinjectiontokenstoproviderdeclarations.Thisgivesyoutheabilitytomorewidelyutilizedependencyinjectionthroughoutyourapplicationsinceyoucannowfeedanytypeofvaluewhereveraservicetypecanbeinjected.

There'smore...Oneotherwayinwhichinjectingvaluesisusefulisthatitgivesyoutheabilitytostuboutservices.Supposeyouwantedtodefineadefaultstubservicethatshouldbeoverriddenwithanexplicitprovidertoenableusefulbehavior.Insuchacase,youcanimagineadefaultarticleentitythatcouldbedifferentlyconfiguredviaadirectivewhilereusingthesamecomponent:



@Component({

selector:'root',

template:`

<article></article>


`

})


[app/editor-article.service.ts]


exportconstMockEditorArticleService={

getArticle:()=>({

title:"Mocktitle",

body:"Mockbody"

})

};

@Injectable()

exportclassEditorArticleService{


"ProminentVeganEmbroiledinScrambledEggsScandal";


"TofuFarmingAllianceretractedtheirendorsement.";

getArticle(){

return{

title:this.title_,

body:this.body_

};

}

}




@Directive({


providers:[EditorArticleService]

})





@Component({

selector:'article',

template:`

<h2>{{title}}</h2>

<p>{{body}}</p>

`

})


title:string;

body:string;

constructor(privateeditorArticleService_:EditorArticleService){

letarticle=editorArticleService_.getArticle();


this.body=article.body;

}

}

Withthis,yourArticleComponent,asdefinedintheprecedingcode,wouldusethemockservicewhenthedirectiveisnotattachedandtheactualservicewhenitisattached.

SeealsoControllingserviceinstancecreationandinjectionwithNgModulegivesabroadoverviewofhowAngular2architectsproviderhierarchiesusingmodulesServiceinjectionaliasingwithuseClassanduseExistingdemonstrateshowtointerceptdependencyinjectionproviderrequestsBuildingaprovider-configuredservicewithuseFactorydetailstheprocessofsettingupaservicefactorytocreateconfigurableservicedefinitions

Buildingaprovider-configuredservicewithuseFactoryOnefurtherextensionofdependencyinjectioninAngular2istheabilitytousefactorieswhendefiningyourproviderhierarchy.Aproviderfactoryallowsyoutoacceptinput,performarbitraryoperationstoconfiguretheprovider,andreturnthatproviderinstanceforinjection.

Note



GettingreadyBeginagainwiththedualserviceandarticlecomponentsetupshowninServiceinjectionaliasingwithuseClassanduseExisting,earlierinthechapter.

Howtodoit...ProviderfactoriesinAngular2areexactlyasyoumightimaginetheywouldbe:functionsthatreturnaprovider.ThefactorycanbespecifiedinaseparatefileandreferencedwiththeuseFactoryprovideoption.

Beginbycombiningthetwoservicesintoasingleservice,whichwillbeconfiguredwithamethodcall:



@Injectable()



"FlyingSpaghettiMonsterSighted";


"Adherentsinsistwearemissingthepoint";

privatenotes_:string="Spoton!";

privateeditorEnabled_:boolean=false;

getArticle():Object{

vararticle={

title:this.title_,

body:this.body_

};

if(this.editorEnabled_){

Object.assign(article,article,{

notes:this.notes_

});

}

returnarticle;

}

enableEditor():void{

this.editorEnabled_=true;

}

}

Definingthefactory

YourobjectiveistoconfigurethisservicetohaveenableEditor()invokedbasedonabooleanflag.Withproviderfactories,thisispossible.Definethefactoryinitsownfile:

[app/article.factory.ts]


exportfunctionarticleFactory(enableEditor?:boolean):ArticleService{

return(articleService:ArticleService)=>{

if(enableEditor){

articleService.enableEditor();

}

returnarticleService;

}

}

InjectingOpaqueToken

Splendid!Next,you'llneedtoreconfigureArticleComponenttoinjectatokenratherthanthedesiredservice:

[app/article.token.ts]

import{OpaqueToken}from'@angular/core';

exportconstArticleToken=newOpaqueToken('app.article');



import{ArticleToken}from'./article.token';

@Component({

selector:'article',

template:`


<p>{{article.body}}</p>

<p*ngIf="article.notes">

<i>Notes:{{article.notes}}</i>

</p>

`

})


article:Object;

constructor(@Inject(ArticleToken)privatearticleService_){

this.article=articleService_.getArticle();

}

}

CreatingproviderdirectiveswithuseFactory

Finally,you'llneedtodefinethedirectivesthatspecifyhowtousethisfactoryandincorporatethemintotheapplication:

[app/default-view.directive.ts]



import{articleFactory}from'./article.factory';


@Directive({

selector:'[default-view]',

providers:[

{provide:ArticleToken,

useFactory:articleFactory(),

deps:[ArticleService]

}

]

})

exportclassDefaultViewDirective{}




import{articleFactory}from'./article.factory';


@Directive({


providers:[

{

provide:ArticleToken,

useFactory:articleFactory(true),

deps:[ArticleService]

}

]

})




@Component({

selector:'root',

template:`

<articledefault-view></article>


`

})


Withthis,youshouldbeabletoseeboththeversionsofArticleComponent.

Howitworks...Thearticlecomponentisredefinedtouseatokeninsteadofaserviceinjection.Withthetoken,Angularwillwalkupthecomponenttreetofindwherethattokenisprovided.Thedirectivesdeclarethatthetokenismappedtoaproviderfactory,whichisamethodinvokedtoreturntheactualprovider.

useFactoryisthepropertythatmapstothefactoryfunction.depsisthepropertythatmapstotheservicedependenciesthatthefactoryhas.

There'smore...Animportantdistinctionatthispointistorecognizethatallthesefactoryconfigurationsarehappeningbeforeanycomponentsareinstantiated.Theclassdecorationthatdefinestheproviderswillinvokethefactoryfunctiononsetup.

SeealsoControllingserviceinstancecreationandinjectionwithNgModulegivesabroadoverviewofhowAngular2architectsproviderhierarchiesusingmodulesServiceinjectionaliasingwithuseClassanduseExistingdemonstrateshowtointerceptdependencyinjectionproviderrequestsInjectingavalueasaservicewithuseValueandOpaqueTokensshowhowyoucanusedependencyinjectedtokenstoinjectgenericobjects

Chapter8.ApplicationOrganizationandManagementThischapterwillcoverthefollowingrecipes:

Composingpackage.jsonforaminimumviableAngular2applicationConfiguringTypeScriptforaminimumviableAngular2applicationPerformingin-browsertranspilationwithSystemJSComposingapplicationfilesforaminimumviableAngular2applicationMigratingtheminimumviableAngular2applicationtoWebpackbundlingIncorporatingshimsandpolyfillsintoWebpackHTMLgenerationwithhtml-webpack-pluginSettingupanapplicationwithAngular'sCLI

IntroductionTheAngular2project'sambitionsgoalsinvolvetheutilizationofadifferentlanguagewithdifferentsyntaxandconstructs,aswellasprovidinghighefficiencyandmodularity.WhatthismeansforyouisthattheprocessofmaintaininganAngular2applicationmaybedifficult.

TheultimategoalistoefficientlyserveHTML,CSS,andJStoawebbrowserandtomakeiteasytodevelopthesourcecomponentsofthesestaticfiles.Howonearrivesatthisendpointcanbeworkedoutinanumberofdifferentways,anditwouldbeanexerciseinfutilitytowriteachapteronallofthem.

Instead,thischapterwillprovideafewopinionatedwaysofarrangingyourAngular2applicationinawaythatitwouldreflectthemostpopularandeffectivestrategies.ItwillalsoshowyouhowtobuildandextendaminimumviableAngular2application.Forsome,thiswillseemabitsimpleandrudimentary.However,themajorityofQuickstartprojectsorcodegenerationframeworkssimplygiveyouarepositoryandafewcommandstoruninordertogetoutofthedoor,andthesecommandsrunwithouttellingyouwhatthey'redoingorhowthey'redoingit!Inthischapter,youwilllearnhowtobuildanAngular2applicationfromthegroundupalongwiththepackagesandtoolsthatwillhelpyoudoitandwhythesemethodswereselected.

Composingpackage.jsonforaminimumviableAngular2applicationWhenthinkingaboutaminimumviableAngular2application,theconfigurationfilesareasclosetothemetaloftheruntimeenvironmentasyou'llget.Inthiscase,therearetwoconfigurationfilesthatwillcontrolhownpmanditsinstalledpackageswillmanagethefilesandthestart-upprocesses:package.jsonandtsconfig.json.

Somepartofthisrecipemaybeareviewfordevelopersthataremoreexperiencedwithnpmanditsfaculties.However,it'simportanttounderstandhowaverysimpleAngular2projectconfigurationcanbestructured,sothatyouareabletowhollyunderstandmorecomplexconfigurationsthatarebuilduponitsfundamentals.

Note



GettingreadyYou'llneedNode.jsinstalledforthisrecipetowork;you'llalsoneedanemptyprojectdirectory.Youshouldcreatethesetwoskeletonconfigurationfilesintherootprojectdirectory:

[package.json]

{

"name":"angular2-minimum-viable-application"

}

[tsconfig.json]

{

"compilerOptions":{

}

}

Tip

Foraquickandeasywaytoensureyouhavenpmsetupandreadytogo,usethefollowing:

npm--versionItshouldspitoutaversionnumberifeverythingissetupproperly.

Howtodoit...You'llstartwithpackage.json.Thepackage.jsonfileforaminimumviableapplicationcontainsthreesections:

dependencies:ThisisalistofpackagetargetsthattheproductionapplicationdirectlydependsupondevDependencies:Thisisalistofpackagetargetsthatthelocalenvironmentneedsforvariousreasons,suchascompilation,runningtests,orlintingscripts:Thesearecustom-definedcommand-lineutilitiesrunthroughnpm

package.jsondependencies

First,youneedtoaddinallthedependenciesthatyourapplicationwillneed.ThisincludesAngular2coremodules,whichliveinsidethenode_modules/@angulardirectory,aswellasahandfuloflibrarydependencies:

core-jsisthepolyfillfortheES6syntaxthattheTypeScriptcompilerdependsupon,suchasSet,Promise,andMap.reflect-metadataisthepolyfillfortheReflectMetadataAPI.ThisallowsyourTypeScripttousedecoratorsthatarenotpartofthestandardTypeScriptspecification,suchas@Component.rxjsisavailablefortheReactiveXJavaScriptobservableslibrary.Angular2nativelyusesObservables,andthisisadirectdependencyoftheframework.SystemJSisthedynamicmoduleloaderthatthisprojectneedsfortwopurposes:toimportandmapallthesourcefiles,andtobeabletoresolvetheES6import/exportdeclarations.zonejsistheZoneJSlibrarythatprovidesAngular2withtheabilitytouseasynchronousexecutioncontexts.Thisisadirectdependencyoftheframework.


[package.json]

{

"name":"angular2-minimum-viable-application",

"dependencies":{

"@angular/common":"2.0.0",

"@angular/compiler":"2.0.0",

"@angular/core":"2.0.0",

"@angular/platform-browser":"2.0.0",

"@angular/platform-browser-dynamic":"2.0.0",

"core-js":"^2.4.1",

"reflect-metadata":"^0.1.3",

"rxjs":"5.0.0-beta.12",

"systemjs":"0.19.27",

"zone.js":"^0.6.23"

}

}

package.jsondevDependencies

Next,youneedtospecifythedevDependencies.

Note

Here'sannpmrefresher:devDependenciesaredependenciesthatarespecifictoadevelopmentenvironment.Buildscriptscanusethistodifferentiatebetweenpackagesthatneedtobeincludedinaproductionbundleandonesthatdon't.

lite-serveristhesimplefileserveryou'llusetotestthisapplicationlocally.Thiscouldbereplacedbyanynumberofsimplefileservers.typescriptistheTypeScriptcompiler.concurrentlyisasimplecommand-lineutilityforrunningsimultaneouscommandsfromannpmscript.


[package.json]

{


"dependencies":{






"core-js":"^2.4.1",


"rxjs":"5.0.0-beta.12",

"systemjs":"0.19.27",

"zone.js":"^0.6.23"

},

"devDependencies":{

"concurrently":"^2.2.0",

"lite-server":"^2.2.2",

"typescript":"^2.0.2"

}

}

package.jsonscripts

Finally,youneedtocreatethescriptsthatyou'llusetogeneratecompiledfilesandrunthedevelopmentserver:

[package.json]

{


"scripts":{

"lite":"lite-server",

"postinstall":"npminstall-S@types/node@types/core-js",

"start":"tsc&&concurrently'npmruntsc:w''npmrunlite'",

"tsc":"tsc",

"tsc:w":"tsc-w"

},

"dependencies":{






"core-js":"^2.4.1",


"rxjs":"5.0.0-beta.12",

"systemjs":"0.19.27",

"zone.js":"^0.6.23"

},

"devDependencies":{




}

}

Eachofthesescriptsservesapurpose,butmostyouwillnotneedtoinvokemanually.Hereisabriefdescriptionofeachofthesescripts:

litestartsoffaninstanceoflite-server.postinstallisthehookdefinitionthatwillrunafternpminstalliscompleted.Inthiscase,afternpmhasinstalledalltheprojectdependencies,youwanttoinstallthedeclarationfilesformodulesthatdonothavethem.npmrecognizesthepre-andpost-prefixesforscriptstrings.Anytimeascriptisrun,npmwillcheckforscriptswithpre-andpost-prefixingthemandrunthembeforeandafterthescript,respectively.Inthisrecipe,prelitewouldrunbeforelite,andpostlitewouldrunafterliteisrun.startisthedefinitionofthedefaultvalueofnpmstart.ThisscriptrunstheTypeScriptcompileroncetocompletion,thensimultaneouslyinvokestheTypeScriptcompilerwatcherandstartsupadevelopmentserver.Itisareservedscriptkeywordinnpm,thusthereisnoneedfornpmrunstart,althoughthatdoeswork.tsckicksofftheTypeScriptcompiler.TheTypeScriptcompilerreadsitssettingsfromthetsconfig.jsonthatexistsinthesamedirectory.tsc:wsetsafilewatchertorecompileuponfilechanges.

SeealsoComposingpackage.jsonforaminimumviableAngular2applicationdescribeshowallthepiecesworkforthecorenodeprojectfileConfiguringTypeScriptforaminimumviableAngular2applicationtalksabouthowtoconfigurethecompilationtosupportanAngular2projectPerformingin-browsertranspilationwithSystemJSdemonstrateshowSystemJScanbeusedtoconnectuncompiledstaticfilestogetherComposingapplicationfilesforaminimumviableAngular2ApplicationwalksyouthroughhowtocreateanextremelysimpleAngular2appfromscratchMigratingtheminimumviableAngular2applicationtoWebpackbundlingdescribeshowtointegrateWebpackintoyourAngularapplicationbuildprocessIncorporatingshimsandpolyfillsintoWebpackgivesyouahandywayofmanagingAngular2polyfilldependenciesHTMLgenerationwithhtml-webpack-pluginshowsyouhowyoucanconfigureannpmpackagetoaddcompiledfilestoyourHTMLautomaticallySettingupanapplicationwithAngularCLIgivesadescriptionofhowtousetheCLI,whatitgivesyou,andwhattheseindividualpiecesdo

ConfiguringTypeScriptforaminimumviableAngular2applicationInordertouseTypeScriptalongsideAngular2,therearetwomajorconsiderations:moduleinteroperabilityandcompilation.You'llneedtohandlebothinordertotakeyourapplication's.tsfiles,mixthemwithexternallibraryfiles,andoutputthefilesthatwouldbecompatiblewithyourtargetdevice.

TypeScriptcomesreadyasannpmpackage,butyouwillneedtotellithowtointeractwiththefilesandmodulesyou'vewritten,andwithfilesfromotherpackagesthatyouwanttouseinyourmodules.

Note



GettingreadyYoushouldfirstcompletetheinstructionsmentionedintheprecedingrecipe.ThiswillgiveyoutheframeworknecessarytodefineyourTypeScriptconfiguration.

Howtodoit...ToconfigureTypeScript,you'llneedtoadddeclarationfilestoincompatiblemodulesandgenerateaconfigurationfilethatwillspecifyhowthecompilershouldwork.

Declarationfiles

TypeScriptdeclarationfilesexisttospecifytheshapeofalibrary.Thesefilescanbeidentifiedbya.d.tssuffix.ThemajorityofnpmpackagesandotherJavaScriptlibrariesalreadyincludethesefilesinastandardizedlocation,sothatTypeScriptcanlocatethemandlearnabouthowthelibraryshouldbeinterpreted.Librariesthatdon'tincludetheseneedtobegiventhefiles,andfortunatelytheopensourcecommunityalreadyprovidesalotofthem.

Twolibrariesthatthisprojectusesdon'thavedeclarationfiles:nodeandcore-js.AsofTypeScript2.0,youareabletonativelyinstallthedeclarationfilesfortheselibrariesdirectlythroughnpm.The-Sflagisashorthandforsavingthemtopackage.json:

npminstall-S@types/node@types/core-js

Asensibleplaceforthisisinsidethepostinstallscript.

tsconfig.json

TheTypeScriptcompilerwilllookforthetsconfig.jsonfiletodeterminehowitshouldcompiletheTypeScriptfilesinthisdirectory.Thisconfigurationfileisn'trequired,asTypeScriptwillfallbacktothecompilerdefaults;however,youwanttomanageexactlyhowthe*.jsand*.map.jsfilesaregenerated.Modifythetsconfig.jsonfiletoappearasfollows:

[tsconfig.json]

{

"compilerOptions":{

"target":"es5",

"module":"commonjs",

"moduleResolution":"node",

"emitDecoratorMetadata":true,

"experimentalDecorators":true,

"noImplicitAny":false

}

}

ThecompilerOptionsproperty,asyoumightexpect,specifiesthesettingsthecompilershouldusewhenthecompilingprocessfindsTypeScriptfiles.Intheabsenceofafilesproperty,TypeScriptwilltraversetheentireprojectdirectorystructuresearchingfor*.tsand*.tsxfiles.

AllthecompilerOptionspropertiescanbespecifiedequivalentlyascommand-lineflags,butdoingsointsconfig.jsonisamoreorganizedwayofgoingaboutyourproject.

targetspecifiestheECMAScriptversionthatthecompilershouldoutput.Forbroadbrowsercompatibility,ES5isasensibledefaulthere.RecallthatECMAScriptisthespecificationuponwhichJavaScriptisbuilt.ThenewestfinishedspecificationisES6(alsocalledES2015),butmanybrowsersdonotfullysupportthisspecificationyet.TheTypeScriptcompilerwillcompileES6constructs,suchasclassandPromise,tonon-nativeimplementations.modulespecifieshowtheoutputfileswillhandlethemodulesintheoutputfiles.SinceyoucannotassumethatbrowsersareabletohandleES6modules,theTypeScriptcompilerwillhavetoconvertthemintoamodulesystemthatbrowsersareabletohandle.CommonJSisasensiblechoicehere.TheCommonJSmodulestyleinvolvesdefiningalltheexportsinasinglemoduleaspropertiesofasingle"exports"object.TheTypeScriptcompileralsosupportsAMDmodules(require.jsstyle),UMDmodules,SystemJSmodules,andofcourse,leavingthemodulesastheirexistingES6modulestyle.It'soutofthescopeofthisrecipetodivedeepintomodules.moduleResolutiondefineshowmodulepathswillberesolved.It'snotcriticalthatyouunderstandtheexactdetailsoftheresolutionstrategy,butthenodesettingwillgiveyoutheproperoutputformat.emitDecoratorMetadataandexperimentalDecoratorsenableTypeScripttohandleAngular2'suseofdecorators.Recalltheadditionofthereflect-metadatalibrarytosupportexperimentaldecorators.TheseflagsarethepointwhereitisabletotieintotheTypeScriptcompiler.noImplicitAnycontrolswhetherornotTypeScriptfilesmustbetyped.Whensettotrue,thiswillthrowanerrorifthereisanymissedtypinginyourproject.Thereisanongoingdiscussionregardingwhetherornotthisflagshouldbeset,asforcingobjectstobetypedisobviouslyusefultopreventerrorsthatmayarisefromambiguityincodebases.Ifyou'dliketoseeanexampleofthecompilerthrowinganerror,setnoImplicitAnytotrueandaddconstructor(foo){}insideAppComponent.Youshouldseethecompilercomplainaboutfoobeinguntyped.

Howitworks...RunningthefollowingcommandwillstartuptheTypeScriptcompilerfromthecommandlineattherootlevelofyourprojectdirectory:

npmruntsc

Thecompilerwilllookfortsconfig.jsonifitisthereandfallbacktoitsdefaultsotherwise.Thesettingswithindirectthecompilerhowtohandleandvalidatethefiles,whichiswhereeverythingyoujustsetupcomesintoplay.

TheTypeScriptcompilerdoesn'trunthecodeormeaningfullyunderstandwhatitdoes,butitcandetectwhendifferentpiecesoftheapplicationaretryingtointeractinawaythatdoesn'tmakesense.The.d.tsdeclarationfileforamodulegivesTypeScriptawaytoinspecttheinterfacethatthemodulewillmakeavailableforconsumptionwhenitisimported.

Forexample,supposethatauthisanexternalmodulethatcontainsaUserclass.Thiswouldthenbeimportedviathefollowing:

import{User}from'./auth';

Byaddingthedeclarationfiletotheimportedmodule,TypeScriptisabletocheckthattheUserclassexists;italsobehavesinthewayyouareattemptingtointhelocalmodule.Ifitseesamismatch,itwillthrowanerroratcompilation.

Compilation

Dependingonyourframeworkexperience,thismaybesomethingyouhaveorhavenothadexperiencewithpreviously.Angular2(amongmanyframeworks)operatesunderthenotionthatJavaScript,asitcurrentlyexists,isinsufficientforwritinggoodcode.Thedefinitionof"good"hereissubjective,butallframeworksthatrequirecompilationwanttoextendormodifyJavaScriptinsomeformoranother.

However,allplatformsthattheseapplicationsneedtorunon—foryourpurposes,webbrowsers—onlyhaveaJavaScriptexecutionenvironmentthatexecutesfromuncompiledcode.Itisn'tfeasibleforyoutoextendhowthebrowserhandlespayloadsordeliversacompiledbinary,sothefilesthatyousendtotheclientmustplaybyitsrules.

TypeScript,bydefinitionanddesign,isastrictsupersetofES6,buttheseextensionscan'tbeusednativelyinabrowser.Eventoday,themajorityofbrowsersstilldonotfullysupportES6.Therefore,asensibleobjectiveistoconvertTypeScriptintoES5.1,whichistheECMAScriptstandardthatissupportedonallmodernbrowsers.Howyouarriveatthisoutputcanoccurinoneoftwoways:

SendtheTypeScripttotheclientasis.Therearein-browsercompilationlibrariesthatcan

performacompilationontheclientandexecutetheresultingES5.1-compliantcodeasnormalJavaScript.Thismethodmakesdevelopmenteasiersinceyourbackenddoesn'tneedtodomuchotherthanservethefiles;however,itdeferscomputingtotheclient,whichdegradesperformanceandisthereforeconsideredabadpracticeforproductionapplications.CompiletheTypeScriptintoJavaScriptbeforesendingittotheclient.Theoverwhelmingmajorityofproductionapplicationswillelecttohandletheirbusinessthisway.EspeciallysincestaticfilesareoftenservedfromaCDNorstaticdirectory,itmakesgoodsensetocompileyourdescriptiveTypeScriptcodebaseintoJavaScriptfilesaspartofareleaseandthenservethosefilestotheclient.

Tip

WhenyoulookatthecompiledJavaScriptthatresultsfromcompilingTypeScript,itcanappearawfullybrutalandunreadable.Don'tworry!ThebrowserdoesnotcarehowmangledtheJavaScriptfilesareaslongastheycanbeexecuted.

Withthecompileroptionsyou'vespecifiedinthisrecipe,theTypeScriptcompilerwilloutputa.jsfileofthesamenamerightnexttoitssource,the.tsfile.

There'smore...BynomeansistheTypeScriptcompilerlimitedtoaone-off.tsfilegeneration.Ifoffersyouabroadrangeoftoolingfunctionsforspecifyingexactlyhowyouroutputfilesshouldappear.

Sourcemapgeneration

TheTypeScriptcompilerisalsocapableofgeneratingsourcemapstogoalongwithoutputfiles.Ifyou'renotfamiliarwiththem,theutilityofsourcemapsstemsfromthenatureofcompilationandminification:filesbeingdebuggedinthebrowsersarenotthefilesthatyouhavewritten.What'smore,whenusingacompiledTypeScript,thecompiledfileswon'tevenbeinthesamelanguage.

Sourcemapsareindexesthatpairwithcompiledfilestodescribehowtheyoriginallyappearedbeforetheywerecompiled.Morespecifically,the.js.mapfilescontainanencodingschemethatassociatesthecompiledand/orminifiedtokenswiththeiroriginalnameandstructureintheuncompiled.tsfile.Browsersthatunderstandhowtousesourcemapscanreconstructhowtheoriginalfileappearedandallowyoutosetbreakpoints,stepthrough,andinspectlexicalconstructsinsideitasifitweretheoriginal.

Sourcemapscanbespecifiedwithaspecialtokenaddedtothecompiledfile://#sourceMappingURL=/dist/example.js.map

Ifyouwanttogeneratesourcemapfilesfortheoutput,youcanspecifythisintheconfigurationfileaswellbyadding"sourceMap":true.Bydefault,the.js.mapfileswillbecreatedinthesameplaceastheoutput.jsfiles;alternatively,youcandirectthecompilertocreatethesourcemapsinsidethe.jsfileitself.

Tip

Eventhoughextraneousmapfileswon'taffecttheresultantapplicationbehavior,addingtheminlinemaybeundesirableifyoudon'twanttobloatyour.jspayloadsizeunnecessarily.Thisisbecauseclientsthatdon'twantorneedthemapfilescan'tdeclinetorequestthem.

Singlefilecompilation

SinceTypeScriptchecksallthelinkedmodulesagainsttheirimportsandexports,there'snoreasonyouneedtohaveallthecompiledfilesexistas1:1mappingstotheirinputfiles.TypeScriptisperfectlyhappytocombinethecompiledfilesintoasinglefileiftheoutputmoduleformatsupportsit.Specifythesinglefilewhereyouwishallthemodulestobecompiledwith"outFile":"/dist/bundle.js".

Note

Certainoutputmoduleformats,suchasCommonJS,won'tworkasconcatenatedmodulesina

singlefile,sousingtheminconjunctionwithoutFilewillnotwork.AsoftheTypeScript1.8release,AMDandsystemoutputformatsaresupported.

IfyouplanonusingSystemJS,thiscompileroptioncanpotentiallyhelpyou,asSystemworkswithvirtuallyanymoduleformat.If,however,you'reusingaCommonJS-basedbundler,suchasWebpack,it'sbesttodelegatethefilecombinationtothebundler.

SeealsoComposingpackage.jsonforaminimumviableAngular2applicationdescribeshowallthepiecesworkforthecorenodeprojectfilePerformingin-browsertranspilationwithSystemJSdemonstrateshowSystemJScanbeusedtoconnectuncompiledstaticfilestogetherComposingapplicationfilesforaminimumviableAngular2applicationwalksyouthroughhowtocreateanextremelysimpleAngular2appfromscratchMigratingtheminimumviableAngular2applicationtoWebpackbundlingdescribeshowtointegrateWebpackintoyourAngularapplicationbuildprocess

Performingin-browsertranspilationwithSystemJSItcanbeoftenusefultobeabletodeliverTypeScriptfilesdirectlytothebrowserandtodeferthetranspilationtoJavaScriptuntilthen.Whilethismethodhasperformancedrawbacks,itisextremelyusefulwhenprototypingandperformingexperimentations.

Note



GettingreadyCreateanemptyprojectdirectoryandcreatethefollowingpackage.jsoninsideit:

[package.json]

{

"scripts":{

"lite-server":"lite-server"

},

"devDependencies":{


"systemjs":"^0.19.38",


}

}

Runningnpminstallshouldgetyoureadytowritecode.

Howtodoit...TheTypeScriptnpmpackagecomesbundledwithatranspiler.WhencombinedwithSystemJSasthedesignatedtranspilationutility,thisallowsyoutoserveTypeScriptfilestotheclient;SystemJSwilltranspilethemintobrowser-compatibleJavaScript.

First,createtheindex.htmlfile.ThisfilewillimportthetworequiredJSlibraries:system.jsandtypescript.js.Next,itspecifiesthetypescriptasthedesiredtranspilerandimportsthetop-levelmain.tsfile:

[index.html]

<html>

<head>

<scriptsrc="node_modules/systemjs/dist/system.js">

</script>

<scriptsrc="node_modules/typescript/lib/typescript.js">

</script>

<script>

System.config({

transpiler:'typescript'

});

System.import('main.ts');

</script>

</head>

<body>

<h1id="text"></h1>

</body>

</html>

Next,createthetop-levelTypeScriptfile:

[main.ts]

import{article}from'./article.ts';

document.getElementById('text')

.innerHTML=article;

Finally,createthedependencyTypeScriptfile:

[article.ts]

exportconstarticle="Coolstory,bro";

Withthis,youshouldbeabletostartadevelopmentserverwithnpmrunlite-serverandseetheTypeScriptapplicationrunningnormallyinyourbrowseratlocalhost:3000.

Howitworks...SystemJSisabletoresolvemoduledependenciesaswellasapplythetranspilertothemodulebeforeitreachesthebrowser.Ifyoulookatthetranspiledfilesinabrowserinspector,youcanseetheemittedfilesexistasvanillaJavaScriptIIFEs(instantaneouslyinvokedfunctionexpressions)aswellastheircoupledsourcemaps.Withthesetools,itispossibletobuildasurprisinglycomplexapplicationwithoutanysortofbackendfilemanagement.

There'smore...Unlessyou'reexperimentingordoingaroughproject,doingtranspilationinthebrowserisn'tpreferred.Anycomputationyoucandoontheservershouldbedonewheneverpossible.Additionally,alltheclientstranspilingtheirownfilesallperformhighlyredundantoperationssinceallofthemtranspilethesamefiles.

SeealsoComposingpackage.jsonforaminimumviableAngular2applicationdescribeshowallthepiecesworkforthecorenodeprojectfileConfiguringTypeScriptforaminimumviableAngular2applicationtalksabouthowtoconfigurethecompilationtosupportanAngular2projectComposingapplicationfilesforaminimumviableAngular2applicationwalksyouthroughhowtocreateanextremelysimpleAngular2appfromscratchMigratingtheminimumviableAngular2applicationtoWebpackbundlingdescribeshowtointegrateWebpackintoyourAngularapplicationbuildprocessIncorporatingshimsandpolyfillsintowebpackgivesyouahandywayofmanagingAngular2polyfilldependenciesHTMLgenerationwithhtml-webpack-pluginshowsyouhowyoucanconfigureannpmpackagetoaddcompiledfilestoyourHTMLautomaticallySettingupanapplicationwithAngularCLIgivesadescriptionofhowtousetheCLI,whatitgivesyou,andwhattheseindividualpiecesdo

ComposingapplicationfilesforaminimumviableAngular2applicationWhenapproachingAngular2initially,itisusefultohaveanunderstandingofanapplicationstructurethatistorndowntothebaremetal.Inthecaseofaminimumviableapplication,itwillconsistofasinglecomponent.Sincethisisachapteronapplicationorganization,itisn'tsomuchaboutwhatthatcomponentwilllooklike,butratherhowtotaketheTypeScriptcomponentdefinitionandactuallygetittorenderinawebpage.

Note



GettingreadyThisrecipeassumesyouhavecompletedallthestepsgivenintheComposingconfigurationfilesforaminimumviableAngular2applicationrecipe.Thenpmmoduleinstallationshouldsucceedwithnoerrors:

npminstall

Howtodoit...Thesimplestplacetostartisthecoreapplicationcomponent.

app.component.ts

Implementacomponentinsideanewapp/directoryasfollows;thereshouldbenosurprises:



@Component({

selector:'app-root',

template:'<h1>AppComponenttemplate!</h1>'

})

exportclassAppComponent{}

Thisisaboutassimpleacomponentcanpossiblyget.Oncethisissuccessfullyrenderedintheclient,thiscomponentshouldjustbeabiglineoftext.

app.module.ts

Next,youneedtodefinetheNgModulethatwillbeassociatedwiththiscomponent.Createanotherfileintheapp/directory,app.module.ts,andhaveitmatchthefollowing:

[app/app.module.ts]



import{AppComponent}from'./app.component';

@NgModule({

imports:[BrowserModule],

declarations:[AppComponent],

bootstrap:[AppComponent]

})


There'sabitmoregoingonhere:

importsspecifiesthemoduleswhoseexporteddirectives/pipesshouldbeavailabletothismodule.

Tip

ImportingBrowserModulegivesyouaccesstocoredirectivessuchasNgIfandalsospecifiesthetypeofrenderer,eventmanagement,anddocumenttype.Ifyourapplicationisrenderinginawebbrowser,thismodulegivesyouthetoolsyouneedtodothis.

declarationsspecifieswhichdirectives/pipesarebeingexportedbythismodule.Inthiscase,AppComponentisthesoleexport.bootstrapspecifieswhichcomponentsshouldbebootstrappedwhenthismoduleisbootstrapped.Morespecifically,componentslistedherewillbedesignatedforrenderingwithinthismodule.AppComponentneedstobebootstrappedandrenderedsomewhere,andthisiswherethisspecificationwilloccur.

Thiscompletesthemoduledefinition.Atthispoint,youhavesuccessfullylinkedthecomponenttoitsmodule,butthismoduleisn'tbeingbootstrappedanywhereorevenincluded.

main.ts

You'llchangethisnextwithmain.ts,thetop-levelTypeScriptfile:

[app/main.ts]



import{AppModule}from'./app.module';

platformBrowserDynamic().bootstrapModule(AppModule);

ThisfiledefinestheNgModuledecoratorthatwillbeusedforAppComponent.Insideit,youspecifythatthemodulemustimportBrowserModule.

Note

RecallthatAngular2isdesignedtobeplatform-independent.Morespecifically,itstrivestoallowyoutowritecodethatmightnotnecessarilyrunonaconventionalwebbrowser.Inthiscase,youaretargetingastandardwebbrowser,soimportingBrowserModulefromtheplatformBrowsertargetisthewayinwhichyoucaninformtheapplicationofthis.Ifyouweretargetingaseparateplatform,youwouldselectadifferentplatformtoimportintoyourrootapplicationcomponent.

ThisNgModuledeclarationalsospecifiesthatAppComponentexistsandshouldbebootstrapped.

Note

BootstrappingishowyoukickoffyourAngular2application,butithasaveryspecificdefinition.Invokingbootstrap()tellsAngulartomountthespecifiedapplicationcomponentontoDOMelementsidentifiedbythecomponent'sselector.Thiskicksofftheinitialroundofchangedetectionanditssideeffects,whichwillcompletethecomponentinitialization.

Sinceyou'vedeclaredthatthismodulewillbootstrapAppComponentwhenitisbootstrapped,thismodulewillinturnbetheonebootstrappedfromthetop-levelTypeScriptfile.Angular2pushesforthisconventionasamain.tsfile:

[app/main.ts]





TheplatformBrowserDynamicmethodreturnsaplatformobjectthatexposesthebootstrapModulemethod.ItconfiguresyourapplicationtobebootstrappedwithAngular2'sjust-in-time(JIT)compiler.

Tip

Fornow,thedetailsofwhyyouarespecifyingjust-in-timecompilationaren'timportant.It'senoughtoknowthatJITcompilationisasimplerversion(asopposedtoahead-of-timecompilation)inAngular2'sofferings.

index.html

Finally,youneedtobuildanHTMLfilethatiscapableofbundlingtogetherallthesecompiledfilesandkickingofftheapplicationinitialization.Beginwiththefollowing:

[index.html]

<html>

<head>

<title>Angular2MinimumViableApplication</title>

<scriptsrc="node_modules/zone.js/dist/zone.js">

</script>

<scriptsrc="node_modules/reflect-metadata/Reflect.js">

</script>

<scriptsrc="node_modules/systemjs/dist/system.src.js">

</script>

</head>

<body>

<app-root></app-root>

</body>

</html>

Mostofthissofarshouldbeexpected.ZoneJSandReflectareAngular2dependencies.Themoduleloaderyou'lluseisSystemJS.<app-root>istheelementthatAppComponentwillrenderinside.

ConfiguringSystemJS

Next,SystemJSneedstobeconfiguredtounderstandhowtoimportmodulefilesandhowtoconnectmodulesfrombeingimportedinsideothermodules.Inotherwords,itneedstobegivenafiletobeginwithandadirectoryofmappingsfordependenciesofthatmainfile.Thiscanbe

accomplishedwithSystem.config()andSystem.import(),whicharemethodsexposedontheglobalSystemobject:

[index.html]

<html>

<head>



</script>


</script>

<scriptsrc="node_modules/systemjs/dist/system.src.js">

</script>

<script>

System.config({

paths:{

'ng:':'node_modules/@angular/'

},

map:{

'@angular/core':'ng:core/bundles/core.umd.js',

'@angular/common':'ng:common/bundles/common.umd.js',

'@angular/compiler':

'ng:compiler/bundles/compiler.umd.js',

'@angular/platform-browser':

'ng:platform-browser/bundles/platform-browser.umd.js',

'@angular/platform-browser-dynamic':

'ng:platform-browser-dynamic/bundles/platform-browser-

dynamic.umd.js',

'rxjs':'node_modules/rxjs'

},

packages:{

app:{

main:'./main.js'

},

rxjs:{

defaultExtension:'js'

}

}

});

System.import('app');

</script>

</head>

<body>


</body>

</html>

System.config()specifieshowSystemJSshouldhandlethefilespassedtoit.

Thepathspropertyspecifiesanaliastoshortenthepath'sinsidemap.Itactsasasimple

findandreplacefunction,soanyfoundinstancesofng:arereplacedwithnode_modules/@angular/.ThemappropertyspecifieshowSystemJSshouldresolvethemoduleimportsthatyouhavenotexplicitlydefined.Here,thistakestheformoffivecoreAngularmodulesandtheRxJSlibrary.Thepackagespropertyspecifiesthetargetsthatwillbeimportedbythispropertyandthefilestheyneedtomapto.

Tip

Forexample,theapppropertywillbeusedwhenamoduleimportsapp,andinsideSystemJS,thiswillmaptomain.js.Similarly,whenamodulerequiresanRxJSmodule,suchasSubject,SystemJSwilltaketherxjs/Subjectimportpath,recognizethatdefaultExtensionisspecifiedasjs,mapthemoduletoitsfilerepresentationnode_modules/rxjs/Subject.js,andimportit.

SeealsoComposingpackage.jsonforaminimumviableAngular2applicationdescribeshowallthepiecesworkforthecorenodeprojectfileConfiguringTypeScriptforaminimumviableAngular2applicationtalksabouthowtoconfigurecompilationtosupportanAngular2projectPerformingin-browsertranspilationwithSystemJSdemonstrateshowSystemJScanbeusedtoconnectuncompiledstaticfilestogetherMigratingtheminimumviableAngular2applicationtoWebpackbundlingdescribeshowtointegrateWebpackintoyourAngularapplicationbuildprocessIncorporatingshimsandpolyfillsintoWebpackgivesyouahandywayofmanagingAngular2polyfilldependenciesHTMLgenerationwithhtml-webpack-pluginshowsyouhowyoucanconfigureannpmpackagetoaddcompiledfilestoyourHTMLautomaticallySettingupanapplicationwithAngularCLIgivesadescriptionofhowtousetheCLI,whatitgivesyou,andwhattheseindividualpiecesdo

MigratingtheminimumviableapplicationtoWebpackbundlingItisadvantageousformanyreasonstomakeitaseasyandquickaspossiblefortheclienttoloadandrunthecodesentfromyourserver.Oneoftheeasiestandmosteffectivewaysofdoingthisisbybundlinglotsofcodeintoasinglefile.Innearlyallcases,itishighlyefficientforthebrowsertoloadasinglefilethatcontainsallthedependenciesrequiredtobootstrapanapplication.

WebpackoffersmanyusefultoolsandamongthemistheterrificJSbundler.Thisrecipedemonstrateshowyouwillbeabletocombineyourentireapplication(includingnpmpackagedependencies)intoasingleJavaScriptfilethatthebrowserwillbeserved.

Note



GettingreadyYoushouldhavecompletedallthestepsgivenintheComposingconfigurationfilesforaminimumviableAngular2applicationandComposingapplicationfilesforaminimumviableAngular2applicationrecipes.npmstartshouldstartupthedevelopmentserver,anditshouldbevisibleatlocalhost:3000.

Howtodoit...Beginbyremovingtheapplication'sdependencyonSystemJS.webpackisabletoresolvedependenciesandbundleallyourfilesintoasingleJSfile.Beginbyinstallingwebpackwiththeglobalflag:

npminstallwebpack-g

webpack.config.js

webpacklooksforawebpack.config.jsfileforinstructionsonhowtobehave.Createthisnow:

[webpack.config.js]

module.exports={

entry:"./app/main.js",

output:{

path:"./dist",

filename:"bundle.js"

}

};

Nothingexceptionallycomplicatedisgoingonhere.Thistellswebpacktoselectmain.jsasthetop-levelapplicationfile,resolveallitsdependenciestothefilesthatdefinethem,andbundlethemintoasinglebundle.jsinsideadist/directory.

Tip

Atthispoint,youcancheckthatthisisworkingbyinvokingwebpackfromthecommandline,whichwillrunthebundler.Youshouldseebundle.jsappearinsidedist/withallthemoduledependenciesinsideit.

Thisisagoodstart,butthisgeneratedfilestillisn'tbeingusedanywhere.Next,you'llmodifyindex.htmltousethefile:

[index.html]

<html>

<head>



</script>


</script>

<scriptsrc="dist/bundle.js">

</script>

</head>

<body>


</body>

</html>

Probablynotwhatyouwereexpectingatall!Sincebundle.jsistheapplicationentrypointandSystemJSisnolongerneededtoresolveanymodules(becausewebpackisalreadydoingthisforyouwhenbundlingthefiles),youcanremovetheapplication'sdependencyonSystemJS.

Sincethisisthecase,youcanremovetheSystemdependencyfromyourpackage.jsonandaddthewebpackscriptsanddependency:

[package.json]

{

"name":"mva-bundling",

"scripts":{

"start":"tsc&&webpack&&concurrently'npmruntsc:w'

'npmrunwp:w''npmrunlite'",



"tsc":"tsc",

"tsc:w":"tsc-w",

"wp":"webpack",

"wp:w":"webpack--watch"

},

"dependencies":{






"core-js":"^2.4.1",


"rxjs":"5.0.0-beta.12",

"zone.js":"^0.6.23"

},

"devDependencies":{



"typescript":"^2.0.2",

"webpack":"^1.13.2"

}

}

WhetherornotwebpackandtypescriptbelongtodevDependencieshereisamatterofdisputeandislargelysubjecttohowyoumanageyourlocalenvironment.Ifyou'vealreadyinstalledthemwiththeglobalflag,thenyoudon'tneedtolistithereasadependency.Thisisbecausenpmwillsearchforgloballyinstalledpackagesandfindthemforyoutorunnpmscripts.Furthermore,listingitherewillinstalladuplicatewebpacklocaltothisproject,whichisobviouslyredundant.

Forthepurposeofthisrecipe,itishelpfultohaveithere.Thisisbecauseyoucanensurethatasinglenpminstallonthecommandlinewillfetchallthepackagesyouneedoffthebat,andthiswillletyouspecifytheversionyouwantwithintheproject.

Now,whenyouexecutenpmstart,thefollowingoccurs:

TypeScriptdoesaninitialcompilationof.tsfilesinto.jsfiles.WebpackdoesaninitialbundlingofalltheJSfilesintoasinglebundle.jsinthedist/directory.Simultaneously,lite-serverisstarted,theTypeScriptcompilerwatcherisstarted,andtheWebpackwatcherisstarted.Upona.tsfilechange,TypeScriptwillcompileitintoa.jsfile,andWebpackwillpickupthatfilechangeandrebundleitintobundle.js.Thelite-serverwillseethatbundle.jsischangedandreloadthepage,soyoucanseethechangesbeingupdatedautomatically.

Tip

Withoutspecifyingtheconfigurationsmoreclosely,theTypeScript,Webpack,andthelite-serverfilewatchlistswillusetheirdefaultsettings,whichmaybetoobroadandthereforewouldwatchfilestheydonotcareabout.Ideally,TypeScriptwouldonlywatch.tsfiles(whichdoesthiswithyourtsconfig.json),Webpackwouldonlywatch.html,.js,and.cssfiles,andlite-serverwouldonlywatchthefilesitactuallyservestotheclient.

SeealsoIncorporatingshimsandpolyfillsintoWebpackgivesyouahandywayofmanagingAngular2polyfilldependenciesHTMLgenerationwithhtml-webpack-pluginshowsyouhowyoucanconfigureannpmpackagetoaddcompiledfilestoyourHTMLautomatically

IncorporatingshimsandpolyfillsintoWebpackSofar,thishasbeenamuchcleanerimplementation,butyoustillhavethetwodanglingshimsinsidetheindex.htmlfile.You'vepareddownindex.htmlsuchthatitisnowrequestingonlyahandfulofJSfilesinsteadofeachmoduletargetindividually,butyoucangoevenfurtherandbundlealltheJSfilesintoasinglefile.

Thechallengeinthisisthatbrowsershimsaren'tdeliveredviamodules;inotherwords,therearen'tanyotherfilesthatwillimportthesetousethem.Theyjustassumetheiruseisavailable.Therefore,thestandardWebpackbundlingwon'tpickupthesetargetsandincludetheminthebundledfile.

Note



GettingreadyYoushouldcompletetheMigratingtheminimumviableapplicationtoWebpackbundlingrecipefirst,whichwillgiveyouallthesourcefilesneededforthisrecipe.

Howtodoit...Thereareanumberofwaystogoaboutdoingthis,includingsomethatinvolvetheadditionofWebpackplugins,butthere'sanextremelysimplewayaswell:justaddtheimportsmanually.

Createanewpolyfills.ts:

[src/polyfills.ts]

import"reflect-metadata";

import"zone.js";

Importthismodulefrommain.ts:

[src/main.ts]

import'./polyfills';



import{AppModule}from'./app/app.module';


Finally,cleanupindex.html:

[index.html]

<html>

<head>


<body>


<scriptsrc="dist/bundle.js"></script>

</body>

</html>

Now,Webpackshouldbeabletoresolvetheshimimports,andalltheneededfileswillbeincludedinsidebundle.js.

Howitworks...TheonlyreasonthatthepolyfillsarenotdiscoveredbyWebpackisbecausetheyarenotrequiredanywhereintheapplication.Rather,anywheretheyareusedleadstotheassumptionthattheexposedtargets,suchasZone,havepreviouslybeenmadeavailable.Therefore,itiseasyforyoutosimplyimportthemattheverytopofyourapplication,whichhasawell-definedpointinthecode.WiththisWebpack,youwillbeabletodiscovertheexistenceofpolyfillsandincorporatethemintothegeneratedbundle.

SeealsoMigratingtheminimumviableAngular2applicationtoWebpackbundlingdescribeshowtointegrateWebpackintoyourAngularapplicationbuildprocessHTMLgenerationwithhtml-webpack-pluginshowsyouhowyoucanconfigureannpmpackagetoaddcompiledfilestoyourHTMLautomatically

HTMLgenerationwithhtml-webpack-pluginIdeally,youwouldliketobeabletohaveWebpackmanagethebundledfileanditsinjectionintothetemplate.Bydefault,Webpackisunabletodothis,asitisonlyconcernedwiththefilesrelatedtoscripting.Fortunately,WebpackoffersanextremelypopularpluginthatallowsyoutoexpandthescopeofWebpack'sfileconcerns.

Note



GettingreadyInstallthepluginandaddittodevDependenciesofpackage.jsonwiththefollowing:

npminstallhtml-webpack-plugin--save-dev

Howtodoit...First,you'llneedtoincorporatethepluginintopackage.jsonifitisn'talready:

[package.json]

{

"name":"mva-bundling",

"scripts":{

"start":"tsc&&webpack&&concurrently'npmruntsc:w'

'npmrunwp:w''npmrunlite'",



"tsc":"tsc",

"tsc:w":"tsc-w",

"wp":"webpack",

"wp:w":"webpack--watch"

},

"dependencies":{






"core-js":"^2.4.1",


"rxjs":"5.0.0-beta.12",

"zone.js":"^0.6.23"

},

"devDependencies":{


"html-webpack-plugin":"^2.22.0",

"imports-loader":"^0.6.5",



"webpack":"^1.13.2"

}

}

Oncethismoduleisinstalled,defineitsoperationinsidetheWebpackconfig:

[webpack.config.js]

varHtmlWebpackPlugin=require('html-webpack-plugin');

module.exports={

entry:"./src/main.js",

output:{

path:"./dist",

filename:"bundle.js"

},

plugins:[newHtmlWebpackPlugin({

template:'./src/index.html'

})]

};

ThisspecifiestheoutputHTMLfilethatwillservetheentireapplication.SincethepluginwillautomaticallygeneratetheHTMLfileforyou,you'llneedtomodifytheexistingonethatisdesignatedasthetemplate:

[src/index.html]

<html>

<head>


</head>

<body>


</body>

</html>

Finally,becauseindex.htmlisnowservedoutofthedist/directory,you'llneedtoconfigurethedevelopmentservertoservefilesoutofthere.Sincelite-serverisjustawrapperforBrowserSync,youcanspecifybaseDirinsideabs-config.jsonfile,whichyoushouldcreatenow:

[bs-config.json]

{

"server":{"baseDir":"./dist"}

}

Howitworks...Webpackisverymuchawareofthebundlethatitiscreating,andsoitmakessensethatyouwouldbeabletomaintainareferencetothisbundle(orbundles)anddirectlypipethosepathsintoanindex.htmlfile.ThepluginwillappendthescriptsattheendofthebodytoensuretheentireinitialDOMispresent.

SeealsoMigratingtheminimumviableAngular2applicationtoWebpackbundlingdescribeshowtointegrateWebpackintoyourAngularapplicationbuildprocessIncorporatingshimsandpolyfillsintoWebpackgivesyouahandywayofmanagingAngular2polyfilldependencies

SettingupanapplicationwithAngularCLIIntandemwiththeAngular2framework,theAngularteamalsosupportsabuildtoolthatcancreate,build,andrunanAngular2applicationrightoutofthebox.What'smore,itincludesageneratorthatcancreatestyle-guide-compliantfilesanddirectoriesforvariousapplicationpiecesfromthecommandline.

Note



GettingreadyAngular'sCLIisannpmmodule.You'llneedtohaveNode.jsinstalledonyoursystem—v7.0.0orlaterworksasasuitablerecentreleasethat'scompatiblewiththeAngularCLI.

Tip

Thereisanotheroptionyouhave:manageyourNodeenvironmentswithnvm,theNodeversionmanager.ThisgivesyouatransparentwrapperthatcanseparatelymanageenvironmentswiththeNodeversionaswellastheinstallednpmpackagesinthatenvironment.Ifyou'veeverdealtwithmessinessinvolvingsudonpminstall-g,youwillbedelightedbythistool.

OnceNodeisinstalled(andifyouusenvm,you'veselectedwhichenvironmenttouse),installtheAngularCLI:

npminstall-gangular-cli

Howtodoit...AngularCLIcomesreadytogenerateafullyworkingAngular2application.TocreateanapplicationnamedPublisherApp,invokethefollowingcommand:

ngnewpublisher

TheAngularCLIwilldutifullyassembleallthefilesneededforaminimalAngular2TypeScriptapplication,initializeaGitrepository,andinstallalltherequirednpmdependencies.Thecreatedfilelistshouldlookasfollows:

createREADME.md

createsrc/app/app.component.css

createsrc/app/app.component.html

createsrc/app/app.component.spec.ts

createsrc/app/app.component.ts

createsrc/app/app.module.ts

createsrc/app/index.ts

createsrc/app/shared/index.ts

createsrc/environments/environment.prod.ts

createsrc/environments/environment.ts

createsrc/favicon.ico

createsrc/index.html

createsrc/main.ts

createsrc/polyfills.ts

createsrc/styles.css

createsrc/test.ts

createsrc/tsconfig.json

createsrc/typings.d.ts

createangular-cli.json

createe2e/app.e2e-spec.ts

createe2e/app.po.ts

createe2e/tsconfig.json

create.gitignore

createkarma.conf.js

createpackage.json

createprotractor.conf.js

createtslint.json

Usecdpublishertomoveintotheapplication'sdirectory,whichwillallowyoutoinvokealltheproject-specificAngularCLIcommands.

Runningtheapplicationlocally

Torunthisapplication,startuptheserver:

ngserve

Thedefaultapplicationpagewillbeavailableonlocalhost:4200.

Testingtheapplication

Toruntheapplication'sunittests,usethis:

ngtest

Toruntheapplication'send-to-endtests,usethis:

nge2e

Howitworks...Let'sroughlygothroughwhateachofthesefilesoffertoyou:

Projectconfigurationfilesangular-cli.jsonistheconfigurationfilespecifyinghowtheAngularCLIshouldbundleandmanageyourapplication'sfilesanddirectories.package.jsonisthenpmpackageconfigurationfile.Insideit,you'llfindscriptsandcommand-linetargetsthattheAngularCLIcommandswilltieinto.

TypeScriptconfigurationfilestslint.jsonspecifiestheconfigurationforthetslintnpmpackage.TheAngularCLIcreatesforyoualintcommandfor.tsfileswithnpmrunlint.src/tsconfig.jsonispartoftheTypeScriptspecification;itinformsthecompilerthatthisistherootoftheTypeScriptproject.Itscontentsdefinehowthecompilationshouldoccur,anditspresenceenablesthetsccommandtousethisdirectoryastherootcompilationdirectory.e2e/tsconfig.jsonistheend-to-endTypeScriptcompilerconfigurationfile.src/typings.d.tsisthespecificationfileforthetypingsnpmmodule.ItallowsyoutodescribehowexternalmodulesshouldbewrappedandincorporatedintotheTypeScriptcompiler.Thistypings.d.tsfilespecifiestheSystemnamespaceforSystemJS.

Testconfigurationfileskarma.conf.jsistheconfigurationfileforKarma,thetestrunnerfortheprojectprotractor.conf.jsistheconfigurationfileforProtractor,theend-to-endtestframeworkfortheprojectsrc/test.tsdescribestotheKarmaconfigurationhowtostartupthetestrunnerandwheretofindthetestfilesthroughouttheapplication

Coreapplicationfilessrc/index.htmlistherootapplicationfilethatisservedtoruntheentiresingle-pageapplication.CompiledJSandotherstaticassetswillbeautomaticallyaddedtothisfilebythebuildscript.src/main.tsisthetop-levelTypeScriptfilethatservestobootstrapyourapplicationwithitsAppModuledefinition.src/polyfills.tsisjustafilethatkeepsthelonglistofimportedpolyfillmodulesoutofmain.ts.src/styles.cssistheglobalapplicationstylefile.

Environmentfilessrc/environments/environment.tsisthedefaultenvironmentconfigurationfile.Specifyingdifferentenvironmentswhenbuildingandtestingyourapplicationwilloverride

these.src/environments/environment.prod.tsistheprodenvironmentconfiguration,whichcanbeselectedfromthecommandlinewith--prod.

AppComponentfiles

EveryAngular2applicationhasatop-levelcomponent,andAngularCLIcallsthisAppComponent.

src/app/app.component.tsisthecoreTypeScriptcomponentclassdefinition.Thisiswhereallofthelogicthatcontrolsthiscomponentshouldgo.src/app/app.component.htmlandsrc/app/app.component.cssarethetemplatingandstylingfilesspecifictoAppComponent.RecallthatstylingspecifiedinComponentMetadataisencapsulatedonlytothiscomponent.src/app/app.module.tsistheNgModuledefinitionforAppComponent.src/app/index.tsisthefilethatinformstheTypeScriptcompilerwhichmodulesareavailableinsidethisdirectory.Anymodulesthatareexportedinthisdirectoryandusedelsewhereintheapplicationmustbespecifiedhere.

AppComponenttestfilessrc/app/app.component.spec.tsaretheunittestsforAppComponente2e/app.e2e-spec.tsaretheend-to-endtestsforAppComponente2e/app.po.tsisthepageobjectdefinitionforuseinAppComponentend-to-endtesting

There'smore...Whenlookingattheentireprojectcodebase,thebulkofthefilesbreakdownintofourcategories:

Filesthataresenttothebrowser:Thisincludesyouruncompiled/unminifiedapplicationfilesandalsothecompiled/minifiedfiles.Whendevelopingyourapplication,youwanttobeabletotestyourapplicationlocallywithuncompiledfiles.Youalsowanttobeabletoshipyourapplicationtoproductionwithcompiledandminifiedfiles,whichoptimizesbrowserperformance.Theuncompiled/unminifiedfilesarecollectedbythebuildscripts,tobecombinedintothecompiled/minifiedfiles.Filesusedfortesting:Thetestfilesthemselvesareusuallysprinkledthroughoutyourapplicationandarenotcompiled.Thiscategoryalsoincludesconfigurationfilesandtestscriptsthatcontrolwhatactuallyhappenswhenyourunthetestsandwherethetestrunnerscanfindthetestfilesinyourprojectdirectory.Filesthatcontrolyourdevelopmentenvironment:Dependingonyoursetup,yoursingle-pageapplicationmayrunbyitself(withnobackendcodebase),oritmaybebuiltalongsideasubstantialbackendcodebasethatexposesAPIsandotherserver-sidebehavior.Quickstartrepositoriesorapplicationgenerators(suchasAngularCLI)usuallyprovideyouwithaminimalHTTPservertogetyouoffthegroundandserveyourstaticassetstothebrowser.Howexactlyyourunyourdevelopmentenvironmentwillvary,butthefilesinthiscategorymanagehowyourapplicationwillworkbothlocallyandinproduction.Filesthatcompileyourapplication:Thefilesyoueditinyourcodeeditorofchoicearenottheonesthatreachthebrowserinaproductionapplication.Buildscriptsareusuallysetuptocombineallyourfilesintothesmallestandfewestfilespossible.Frequently,thiswillmeanasinglecompiledJSandcompiledCSSfiledeliveredtothebrowser.Thesefileswillminifyyourcodebase,compileTypeScriptintovanillaJavaScript,selectenvironmentfilesandothercontext-specificfiles,andorganizefileincludesandotherfilesandmoduledependenciessothatyourapplicationworkswhenit'scompiled.Usually,thefilestheycreatewillbedumpedintoadistdirectory,whichwillcontainfilesthatareservedtothebrowserinproduction.

SeealsoComposingpackage.jsonforaminimumviableAngular2applicationdescribeshowallthepiecesworkforthecorenodeprojectfileConfiguringTypeScriptforaminimumviableAngular2applicationtalksabouthowtoconfigurecompilationtosupportanAngular2projectPerformingin-browsertranspilationwithSystemJSdemonstrateshowSystemJScanbeusedtoconnectuncompiledstaticfilestogetherComposingapplicationfilesforaminimumviableAngular2applicationwalksyouthroughhowtocreateanextremelysimpleAngular2appfromscratchIncorporatingshimsandpolyfillsintoWebpackgivesyouahandywayofmanagingAngular2polyfilldependencies

Chapter9.Angular2TestingThischapterwillcoverthefollowingrecipes:

CreatingaminimumviableunittestsuitewithKarma,Jasmine,andTypeScriptWritingaminimumviableunittestsuiteforasimplecomponentWritingaminimumviableend-to-endtestsuiteforasimpleapplicationUnittestingasynchronousserviceUnittestingacomponentwithaservicedependencyusingstubsUnittestingacomponentwithaservicedependencyusingspies

IntroductionWritingtestsislikebrushingyourteeth.Youcangetawaywithskippingitforawhile,butit'llcatchupwithyoueventually.

Theworldoftestingisawashwithconflictingideologies,platitudes,andgrandstanding.What'smore,thereisadizzyingarrayoftoolsavailablethatallowyoutowriteandrunyourtestsindifferentways,automateyourtests,oranalyzeyourtestcoverageorcorrectness.Ontopofthat,eachdeveloper'sutilityandstyleoftestingisunique;someonehackingawayatapre-seedstartupwillnothavethesamerequirementsasadeveloperthatispartofalargeteaminsideaFortune500company.

ThegoalofthischapteristowalkyouthroughtheavailabletestingutilitiesthattheAngular2frameworkcomeswithoutofthebox,aswellassomestrategiesfordeployingtheseutilities.TherecipeswillfocusonunittestsratherthanE2Etests,asanoverwhelmingmajorityofrobusttestsuiteswillbeunittests.

CreatingaminimumviableunittestsuitewithKarma,Jasmine,andTypeScriptBeforeyoujumpintotheintricaciesoftestinganAngular2application,it'simportanttofirstexaminethesupportinginfrastructurethatwillmakerunningthesetestspossible.ThebulkofofficialAngularresourcesoffertestsontopofKarmaandJasmine,andthere'snoreasontorocktheboatonthisone,asthesearebothfinetestingtools.Thatsaid,it'sawholenewworldwithTypeScriptinvolved,andusingthemintestswillrequiresomeconsiderations.

Thisrecipewilldemonstratehowtoputtogetheraverysimpleunittestsuite.ItwilluseKarmaandJasmineasthetestinfrastructure,TypeScriptandWebpackforcompilationandmodulesupport,andPhantomJSasthetestbrowser.Forthoseunfamiliarwiththesetools,here'sabitaboutthem:

Karmaisaunittestrunner.YourunteststhroughKarmaonthecommandline.Ithastheabilitytostartupatestserverthatunderstandshowtofindtestfilesandservethemtothetestbrowser.Jasmineisatestframework.Whenyouusekeywordssuchas"it"and"describe,"rememberthattheyarepartofJasmineunittests.ItintegrateswithKarmaandunderstandshowtoexposeandrunthetestsyou'vewritten.PhantomJSisaheadlesswebkitbrowser.(HeadlessmeansitrunsasaprocessthatdoesnothaveavisibleuserinterfacebutstillconstructsaDOMandhasaJSruntime.)Unittestsrequireabrowsertorun,astheJavaScriptunittestsaredesignedtoexecuteinsideabrowserruntime.Karmasupportsalargenumberofbrowserpluginstorunthetestson,includingstandardbrowserssuchasChromeandFirefox.Ifyouweretoincorporatethesebrowserplugins,Karmawouldstartupaninstanceofthebrowserandrunthetestsinsideit.Forthepurposeofcreatingaminimumviableunittestsuite,youarefinedoingthetestinginsideaheadlessbrowser,whichwillcleanlyreportitsresultstothecommandline.Ifyouwanttorunyourtestsinsideanactualbrowser,Karmawillexposetheserverataspecifiedport,whichyoucanaccessdirectly,forexample,visitinghttp://localhost:9876inthedesiredtestbrowser.

Note



GettingreadyStartoutwithapackage.jsonfile:

[package.json]

{}

Note

ThisstillneedstobeavalidJSONfile,asnpmneedstobeabletoparseitandaddtoit.

Howtodoit...Startoffbycreatingthefilethatwillbetested.YouintendtouseTypeScript,sogoaheadanduseitssyntaxhere:

[src/article.ts]

exportclassArticle{

title:string=

"LabMiceStrikeforImprovedWorkingConditions,Benefits"

}

Writingaunittest

WiththeArticleclassdefined,youcannowimportitintoanewtestfile,article.spec.ts,anduseit.

Note

Jasminetestfiles,byconvention,aresuffixedwith.spec.ts.TestfilesgeneratedbytheAngularCLIwillexistalongsidethefiletheytest,butbynomeansisthismandatory.YoucandefineyourconventioninsideyourKarmaconfigurationlateron.

StartoffbyimportingtheArticleclassandcreateanemptyJasminetestsuiteusingdescribe:

[src/article.spec.ts]

import{Article}from'./article';

describe('Articleunittests',()=>{

});

Note

describedefinesaspecsuite,whichincludesastringtitlecalledArticleunittests,andananonymousfunction,whichcontainsthesuite.Aspecsuitecanbenestedinsideanotherspecsuite.

Insideadescribesuitefunction,youcandefinebeforeEachandafterEach,whicharefunctionsthatexecutebeforeandaftereachunittestisdefinedinsidethesuite.Therefore,itispossibletodefinenestedsetuplogicforunittestsusingnesteddescribeblocks.

Insidethespecsuitefunction,writetheunittestthatisusingit:

[src/article.spec.ts]

import{Article}from'./article';

describe('Articleunittests',()=>{

it('Hascorrecttitle',()=>{

leta=newArticle();

expect(a.title)

.toBe("LabMiceStrikeforImprovedWorkingConditions,

Benefits");

});

});

NotethatboththecodeandthetestarewritteninTypeScript.

ConfiguringKarmaandJasmine

First,installKarma,theKarmaCLI,Jasmine,andtheKarmaJasmineplugin:

npminstallkarmajasmine-corekarma-jasmine--save-dev

npminstallkarma-cli-g

Alternately,ifyouwanttosaveafewkeystrokes,thefollowingisequivalent:

npmi-Dkarmajasmine-corekarma-jasmine

npmikarma-cli-g

Karmareadsitsconfigurationoutofakarma.conf.jsfile,socreatethatnow:

[karma.conf.js]

module.exports=function(config){

config.set({

})

}

KarmaneedstoknowhowtofindthetestfilesandalsohowtouseJasmine:

[karma.conf.js]


config.set({

frameworks:[

'jasmine'

],

files:[

'src/*.spec.js'

],

plugins:[

'karma-jasmine',

]

})

}

ConfiguringPhantomJS

PhantomJSallowsyoutodirecttestsentirelyfromthecommandline,butKarmaneedstounderstandhowtousePhantomJS.InstallthePhantomJSplugin:

npminstallkarma-phantomjs-launcher--save-dev

Next,incorporatethispluginintotheKarmaconfig:

[karma.conf.js]


config.set({

browsers:[

'PhantomJS'

],

frameworks:[

'jasmine'

],

files:[

'src/*.spec.js'

],

plugins:[

'karma-jasmine',

'karma-phantomjs-launcher'

]

})

}

KarmanowknowsithastorunthetestsinPhantomJS.

CompilingfilesandtestswithTypeScript

Ifyou'repayingattentionclosely,you'llnotethattheKarmaconfigisreferencingtestfilesthatdonotexist.Sinceyou'reusingTypeScript,youmustcreatethesefiles.InstallTypeScriptandtheJasminetypedefinitions:

npminstalltypescript@types/jasmine--save-dev

Addscriptdefinitionstoyourpackage.json:

[package.json]

{

"scripts":{

"tsc":"tsc",

"tsc:w":"tsc-w"

},

"devDependencies":{

"@types/jasmine":"^2.5.35",

"jasmine-core":"^2.5.2",

"karma":"^1.3.0",

"karma-cli":"^1.0.1",

"karma-jasmine":"^1.0.2",

"karma-phantomjs-launcher":"^1.0.2",


}

}

Createatsconfig.jsonfile.Sinceyou'refinewiththecompiledfilesresidinginthesamedirectory,asimpleonewilldo:

[tsconfig.json]

{

"compilerOptions":{

"target":"es5",


"moduleResolution":"node"

}

}

Tip

Youwouldprobablynotdoitthiswayforaproductionapplication,butforaminimumviablesetup,thiswilldoinapinch.Aproductionapplicationwouldmostlikelyputcompiledfilesintoanentirelydifferentdirectory,frequentlynameddist/.

IncorporatingWebpackintoKarma

Ofcourse,you'llneedawayofresolvingmoduledefinitionsforcodeandtests.Karmaisn'tcapableofdoingthisonitsown,soyou'llneedsomethingtodothis.Webpackisperfectlysuitableforsuchatask,andKarmahasaterrificpluginthatallowsyoutopreprocessyourtestfilesbeforetheyreachthebrowser.

InstallWebpackanditsKarmaplugin:

npminstallwebpackkarma-webpack--save-dev

ModifytheKarmaconfigtospecifyWebpackasthepreprocessor.Thisallowsyourmoduledefinitionstoberesolvedproperly:

[karma.conf.js]


config.set({

browsers:[

'PhantomJS'

],

frameworks:[

'jasmine'

],

files:[

'src/*.spec.js'

],

plugins:[

'karma-webpack',

'karma-jasmine',

'karma-phantomjs-launcher'

],

preprocessors:{

'src/*.spec.js':['webpack']

}

})

}

Writingthetestscript

YoucankickofftheKarmaserverwiththefollowing:

karmastartkarma.conf.js

Thiswillinitializethetestserverandrunthetests,watchingforchangesandrerunningthetests.However,thissidestepsthefactthattheTypeScriptfilesrequirecompilationinthefilesthatKarmaiswatching.TheTypeScriptcompileralsohasafilewatcherthatwillrecompileonthefly.Youwouldlikebothofthesetorecompilewheneveryousavechangestoasourcecodefile,soitmakessensetorunthemsimultaneously.Theconcurrentlypackageissuitableforthistask.

Note

concurrentlynotonlyallowsyoutorunmultiplecommandsatonce,butalsotokillthemallatonce.Withoutit,akillsignalfromthecommandlinewouldonlytargetwhicheverprocesswasrunmostrecently,ignoringtheprocessthatisrunninginthebackground.

Installconcurrentlywiththefollowing:

npminstallconcurrently--save-dev

Finally,buildyourtestscripttorunKarmaandtheTypeScriptcompilersimultaneously:

[package.json]

{

"scripts":{

"test":"concurrently'npmruntsc:w''karmastart

karma.conf.js'",

"tsc":"tsc",

"tsc:w":"tsc-w"

},

"devDependencies":{

"@types/jasmine":"^2.5.35",


"jasmine-core":"^2.5.2",

"karma":"^1.3.0",

"karma-cli":"^1.0.1",

"karma-jasmine":"^1.0.2",

"karma-phantomjs-launcher":"^1.0.2",

"karma-webpack":"^1.8.0",


"webpack":"^1.13.2"

}

}

Withthis,youshouldbeabletorunyourtests:

npmtest

Ifeverythingisdonecorrectly,theKarmaservershouldbootupandrunthetests,outputtingthefollowing:

PhantomJS2.1.1(Linux0.0.0):Executed1of1SUCCESS(0.038secs/0.001

secs)

Howitworks...KarmaandJasmineworktogethertodelivertestfilestothetestbrowser.TypeScriptandWebpackaretaskedwithconvertingyourTypeScriptfilesintoaJavaScriptformatthatwillbeusablebythetestbrowser.

There'smore...AninterestingconsiderationofthissetupishowexactlyTypeScriptishandled.

BoththecodeandtestfilesarewritteninTypeScript,whichallowsyoutousetheES6modulenotation,asopposedtosomemix-and-matchstrategy.However,thisleavesyouwithsomechoicestomakeonhowthetestsetupshouldwork.

Thetestsneedtobeabletousedifferentpiecesofyourapplicationinapiecemealfashion,asopposedtothestandardapplicationsetupwhereallthemodulesgetpulledtogetheratonce.ThisrecipehadTypeScriptindependentlycompilethe.tsfiles,anditthendirectedKarmatowatchtheresultant.jsfiles.Thisisperhapseasiertocomprehendbysomeonewhoiseasingintotests,butitmightnotbethemostefficientwaytogoaboutit.KarmaalsosupportsTypeScriptplugins,whichallowyoutopreprocessthefilesintoTypeScriptbeforehandingthemofftotheWebpackpreprocessor.

Karmasupportsthechainingofpreprocesssteps,whichwillbeusefulifyouwanttocompiletheTypeScriptontheflyaspartofpreprocessing.

SeealsoWritingaminimumviableunittestsuiteforasimplecomponentshowsyouabasicexampleofunittestingAngular2componentsUnittestingasynchronousservicedemonstrateshowaninjectionismockedinunittestsUnittestingacomponentwithaservicedependencyusingStubsshowshowyoucancreateaservicemocktowriteunittestsandavoiddirectdependenciesUnittestingacomponentwithaservicedependencyusingSpiesshowshowyoucankeeptrackofservicemethodinvocationsinsideaunittest

WritingaminimumviableunittestsuiteforasimplecomponentUnittestsarethebreadandbutterofyourapplicationtestingprocess.Theyexistasacompaniontoyoursourcecode,andmostofthetime,thebulkofyourapplicationtestswillbeunittests.Theyarelightweight,runquickly,areeasytoreadandreasonabout,andcangivecontextastohowthecodeshouldbeusedandhowitmightbehave.

SettingupKarma,Jasmine,TypeScript,andAngular2alongwithalltheconnectingconfigurationsbetweenthemisabitofanimposingtask;itwasdeemedtobeoutofthescopeofthischapter.It'snotaveryinterestingdiscussiontogetallofthemtoworktogether,especiallysincetherearealreadysomanyexampleprojectsthathaveputtogethertheirownsetupsforyou.It'sfarmoreinterestingtodivedirectlyintotheteststhemselvesandseehowtheycanactuallyinteractwithAngular2.

Note



GettingreadyThisrecipewillassumeyouareusingaworkingAngular2testingenvironment.TheoneprovidedintheapplicationgeneratedbytheAngularCLIisideal.Testscanberuninthisenvironmentwiththefollowingcommandinsidetheprojectdirectory:

ngtest

Beginwiththefollowingcomponent:

[src/app/article/article.component.ts]


@Component({

selector:'app-article',

template:`

<h1>

{{title}}

</h1>

`

})


title:string='CaptainHookSuesOverSporkSnafu';

}

Yourgoalistoentirelyfleshoutarticle.component.spec.tstotestthisclass.

Howtodoit...ThesimplestpossibletestyoucanthinkofistheonethatwillsimplycheckthatyouareabletoinstantiateaninstanceofArticleComponent.Beginwiththattest:

[src/app/article/article.component.spec.ts]


describe('Component:Article',()=>{

it('shouldcreateaninstance',()=>{

letcomponent=newArticleComponent();

expect(component).toBeTruthy();

});

});

Nothingtrickyisgoingonhere.SinceArticleComponentisjustaplainoldTypeScriptclass,nothingispreventingyoufromcreatinganinstanceandinspectingitinthememory.

However,forittoactuallybehavelikeanAngular2component,you'llneedsomeothertools.

UsingTestBedandasync

WhenyoutrytopuppetanAngular2environmentforthecomponentinatest,thereareanumberofconsiderationsyou'llneedtoaccountfor.First,Angular2unittestsheavilyrelyuponTestBed,whichcanbethoughtofasyourtestingmultitool.

ThedenominationofunittestswhendealingwithacomponentinvolvesComponentFixture.TestBed.createComponent()willcreateafixturewrappinganinstanceofthedesiredcomponent.

Tip

Theneedforfixturesiscenteredinhowunittestsaresupposedtowork.AnArticleComponentdoesnotmakesensewheninstantiatedasitwaswiththeinitialtestyouwrote.ThereisnoDOMelementtoattachto,norunningapplication,andsoon.Itdoesn'tmakesenseforthecomponentunitteststohaveanexplicitdependencyonthesethings.So,ComponentFixtureisAngular'swayoflettingyoutestonlytheconcernsofthecomponentasitwouldnormallyexist,withoutworryingaboutallthemessinessofitsinnatedependencies.

TheTestBedfixture'sasynchronousbehaviormandatesthatthetestlogicisexecutedinsideanasync()wrapper.

Tip

Theasync()wrappersimplyrunsthetestinsideitsownzone.Thisallowsthetestrunnertowait

foralltheasynchronouscallsinsidethetesttocompletethembeforeendingthetest.

BeginbyimportingTestBedandasyncfromtheAngulartestingmoduleandputtogethertheskeletonfortwomoreunittests:


import{TestBed,async}from'@angular/core/testing';






});

it('shouldhavecorrecttitle',async(()=>{

}));

it('shouldrendertitleinanh1tag',async(()=>{

}));

});

Nowthatyouhavetheskeletonsforthetwotestsyou'dliketowrite,it'stimetouseTestBedtodefinethetestmodule.Angular2componentsarepairedwithamoduledefinition,butwhenperformingunittests,you'llneedtousetheTestBedmodule'sdefinitionforthecomponenttoworkproperly.ThiscanbedonewithTestBed.configureTestModule(),andyou'llwanttoinvokethisbeforeeachtest.

Jasmine'sdescribeallowsyoutogroupbeforeEachandafterEachinsideit,anditisperfectforusehere:








});

describe('Async',()=>{

beforeEach(()=>{

TestBed.configureTestingModule({

declarations:[

ArticleComponent

],

});

});


}));


}));

});

});

CreatingaComponentFixture

TestBedgivesyoutheabilitytocreateafixture,butyouhaveyettoactuallydoit.You'llneedafixtureforboththeasynctests,soitmakessensetodothisinbeforeEachtoo:





letfixture;




});


beforeEach(()=>{


declarations:[

ArticleComponent

],

});

fixture=TestBed.createComponent(ArticleComponent);

}));

afterEach(()=>{

fixture=undefined;

});


}));


}));

});

});

Tip

Here,fixtureisassignedtoundefinedintheafterEachteardown.Thisistechnically

superfluousforthepurposeofthesetests,butitisgoodtogetintothehabitofperformingarobustteardownofsharedvariablesinunittests.Thisisbecauseoneofthemostfrustratingthingstodebuginatestsuiteistestvariablebleed.Afterall,thesearejustfunctionsrunninginasequenceinabrowser.

Nowthatthefixtureisdefinedforeachtest,youcanuseitsmethodstoinspecttheinstantiatedcomponentindifferentways.

Forthefirsttest,you'dliketoinspecttheArticleComponentobjectitselffromwithinComponentFixture.ThisisexposedwiththecomponentInstanceproperty:





letexpectedTitle='CaptainHookSuesOverSporkSnafu';

letfixture;




});


beforeEach(async(()=>{


declarations:[

ArticleComponent

],

});


}));

afterEach(()=>{

fixture=undefined;

});


expect(fixture.componentInstance.title)

.toEqual(expectedTitle);

}));


}));

});

});

Forthesecondtest,youwantaccesstotheDOMthatthefixturehasattachedthecomponentinstanceto.TherootelementthatthecomponentistargetingisexposedwiththenativeElement

property:






letfixture;




});




declarations:[

ArticleComponent

],

});


}));

afterEach(()=>{

fixture=undefined;

});




}));


expect(fixture.nativeElement.querySelector('h1')

.textContent).toContain(expectedTitle);

}));

});

});

Ifyourunthesetests,youwillnoticethatthelasttestwillfail.Thetestseesanemptystringinside<h1></h1>.Thisisbecauseyouarebindingavalueinthetemplatetoacomponentmember.Sincethefixturecontrolstheentireenvironmentsurroundingthecomponent,italsocontrolsthechangedetectionstrategy—which,here,istonotrununtilitistoldtodoso.YoucantriggeraroundofchangedetectionusingthedetectChanges()method:






letfixture;




});




declarations:[

ArticleComponent

],

});


}));

afterEach(()=>{

fixture=undefined;

});




}));


fixture.detectChanges();

expect(fixture.nativeElement.querySelector('h1')

.textContent).toContain(expectedTitle);

}));

});

});

Withthis,youshouldseeKarmarunandpassallthreetests.

Howitworks...Whenitcomestotestingcomponents,fixtureisyourfriend.Itgivesyoutheabilitytoinspectandmanipulatethecomponentinanenvironmentthatitwillbehavecomfortablyin.Youarethenabletomanipulatetheinstancesofinputmadetothecomponent,aswellasinspecttheiroutputandresultantbehavior.

Thisisthecoreofunittesting:the"thing"youaretesting—here,acomponentclass—shouldbetreatedasablackbox.Youcontrolwhatgoesintothebox,andyourtestsshouldmeasureanddefinewhattheyexpecttocomeoutofthebox.Ifthetestsaccountforallthepossiblecasesofinputandoutput,thenyouhaveachieved100percentunittestcoverageofthatthing.

SeealsoCreatingaminimumviableunittestsuitewithKarma,Jasmine,andTypeScriptgivesyouagentleintroductiontounittestswithTypeScriptUnittestingasynchronousservicedemonstrateshowaninjectionismockedinunittestsUnittestingacomponentwithaservicedependencyusingStubsshowshowyoucancreateaservicemocktowriteunittestsandavoiddirectdependenciesUnittestingacomponentwithaservicedependencyusingSpiesshowshowyoucankeeptrackofservicemethodinvocationsinsideaunittest

Writingaminimumviableend-to-endtestsuiteforasimpleapplicationEnd-to-endtesting(ore2eforshort)isontheotherendofthespectrumasfarasunittestingisconcerned.Theentireapplicationexistsasablackbox,andtheonlycontrolsatyourdisposal—forthesetests—areactionstheusermighttakeinsidethebrowser,suchasfiringclickeventsornavigatingtoapage.Similarly,thecorrectnessoftestsisonlyverifiedbyinspectingthestateofthebrowserandtheDOMitself.

Moreexplicitly,anend-to-endtestwill(insomeform)startupanactualinstanceofyourapplication(orasubsetofit),navigatetoitinanactualbrowser,dostufftoapage,andlooktoseewhathappensonthepage.It'sprettymuchascloseasyouaregoingtogettohavinganactualpersonsitdownanduseyourapplication.

Inthisrecipe,you'llputtogetheraverybasicend-to-endtestsuitesothatyoumightbetterunderstandtheconceptsinvolved.

Note



GettingreadyYou'llbeginwiththecodefilescreatedintheminimumviableapplicationrecipefromChapter8,ApplicationOrganizationandManagement.Themostimportantfilesthatyou'llbeeditinghereareAppComponentandpackage.json:

[package.json]

{

"scripts":{



"postinstall":"npminstall-s@types/node@types/core-js",

"tsc":"tsc",

"tsc:w":"tsc-w"

},

"dependencies":{






"core-js":"^2.4.1",


"rxjs":"5.0.0-beta.12",

"systemjs":"0.19.27",

"zone.js":"^0.6.23"

},

"devDependencies":{




}

}



@Component({


template:'<h1>AppComponenttemplate!</h1>'

})

exportclassAppComponent{}

Howtodoit...TheAngularteammaintainstheProtractorproject,whichbymanyaccountsisthebestwaytogoaboutperformingend-to-endtestsonyourapplications,atleastinitially.Itcomeswithalargenumberofutilitiesoutoftheboxtomanipulatethebrowserwhenwritingyourtests,andexplicitintegrationswithAngular2,soit'saterrificplacetostart.

GettingProtractorupandrunning

ProtractorreliesonSeleniumtoautomatethebrowser.ThespecificsofSeleniumaren'tespeciallyimportantforthepurposeofcreatingaminimumviablee2etestsuite,butyouwillneedtoinstallaJavaruntime:

sudoapt-getinstallopenjdk-8-jre

Tip

IrunUbuntu,sotheOpenJDKJavaRuntimeEnvironmentV8issuitableformypurposes.Yourdevelopmentsetupmaydiffer.RuntimesfordifferentoperatingsystemscanbefoundonOracle'swebsite.

Protractoritselfcanbeinstalledfromnpm,butitshouldbeglobal.You'llbeusingitwithJasmine,soinstallitanditsTypeScripttypingsaswell:

npminstalljasmine-core@types/jasmine--save-dev

npminstallprotractor-g

Tip

Youmayneedtofiddlewiththisconfiguration.Sometimes,itmayworkifyouinstallprotractorlocallyratherthanglobally.Errorsinvolvingwebdriver-managerarepartoftheprotractorpackage,sotheywillmostlikelybeinvolvedwhereyourprotractorpackageinstallationisaswell.

Itshouldcomeasnosurprisethatprotractorisconfiguredwithafile,socreateitnow:

[protractor.conf.js]

exports.config={

specs:[

'./e2e/**/*.e2e-spec.ts'

],

capabilities:{

'browserName':'chrome'

},

baseUrl:'http://localhost:3000/',

framework:'jasmine',

}

Noneofthesesettingsshouldsurpriseyou:

Thee2etestfilesaregoingtoliveinane2e/directoryandwillbesuffixedwith.e2e-spec.ts

ProtractorisgoingtospinupaChromeinstancethatitwillpuppeteerwithSeleniumTheserveryou'regoingtospinupwillexistatlocalhost:3000,andalltheURLsinsidetheProtractortestswillberelativetothisTheProtractortestswillbewrittenwiththeJasminesyntax

Forsimplicity,theserveryouarestartingupfortheend-to-endtestswillbethesamelite-serveryou'vebeenusingallalong.Whenitstartsup,lite-serverwillopenupabrowserwindowofitsown,whichwillprovetobeabitannoyinghere.SinceitisathinwrapperforBrowserSync,youcanconfigureittonotdothisbysimplydirectingitnottodosoinaconfigfilethatisonlyusedwhenrunninge2etests.

Createthisfilenowinsidethetestdirectory:

[e2e/bs-config.json]

{

"open":false

}

Note

Thelite-serverwrapperwon'tfindthisautomatically,butyou'lldirectittothefileinamoment.

MakingProtractorcompatiblewithJasmineandTypeScript

First,createatsconfig.jsonfileinsidethetestdirectory:

[e2e/tsconfig.json]

{

"compilerOptions":{

"target":"es5",


"moduleResolution":"node"

}

}

Next,createtheactuale2etestfileskeleton:

[e2e/app.e2e-spec.ts]

describe('AppE2ETestSuite',()=>{

it('shouldhavethecorrecth1text',()=>{

});

});

ThisusesthestandardJasminesyntaxtodeclareaspecsuiteandanemptytestwithinit.

Beforefleshingoutthetest,youneedtoensurethatProtractorcanactuallyusethisfile.Installthets-nodepluginsothatProtractorcanperformthecompilationandusethesefilesine2etests:

npminstallts-node--save-dev

Next,instructProtractortousethistocompilethetestsourcefilesintoausableformat.Thiscanbedoneinitsconfigfile:


exports.config={

specs:[


],

capabilities:{


},



beforeLaunch:function(){

require('ts-node').register({

project:'e2e'

});

}

}

Withallthis,you'releftwithaworkingbutemptyend-to-endtest.

Buildingapageobject

AnexcellentconventionthatIhighlyrecommendusingisthepageobject.

Note

Theideabehindthisisthatallofthelogicsurroundingtheinteractionwiththepagecanbeextractedintoitsownpageobjectclass,andtheactualtestbehaviorcanusethisabstractedpageobjectinsidetheclass.ThisallowstheteststobewrittenindependentlyoftheDOMstructureorroutingdefinitions,whichmakesforsuperiortestmaintenance.What'smore,itmakesyourteststotallyindependentofProtractor,whichmakesiteasiershouldyouwanttochangeyourend-to-endtestrunner.

Forthissimpleend-to-endtest,you'llwanttospecifyhowtoarriveatthispageandhowtoinspectittogetwhatyouwant.Definethepageobjectasfollowswithtwomembermethods:

[e2e/app.po.ts]

import{browser,element,by}from'protractor';

exportclassAppPage{

navigate(){

browser.get('/');

}

getHeaderText(){

returnelement(by.css('app-rooth1')).getText();

}

}

navigate()instructsSeleniumtotherootpath(which,asyoumayrecall,isbasedonlocalhost:3000),andgetHeaderText()inspectsaDOMelementforitstextcontents.

Note

Notethatbrowser,element,andbyareallutilitiesimportedfromtheprotractormodule.Moreonthislaterintherecipe.

Writingthee2etest

Withalloftheinfrastructureinplace,youcannoweasilywriteyourend-to-endtest.You'llwanttoinstantiateanewpageobjectforeachtest:

[e2e/app.e2e-spec.ts]

import{AppPage}from'./app.po';

describe('AppE2ETestSuite',()=>{

letpage:AppPage;

beforeEach(()=>{

page=newAppPage();

});

it('shouldhavethecorrecth1text',()=>{

page.navigate();

expect(page.getHeaderText())

.toEqual('AppComponenttemplate!');

});

});

Scriptingthee2etests

Finally,you'llwanttogiveyourselftheabilitytoeasilyruntheend-to-endtestsuite.Seleniumisoftenbeingupdated,soitbehovesyoutoexplicitlyupdateitbeforeyourunthetests:

[package.json]

{

"scripts":{

"pree2e":"webdriver-managerupdate&&tsc",

"e2e":"concurrently'npmrunlite---c=e2e/bs-config.json'

'protractorprotractor.conf.js'",



"postinstall":"npminstall-s@types/node@types/core-js",

"tsc":"tsc",

"tsc:w":"tsc-w"

},

"dependencies":{

...

},

"devDependencies":{

...

}

}

Finally,Angular2needstointegratewithProtractorandbeabletotellitwhenthepageisreadytobeinteractedwith.ThisrequiresonemoreadditiontotheProtractorconfiguration:


exports.config={

specs:[


],

capabilities:{


},



useAllAngular2AppRoots:true,

beforeLaunch:function(){

require('ts-node').register({

project:'e2e'

});

}

}

That'sall!Youshouldnowbeabletoruntheend-to-endtestsuitebyinvokingitwiththecorrespondingnpmscript:

npmrune2e

Thiswillstartupalite-serverinstance(withoutstartingupitsdefaultbrowser),andprotractorwillrunthetestsandexit.

Howitworks...Atthetopoftheapp.po.tspageobjectfile,youimportedthreetargetsfromProtractor:browser,element,andby.Here'sabitaboutthesetargets:

browserisaprotractorglobalobjectthatallowsyoutoperformbrowser-levelactions,suchasvisitingURLs,waitingforeventstooccur,andtakingscreenshots.elementisaglobalfunctionthattakesaLocatorandreturnsanElementFinder.ElementFinderisthepointofcontacttointeractwiththematchingDOMelement,ifitexists.byisaglobalobjectthatexposesseveralLocatorfactories.Here,theby.css()locatorfactoryperformsananalogueofdocument.querySelector().

Tip

TheentireProtractorAPIcanbefoundathttp://www.protractortest.org/#/api.

Thereasonforwritingtheteststhiswaymayfeelstrangetoyou.Afterall,it'sarealbrowserrunningarealapplication,soitmightmakesensetoreachforDOMmethodsandthelike.

ThereasonforusingtheProtractorAPIinsteadissimple:thetestcodeyouarewritingisnotbeingexecutedinsidethebrowserruntime.Instead,ProtractorishandingofftheseinstructionstoSelenium,whichinturnwillexecutetheminsidethebrowserandreturntheresults.Thus,thetestcodeyouwritecanonlyindirectlyinterfacewiththebrowserandtheDOM.

http://www.protractortest.org/#/api

There'smore...Thepurposeofthisrecipewastoassembleaverysimpleend-to-endtestsuitesothatyoucangetafeelofwhatgoesonbehindthescenesinsomeform.Whiletheteststhemselveswillappearmoreorlessastheydohere,regardlessofthetestinfrastructuretheyarerunningon,theinfrastructureitselfisfarfrombeingoptimal;anumberofchangesandadditionscouldbemadetomakeitmorerobust.

Whenrunningunittests,itisoftenusefulfortheunitteststodetectthechangesinfilesandrunthemagainimmediately.Alargepartofthisisbecauseunittestsshouldbeverylightweight.Anydependenciesontherestoftheapplicationaremockedorabstractedawaysothataminimalamountofcodecanberuntoprepareyourunittestenvironment.Thus,thereislittlecosttorunningasuiteofunittestsinasequence.

End-to-endtests,ontheotherhand,behaveintheoppositeway.Theydoindeedrequiretheentireapplicationtobeconstructedandrun,whichcanbecomputationallyexpensive.Pagenavigations,resettingtheentireapplication,initializingandclearingauthentication,andotheroperationsthatmightcommonlybeperformedinanend-to-endtestcantakealongtime.Therefore,itdoesn'tmakeasmuchsenseheretoruntheend-to-endtestswithafilewatcherobservingforchangesmadetothetests.

SeealsoCreatingaminimumviableunittestsuitewithKarma,Jasmine,andTypeScriptgivesyouagentleintroductiontounittestswithTypeScript

UnittestingasynchronousserviceAngular2servicetypesareessentiallyclassesdesignatedforinjectability.Theyareeasytotestsinceyouhaveagreatdealofcontroloverhowandwheretheyareprovided,andconsequently,howmanyinstancesyou'llbeabletocreate.Therefore,testsforserviceswillexistlargelyastheywouldforanynormalTypeScriptclass.

It'llbebetterifyouarefamiliarwiththecontentofthefirstfewrecipesofthischapterbeforeyouproceedfurther.

Note



GettingreadySupposeyouwanttobuilda"magiceightball"service.Beginwiththefollowingcode,withaddedcommentsforclarity:

[src/app/magic-eight-ball.service.ts]


@Injectable()

exportclassMagicEightBallService{

privatevalues:Array<string>;

privatelastIndex:number;

constructor(){

//Initializethevaluesarray

//Musthaveatleasttwoentries

this.values=[

'Askagainlater',

'Outlookgood',

'Mostlikely',

'Don'tcountonit'

];

//Initializewithanyvalidindex

this.lastIndex=this.getIndex();

}

privategetIndex():number{

//Returnarandomindexforthis.values

returnMath.floor(Math.random()*this.values.length);

}

reveal():string{

//Generateanewindex

letnewIdx=this.getIndex();

.

//Checkiftheindexwasthesameoneusedlasttime

if(newIdx===this.lastIndex){

//Ifso,shiftupone(wrappingaround)inthearray

//Thisisstillrandombehavior

newIdx=(++newIdx)%this.values.length;

}

//Savetheindexthatyouarenowusing

this.lastIndex=newIdx;

//Accessthestringandreturnit

returnthis.values[newIdx];

}

}

Thereareseveralthingstonoteabouthowthisservicebehaves:

ThisservicehasseveralprivatemembersbutonlyonepublicmembermethodTheserviceisrandomlyselectedfromanarrayTheserviceshouldn'treturnthesamevaluetwiceinarow

Thewayyourunittestsarewrittenshouldaccountfortheseaswellascompletelytestthebehaviorofthisservice.

Howtodoit...Beginbycreatingtheframeworkofyourtestfile:

[src/app/magic-eight-ball.service.spec.ts]

import{TestBed}from'@angular/core/testing';

import{MagicEightBallService}from

'./magic-eight-ball.service';

describe('Service:MagicEightBall',()=>{

beforeEach(()=>{


providers:[

MagicEightBallService

]

});

});

});

Sofar,noneofthisshouldsurpriseyou.MagicEightBallServiceisaninjectable;itneedstobeprovidedinsideamoduledeclaration,whichisdonehere.However,toactuallyuseitinsideaunittest,youneedtoperformaformalinjectionsincethisiswhatwouldberequiredtoaccessitfrominsideacomponent.Thiscanbeaccomplishedwithinject:


import{TestBed,inject}from'@angular/core/testing';




beforeEach(()=>{


providers:[


]

});

});

it('shouldbeabletobeinjected',inject([MagicEightBallService],

(magicEightBallService:MagicEightBallService)=>{

expect(magicEightBallService).toBeTruthy();

})

);

});

Offtoagoodstart,butthisdoesn'tactuallytestanythingaboutwhattheserviceisdoing.Next,writeatestthatensuresthatastringofnon-zerolengthisbeingreturned:






beforeEach(()=>{


providers:[


]

});

});




})

);

it('shouldreturnastringwithnonzerolength',

inject([MagicEightBallService],


letresult=magicEightBallService.reveal();

expect(result).toEqual(jasmine.any(String));

expect(result.length).toBeGreaterThan(0);

})

);

});

Finally,youshouldwriteatesttoensurethatthetwovaluesreturnedarenotthesame.Sincethismethodisrandom,youcanrunituntilyouareblueinthefaceandstillnotbetotallysure.However,checkingthis50timesinarowisafinewaytobefairlycertain:






beforeEach(()=>{


providers:[


]

});

});




})

);

it('shouldreturnastringwithnonzerolength',






})

);

it('shouldnotreturnthesamevaluetwiceinarow',



letlast;

for(leti=0;i<50;++i){

letnext=magicEightBallService.reveal();

expect(next).not.toEqual(last);

last=next;

}

})

);

});

Terrific!Allthesetestshavepassed;you'vedoneagoodjobbuildingsomeincrementalanddescriptivecodecoverageforyourservice.

Howitworks...Theinjecttestfunctionperformsdependencyinjectionforyoueachtimeitisinvoked,usingthearrayofinjectableclassespassedasthefirstargument.Thearrowfunctionthatispassedasitssecondargumentwillbehaveinessentiallythesamewayasacomponentconstructor,whereyouareabletousethemagicEightBallServiceparameterasaninstanceoftheservice.

Tip

Oneimportantdifferencefromhowitisinjectedcomparedtoacomponentconstructoristhatinsideacomponentconstructor,youwouldbeabletousethis.magicEightBallServicerightaway.Withrespecttoinjectionintounittests,itdoesnotautomaticallyattachtothis.

There'smore...Importantconsiderationsforunittestingarewhattestsshouldbewrittenandhowtheyshouldproceed.Respectingtheboundariesofpublicandprivatemembersisessential.Sincethesetestsarewritteninawaythatonlyutilizesthepublicmembersoftheservice,theauthorisfreetogoaboutchanging,extending,orrefactoringtheinternalsoftheservicewithoutworryingaboutbreakingorneedingtoupdatethetests.Awell-designedclasswillbefullytestablefromitspublicinterface.

Tip

Thisnotionbringsupaninterestingphilosophicalpointregardingunittesting.Youshouldbeabletodescribethebehaviorofawell-formedserviceasafunctionofitspublicmembers.Similarly,awell-formedserviceshouldthenberelativelyeasytowriteunittests,giventhattheformerstatementistrue.

Ifitisthenthecasethatyoufindyourunittestsaredifficulttowrite—forexample,youareneedingtoreachintoaprivatememberoftheservicetotestitproperly—thenconsiderthenotionthatyourservicemightnotbeaswelldesignedasitcouldbe.

Inshort,ifit'shardtotest,thenyoumighthavewrittenaclassinaweirdway.

Testingwithoutinjection

Anobservantdeveloperwillnoteherethattheserviceyouaretestingdoesn'thaveanymeaningfuldependenceoninjection.Injectingitintovariousplacesintheapplicationsurelyprovidesitwithaconsistentway,buttheservicedefinitioniswhollyunawareofthisfact.Afterall,instantiationisinstantiation,andthisservicedoesn'tappeartobemorethananinjectableclass.Therefore,itiscertainlypossibletonotbotherinjectingtheserviceatallandmerelyinstantiatingitusingthenewkeyword:





letmagicEightBallService;

beforeEach(()=>{

magicEightBallService=newMagicEightBallService();

});

it('shouldbeabletobeinjected',()=>{


});

it('shouldreturnastringwithnonzerolength',()=>{




});

it('shouldnotreturnthesamevaluetwiceinarow',()=>{

letlast;

for(leti=0;i<50;++i){

letnext=magicEightBallService.reveal();

expect(next).not.toEqual(last);

last=next;

}

});

});

Ofcourse,thisrequiresthatyoukeeptrackofwhethertheservicecaresaboutwhetherornotithasbeeninjectedanywhere.

SeealsoUnittestingacomponentwithaservicedependencyusingstubsshowshowyoucancreateaservicemocktowriteunittestsandavoiddirectdependenciesUnittestingacomponentwithaservicedependencyusingspiesshowshowyoucankeeptrackofservicemethodinvocationsinsideaunittest

UnittestingacomponentwithaservicedependencyusingstubsStandalonecomponenttestingiseasy,butyouwillrarelyneedtowritemeaningfultestsforacomponentthatexistsinisolation.Moreoftenthannot,thecomponentwillhaveoneormanydependencies,andwritinggoodunittestsisthedifferencebetweendelightanddespair.

Note



GettingreadySupposeyoualreadyhavetheservicefromtheUnittestingasynchronousservicerecipe.Inaddition,youhaveacomponent,whichmakesuseofthisservice:

[src/app/magic-eight-ball/magic-eight-ball.component.ts]



'../magic-eight-ball.service';

@Component({

selector:'app-magic-eight-ball',

template:`

<button(click)="update()">Clickme!</button>

<h1>{{result}}</h1>

`

})

exportclassMagicEightBallComponent{

result:string='';

constructor(privatemagicEightBallService_:MagicEightBallService){}

update(){

this.result=this.magicEightBallService_.reveal();

}

}

Yourobjectiveistowriteasuiteofunittestsforthiscomponentwithoutsettinganexplicitdependencyontheservice.

Howtodoit...Beginwithaskeletonofyourtestfile:

[src/app/magic-eight-ball/magic-eight-ball.component.spec.ts]


import{MagicEightBallComponent}from

'./magic-eight-ball.component';



describe('Component:MagicEightBall',()=>{


}));

afterEach(()=>{

});

it('shouldbeginwithnotext',async(()=>{

}));

it('shouldshowtextafterclick',async(()=>{

}));

});

You'llfirstwanttoconfigurethetestmodulesothatitproperlyprovidestheseimportedtargetsinthetest:








letfixture;



declarations:[

MagicEightBallComponent

],

providers:[


]

});

fixture=TestBed.createComponent(MagicEightBallComponent);

}));

afterEach(()=>{

fixture=undefined;

});


}));


}));

});

Stubbingaservicedependency

Injectingtheactualserviceworksjustfine,butthisisn'twhatyouwanttodo.Youdon'twanttoactuallyinjectaninstanceofMagicEightBallServiceintothecomponent,asthatwouldsetadependencyontheserviceandmaketheunittestmorecomplicatedthanitneedstobe.However,MagicEightBallComponentneedstoimportsomethingthatresemblesaMagicEightBallService.Anexcellentsolutionhereistocreateaservicestubandinjectitinitsplace:








letfixture;

letmagicEightBallResponse='Answerunclear';

letmagicEightBallServiceStub={

reveal:()=>magicEightBallResponse

};



declarations:[


],

providers:[

{

provide:MagicEightBallService,

useValue:magicEightBallServiceStub

}

]

});


}));

afterEach(()=>{

fixture=undefined;

});


}));


}));

});

Acomponentcan'ttellthedifferencebetweentheactualserviceanditsmock,soitwillbehavenormallyinthetestconditionsyou'vesetup.

Next,youshouldwritethepreclicktestbycheckingthatthefixture'snativeElementcontainsnotext:








letfixture;

letgetHeaderEl=()=>

fixture.nativeElement.querySelector('h1');




};



declarations:[


],

providers:[

{



}

]

});


}));

afterEach(()=>{

fixture=undefined;

});



expect(getHeaderEl().textContent).toEqual('');

}));


}));

});

Triggeringeventsinsidethecomponentfixture

Forthesecondtest,youshouldtriggeraclickonthebutton,instructthefixturetoperformchangedetection,andtheninspecttheDOMtoseethatthetextwasproperlyinserted.Sinceyouhavedefinedthetextthatthestubwillreturn,youcanjustcompareitdirectlywiththat:







import{By}from'@angular/platform-browser';


letfixture;

letgetHeaderEl=()=>

fixture.nativeElement.querySelector('h1');




};

...



}));


fixture.debugElement.query(By.css('button'))

.triggerEventHandler('click',null);


expect(getHeaderEl().textContent)

.toEqual(magicEightBallResponse);

}));

});

You'llnotethatthisneedstoimportandusetheBy.csspredicate,whichisrequiredtoperformDebugElementinspections.

Howitworks...Asdemonstratedinthedependencyinjectionchapter,providingastubtothecomponentisnodifferentthanprovidingaregularvaluetothecoreapplication.

Thestubhereisasinglefunctionthatreturnsastaticvalue.Thereisnoconceptofrandomlyselectingfromtheservice'sarrayofstrings,andtheredoesn'tneedtobe.Theunittestsfortheserviceitselfensurethatitisbehavingproperly.Instead,theonlyvalueprovidedbytheservicehereistheinformationitpassesbacktothecomponentforinterpolationbackintothetemplate.

SeealsoWritingaminimumviableunittestsuiteforasimplecomponentshowsyouabasicexampleofunittestingAngular2componentsUnittestingasynchronousservicedemonstrateshowinjectionismockedinunittestsUnittestingacomponentwithaservicedependencyusingspiesshowshowyoucankeeptrackofservicemethodinvocationsinsideaunittest

UnittestingacomponentwithaservicedependencyusingspiesTheabilitytostuboutservicesisuseful,butitcanbelimitinginanumberofways.Itcanalsobetedious,asthestubsyoucreatemustremainuptodatewiththepublicinterfaceoftheservice.Anotherexcellenttoolatyourdisposalwhenwritingunittestsisthespy.

Aspyallowsyoutoselectafunctionormethod.Italsohelpsyoucollectinformationaboutifandhowitwasinvokedaswellashowitwillbehaveonceitisinvoked.Itissimilarinconcepttoastubbutallowsyoutohaveamuchmorerobustunittest.

Note



GettingreadyBeginwiththecomponenttestsyouwroteinthelastrecipe:









letfixture;

letgetHeaderEl=()=>fixture.nativeElement.querySelector('h1');




};



declarations:[


],

providers:[

{



}

]

});


}));

afterEach(()=>{

fixture=undefined;

});




}));







}));

Howtodoit...Insteadofusingastub,configurethetestmoduletoprovidetheactualservice:









letfixture;





declarations:[


],

providers:[


]

});


}));

afterEach(()=>{

fixture=undefined;

});




}));







}));

});

Settingaspyontheinjectedservice

Yourgoalistouseamethodspytointerceptcallstoreveal()ontheservice.Theproblemhere,however,isthattheserviceisbeinginjectedintothecomponent;therefore,youdon'thavea

directabilitytogetareferencetotheserviceinstanceandsetaspyonit.Fortunately,thecomponentfixtureprovidesthisforyou:









letfixture;






declarations:[


],

providers:[


]

});


magicEightBallService=fixture.debugElement.injector

.get(MagicEightBallService);

}));

afterEach(()=>{

fixture=undefined;

magicEightBallService=undefined;

});

...

});

Next,setaspyontheserviceinstanceusingspyOn().Configurethespytointerceptthemethodcallandreturnthestaticvalueinstead:









letfixture;




letrevealSpy;



declarations:[


],

providers:[


]

});




revealSpy=spyOn(magicEightBallService,'reveal')

.and.returnValue(magicEightBallResponse);

}));

afterEach(()=>{

fixture=undefined;


revealSpy=undefined;

});

...

});

Withthisspy,youarenowcapableofseeinghowtherestoftheapplicationinteractswiththiscapturedmethod.Addanewtest,andcheckthatthemethodiscalledonceandreturnsthepropervalueafteraclick(thisalsopullstheclickingactionintoitsowntesthelper):









letfixture;




letrevealSpy;

letclickButton=()=>{



};



declarations:[


],

providers:[


]

});




revealSpy=spyOn(magicEightBallService,'reveal')

.and.returnValue(magicEightBallResponse);

}));

afterEach(()=>{

fixture=undefined;


revealSpy=undefined;

});




}));

it('shouldcallrevealafteraclick',async(()=>{

clickButton();

expect(revealSpy.calls.count()).toBe(1);

expect(revealSpy.calls.mostRecent().returnValue)

.toBe(magicEightBallResponse);

}));


clickButton();




}));

});

Note

NotethatdetectChanges()isonlyrequiredtoresolvethedatabinding,nottoexecuteeventhandlers.

Howitworks...Jasminespiesactasmethodinterceptorsandarecapableofinspectingeverythingaboutthegivenmethodinvocation.Itcantrackifandwhenamethodwascalled,whatargumentsitwascalledwith,howmanytimesitwascalled,howitshouldbehave,andsoon.Thisisextremelyusefulwhentryingtoremovedependenciesfromcomponentunittests,asyoucanmockoutthepublicinterfaceoftheserviceusingspies.

There'smore...Spiesarenotbeholdentoreplacethemethodoutright.Here,itisusefultobeabletopreventtheexecutionfromreachingtheinternalsoftheservice,butitisnotdifficulttoimaginecaseswhereyouwouldonlywanttopassivelyobservetheinvocationofacertainmethodandallowtheexecutiontocontinuenormally.

Forsuchapurpose,insteadofusing.and.returnValue(),Jasmineallowsyoutouse.and.callThrough(),whichwillallowtheexecutiontoproceeduninterrupted.

SeealsoWritingaminimumviableunittestsuiteforasimplecomponentshowsyouabasicexampleofunittestingAngular2componentsUnittestingasynchronousservicedemonstrateshowinjectionismockedinunittestsUnittestingacomponentwithaservicedependencyusingstubsshowshowyoucancreateaservicemocktowriteunittestsandavoiddirectdependencies

Chapter10.PerformanceandAdvancedConceptsThischapterwillcoverthefollowingrecipes:

UnderstandingandproperlyutilizingenableProdModewithpureandimpurepipesWorkingwithzonesoutsideAngularListeningforNgZoneeventsExecutionoutsidetheAngularzoneConfiguringcomponentstouseexplicitchangedetectionwithOnPushConfiguringViewEncapsulationformaximumefficiencyConfiguringtheAngular2RendererServicetousewebworkersConfiguringapplicationstouseahead-of-timecompilationConfiguringanapplicationtouselazyloading

IntroductionAngular2wasatotalrebuildforanumberofreasons,butoneofthebiggestoneswascertainlyefficiency.Theframeworkthatemergedfromtheashesisasleekandelegantone,butnotwithoutitscomplexities.

Thischapterservestoexploresomeofthenewfeaturesthatitbuildsuponandhowtomosteffectivelyemploythemtostreamlineyourapplication.

UnderstandingandproperlyutilizingenableProdModewithpureandimpurepipesAngular2'schangedetectionprocessisanelegantbutficklebeastthatischallengingtounderstandatfirst.Whileitoffershugeefficiencygainsoverthe1.xframework,thegainscancomeatacost.ThedevelopmentmodeofAngularisactivatedbydefault,whichwillalertyouwhenyourcodeisindangerofbehavinginawaythatdefeatsthechangedetectionefficiencygains.Inthisrecipe,you'llimplementafeaturethatviolatesAngular'schangedetectionschema,correctit,andsafelyuseenableProdMode.

Note



GettingreadyBeginwithasimplecomponent:

[src/app/app.component.ts]


@Component({


template:`

<input#t>

<button(click)="update(t.value)">Save</button>

<h1>{{title}}</h1>

`

})

exportclassAppComponent{

title:string='';

update(newTitle:string){

this.title=newTitle;

}

}

Whenthebuttoninthiscomponentisclicked,itgrabsthevalueoftheinputandinterpolatesittotheheadertag.Asis,thisimplementationisperfectlysuitable.

Howtodoit...TodemonstratetherelevanceofenableProdMode,you'llneedtointroduceabehaviorthatenableProdModewouldmask.Morespecifically,thismeansapieceofyourapplicationwillbehavedifferentlywhentwosequentialpassesofchangedetectionarerun.

Note

Thereareasignificantnumberofwaystoimplementthis,butforthepurposeofthisrecipe,you'llimplementanonsensicalpipethatchangeseverytimeit'sused.

Generatingaconsistencyerror

Createanonsensicalpipe,namelyAddRandomPipe:

[src/app/add-random.pipe.ts]

import{Pipe,PipeTransform}from'@angular/core';

@Pipe({

name:'addRandomPipe'

})

exportclassAddRandomPipeimplementsPipeTransform{

transform(value:string):string{

returnvalue+Math.random();

}

}

Next,takethispipeandintroduceittoyourcomponent:



import{AddRandomPipe}from'./add-random.pipe';

@Component({


template:`

<input#t>


<h1>{{title|addRandomPipe}}</h1>

`

})


title:string='';



}

}

Thiswon'tcreateanerroryet,though.

Note

Angularwillindeedrunthechangedetectionprocesstwice,soitmightseemmysteriousthatitdoesn'tcreateanerror.Eventhoughthepipewillgenerateanewoutputeverytimeitstransformmethodisinvoked,Angularissmartenoughtorecognizethattheinputoftheinterpolationaren'tchanging,andtherefore,reevaluatingthepipeisunnecessary.Thisiscalleda"pure"pipe,whichistheAngulardefault.

InordertogetAngulartoevaluatethepipeduringeachchangedetectioncycle,specifythepipeas"impure":



@Pipe({

name:'addRandomPipe',

pure:false

})


transform(value:string):string{

returnvalue+Math.random();

}

}

Nowthefunbegins.Whenyouruntheapplication,youshouldseesomethingsimilartothefollowingerrormessage:

EXCEPTION:Errorin./AppComponentclassAppComponent-inlinetemplate:3:8

causedby:Expressionhaschangedafteritwaschecked.Previousvalue:

'0.0495151713435904'.Currentvalue:'0.9266277919907477'.

Introducingchangedetectioncompliance

Theerrorisbeingthrownassoonastheapplicationstartsup,beforeyou'reevengivenachancetopressthebutton.ThismeansthatAngularisdetectingthebindingmismatchasthecomponentisbeinginstantiatedandrenderedforthefirsttime.

Note

You'vecreatedapipethatintentionallychangeseachtime,soyourgoalistoinstructAngulartonotbothercheckingthepipeoutputtwiceagainstitselfuponcomponentinstantiation.

Atthispoint,you'vemanagedtogetAngulartothrowaconsistencyerror,whichitdoesbecauseit'srunningchangedetectioncheckstwiceandgettingdifferentresults.SwitchingonenableProdModeatthispointwouldstoptheerrorsinceAngularwouldthenonlyrunchange

detectiononceandnotbothertocheckforconsistency.ThisisbecauseittrustsyoutohaveverifiedcompliancebeforeusingenableProdMode.TurningonenableProdModetomaskconsistencyerrormessagesisabitlikecominghometofindyourhouseisonfireandthendecidingtogoonavacation.

Angularallowsyoutocontrolthisbyspecifyingthechangedetectionstrategyforthecomponent.Thedefaultistoalwaysperformachangedetectioncheck,butthiscanbeoverriddenwiththeOnPushconfiguration:


import{Component,ChangeDetectionStrategy}


import{AddRandomPipe}from'./add-random.pipe';

@Component({


template:`

<input#t>


<h1>{{title|addRandomPipe}}</h1>

`,

changeDetection:ChangeDetectionStrategy.OnPush

})


title:string='';



}

}

Nowwhenthecomponentinstanceisinitialized,youshouldnolongerseetheconsistencyerror.

SwitchingonenableProdMode

SinceyourapplicationisnowcompliantwithAngular'schangedetectionmechanism,you'refreetouseenableProdMode.Thisletsyourapplicationrunchangedetectiononceeachtime.Thisisbecauseitassumestheapplicationwillarriveinastablestate.

Inyourapplication'sbootstrappingfile,invokeenableProdModebeforeyoustartbootstrapping:

[src/main.ts]



import{enableProdMode}from'@angular/core';

import{AppModule}from'./app/';

enableProdMode();

Howitworks...enableProdModewillconfigureyourapplicationinanumberofways,includingsilencingerrorandinformationalerrormessages,amongothers;however,noneofthesewaysisasvisibleasthesuppressionofthesecondarychangedetectionprocess.

There'smore...Thereareotherwaystomitigatethisconsistencyproblem.Forexample,supposeyouwanttogenerateapipethatwillappendarandomnumbertotheinput.Itdoesn'tnecessarilyneedtobeadifferentrandomnumbereverysingletime;rather,youcanhaveoneforeachuniqueinputwithinacertainperiodoftime.Suchasituationcouldallowyoutohaveapipethatutilizessomesortofcachingstrategy.Ifthepipecachesresultsforaperiodoftimelongerthanchangedetectiontakestocomplete(whichisnotverylong),thenalteringthechangedetectionstrategyofthecomponentisnotnecessary.Thisisbecausemultiplepipeinvocationswillyieldanidenticalresponse.Forexample,refertothefollowingcode:



@Pipe({

name:'addRandomPipe',

pure:false

})


cache:Object={};

transform(input:string):string{

letvalue=this.cache[input];

if(!value||value.expire<Date.now()){

value={

text:input+Math.random(),

//Expiresinonesecond

expire:Date.now()+1000

}

this.cache[input]=value;

}

returnvalue.text;

}

}

Withthis,youcansafelystrikechangeDetection:ChangeDetectionStrategy.OnPushfromComponentMetadataofyourAppComponentandyouwillnotseeanyconsistencyerrors.

SeealsoConfiguringtheAngular2rendererservicetousewebworkersguidesyouthroughtheprocessofsettingupyourapplicationtorenderonawebworkerConfiguringapplicationstouseahead-of-timecompilationguidesyouthroughhowtocompileanapplicationduringthebuild

WorkingwithzonesoutsideAngularWorkingwithzonesentirelyinsideoftheAngularframeworkconcealswhattheyarereallydoingbehindthescenes.Itwouldbeadisservicetoyou,thereader,tojustglossovertheunderlyingmechanism.Inthisrecipe,you'lltakethevanillazone.jsimplementationoutsideofAngularandmodifyitabitinordertoseehowAngularcanmakeuseofit.

TherewillbenoAngularusedinthisrecipe,onlyzone.jsinsideasimpleHTMLfile.Furthermore,thisrecipewillbewritteninplainES5JavaScriptforsimplicity.

Note



GettingreadyBeginwiththefollowingsimpleHTMLfile:

[index.html]

<buttonid="button">Clickme</button>

<buttonid="add">Addlistener</button>

<buttonid="remove">Removelistener</button>

<script>

varbutton=document.getElementById('button');

varadd=document.getElementById('add');

varremove=document.getElementById('remove');

varclickCallback=function(){

console.log('click!');

};

setInterval(function(){

console.log('setinterval!');

},1000);

add.addEventListener('click',function(){

button.addEventListener('click',clickCallback);

});

remove.addEventListener('click',function(){

button.removeEventListener('click',clickCallback);

});

</script>

Eachofthesecallbackshaslogstatementsinsidethemsoyoucanseewhentheyareinvoked:

setIntervalcallsitsassociatedlistenereverysecondClickingonClickmecallsitslistenerifitisattachedClickingonAddlistenerattachesaclicklistenertothebuttonClickingonRemovelistenerremovestheclicklistener

Note

There'snothingspecialgoingonhere,becauseallofthesearedefaultbrowserAPIs.Themagicofzones,asyouwillsee,isthatthezonebehaviorcanbeintroducedaroundthiswithoutmodifyinganycode.

Howtodoit...First,addthezone.jsscripttothetopofthefile:

[index.html]

<scriptsrc="https://cdnjs.cloudflare.com/ajax/libs/zone.js/0.6.26/zone.js">

</script>




...

Note

There'snospecialsetupneededforzone.js,butitneedstobeaddedbeforeyousetlistenersordoanythingthatcouldhaveasynchronousimplications.Angularneedsthisdependencytobeaddedbeforeitisinitialized.

AddingthisscriptintroducesZonetotheglobalnamespace.zone.jshasalreadycreatedaglobalzoneforyou.Thiscanbeaccessedwiththefollowing:

Zone.current

Forkingazone

Theglobalzoneisn'tdoinganythinginterestingyet.Tocustomizeazone,you'llneedtocreateyourownbyforkingtheonewehaveandrunningrelevantcodeinsideit.Dothisasfollows:

[index.html]

<script

src="https://cdnjs.cloudflare.com/ajax/libs/zone.js/0.6.26/zone.js">

</script>




<script>




Zone.current.fork({}).run(function(){



};



},1000);



});



});

});

</script>

Behaviorally,thisdoesn'tchangeanythingfromtheperspectiveoftheconsole.fork()takesanemptyZoneSpecobjectliteral,whichyouwillmodifynext.

OverridingzoneeventswithZoneSpec

Whenapieceofcodeisruninazone,youareabletoattachbehaviorsatimportantpointsintheasynchronousbehaviorflow.Here,you'lloverridefourzoneevents:

scheduleTask

invokeTask

hasTask

cancelTask

You'llbeginwithscheduleTask.DefineanoverridemethodinsideZoneSpec.Overridesusetheeventnamesprefixedwithon:

[index.html]

<script

src="https://cdnjs.cloudflare.com/ajax/libs/zone.js/0.6.26/zone.js">

</script>




<script>




Zone.current.fork({

onScheduleTask:function(zoneDelegate,zone,targetZone,task){

console.log('schedule');

zoneDelegate

.scheduleTask(targetZone,task);

}

}).run(function(){



};



},1000);



});



});

});

</script>

Withthisaddition,youshouldseethatthezonerecognizesthatthreetasksarebeingscheduled.Thisshouldmakesense,asyouaredeclaringthreeinstancesthatcangenerateasynchronousactions:setInterval,addEventListener,andremoveEventListener.IfyouclickonAddlistener,you'llseeitschedulethefourthtaskaswell.

Note

zoneDelegate.scheduleTask()isrequiredbecauseyouareactuallyoverwritingwhatthezoneisusingforthathandler.Ifyoudon'tperformthisaction,theschedulerhandlerwillexitbeforeactuallyschedulingthetask.

Theoppositeofschedulingataskiscancelingit,sooverridethateventhandlernext:

[index.html]

Zone.current.fork({



zoneDelegate


},

onCancelTask:function(zoneDelegate,zone,targetZone,task){

console.log('cancel');

zoneDelegate

.cancelTask(targetZone,task);

}

}).run(function(){

...

});

Acanceleventoccurswhenascheduledtaskisdestroyed,inthisexample,whenremoveEventListener()isinvoked.IfyouclickonAddlistenerandthenRemovelistener,

you'llseeacanceleventoccur.

Theschedulingoftasksisvisibleduringthestartup,buteachtimeabuttonisclickedorasetIntervalhandlerisexecuted,youdon'tseeanythingbeinglogged.Thisisbecauseschedulingatask,whichoccursduringregistration,isdistinctfrominvokingatask,whichiswhentheasynchronouseventactuallyoccurs.

Todemonstratethis,addaninvokeTaskoverride:

[index.html]

Zone.current.fork({



zoneDelegate


},



zoneDelegate


},

onInvokeTask:function(zoneDelegate,zone,targetZone,task,

applyThis,applyArgs){

console.log('invoke');

zoneDelegate

.invokeTask(targetZone,task,applyThis,applyArgs);

}

}).run(function(){

...

});

Withthisaddition,youshouldnowbeabletoseeaconsolelogeachtimeataskisinvoked—forabuttonclickorasetIntervalcallback.

Sofar,you'vebeenabletoseewhenthezonehastasksscheduledandinvoked,butnow,dothereverseofthistodetectwhenallthetaskshavebeencompleted.ThiscanbeaccomplishedwithhasTask,whichcanalsobeoverridden:

[index.html]

Zone.current.fork({



zoneDelegate


},



zoneDelegate


},

onInvokeTask:function(zoneDelegate,zone,targetZone,task,

applyThis,applyArgs){

console.log('invoke');

zoneDelegate

.invokeTask(targetZone,task,applyThis,applyArgs);

},

onHasTask:function(zoneDelegate,zone,targetZone,isEmpty){

console.log('has');

zoneDelegate.hasTask(targetZone,isEmpty);

}

}).run(function(){

...

});

TheisEmptyparameterofonHasTaskhasthreeproperties:eventTask,macroTask,andmicroTask.ThesethreepropertiesmaptoBooleansdescribingwhethertheassociatedqueueshaveanytasksinsidethem.

Withthesefourcallbacks,youhavesuccessfullyinterceptedfourimportantpointsinthecomponentlifecycle:

Whenatask"generator"isscheduled,whichmaygeneratetasksfrombrowserortimereventsWhenatask"generator"iscanceledWhenataskisactuallyinvokedHowtodeterminewhetheranytasksarescheduledandofwhattype

Howitworks...Theconceptthatformsthecoreofzonesistheinterceptionofasynchronoustasks.Moredirectly,youwanttheabilitytoknowwhenasynchronoustasksarebeingcreated,howmanythereare,andwhenthey'redone.

zone.jsaccomplishesthisbyshimmingalltherelevantbrowsermethodsthatareresponsibleforsettingupasynchronoustasks.Infact,allthemethodsusedinthismethod—setInterval,addEventListener,andremoveEventListener—areallshimmedsothatthezonetheyareruninsideisawareofanyasynchronoustaskstheymightaddtothequeue.

There'smore...TobegintorelatethistoAngular,you'llneedtotakeastepbacktoexaminethezoneecosystem.

Understandingzone.run()

You'llnoticeinthisexamplethatinvokeisprintedforeachasynchronousaction,evenforthosethatwereregisteredinsideanotherasynchronousaction.Thisisthepowerofzones.Anythingdoneinsidethezone.run()blockwillcascadewithinthesamezone.Thisway,thezonecankeeptrackofanunbrokensegmentofasynchronousbehaviorwithoutanoceanofboilerplatecode.

Microtasksandmacrotasks

Thisactuallyhasnothingtodowithzone.jsatallbutratherwithhowthebrowsereventloopworks.Alltheeventsgeneratedbyyouinthisexample—clicks,timerevents,andsoon—aremacrotasks.Thatis,thebrowserrespectstheirhandlersasasynchronous,blockingsegmentofcode.Thecodethatexecutesaroundthesetasks—thezone.jscallbacks,forexample—aremicrotasks.Theyaredistinctfrommacrotasksbutarestillsynchronouslyexecutedaspartoftheentire"turn"forthatmacrotask.

Note

Amacrotaskmaygeneratemoremicrotasksforitselfwithinitsownturn.

Oncethemicrotaskandmacrotaskqueuesareempty,thezonecanbeconsideredtobestable,sincethereisnoasynchronousbehaviortobeanticipated.ForAngular,thissoundslikeagreattimetoupdatetheUI.

Infact,thisisexactlywhatAngularisdoingbehindthescenes.Angularviewsthebrowserthroughthetask-centricgogglesofzone.jsandusesthisclevertooltodecidewhentogoaboutrendering.

SeealsoListeningforNgZoneeventsgivesabasicunderstandingofhowAngularisusingzonesExecutionoutsidetheAngularzoneshowsyouhowtoperformlong-runningoperationswithoutincurringazoneoverheadConfiguringcomponentstouseexplicitchangedetectionwithOnPushdescribeshowtomanuallycontrolAngular'schangedetectionprocess

ListeningforNgZoneeventsWiththeintroductionofAngular2comestheconceptofzones.Beforeyoubeginthisrecipe,IstronglyrecommendedyoutobeginbyworkingthroughtheWorkingwithzonesoutsideAngularrecipe.

zone.jszone.jsisalibrarythatAngular2directlydependsupon.ItallowsAngulartobebuiltuponazonethatallowstheframeworktointimatelymanageitsexecutioncontext.

Moreplainly,thismeansthatAngularcantellwhenasynchronousthingsarehappeningthatitmightcareabout.Ifthissoundsabitlikehow$scope.apply()wasrelevantinAngular1.x,youarethinkingintherightway.

NgZoneAngular2'sintegrationwithzonestakestheformoftheNgZoneservice,whichactsasasortofwrapperfortheactualAngularzones.ThisserviceexposesausefulAPIthatyoucantapinto.

Note



GettingreadyAllthatisneededforthisrecipeisacomponentintowhichtheNgZoneservicecanbeinjected:



@Component({


template:``

})


constructor(){

}

}

Howtodoit...BeginbyinjectingtheNgZoneserviceintoyourcomponent,whichismadeavailableinsidethecoreAngularmodule:


import{Component,NgZone}from'@angular/core';

@Component({


template:``

})


constructor(privatezone:NgZone){

}

}

TheNgZoneserviceexposesanumberofEventEmittersthatyoucanattachto.Sincezonesarecapableoftrackingasynchronousactivitywithinit,theNgZoneserviceexposestwoEventEmittersthatunderstandwhenanasynchronousactivitybecomesenqueuedanddequeuedasmicrotasks.

TheonUnstableEventEmitterletsyouknowwhenoneormoremicrotasksareenqueued;onStableisfiredwhenthethemicrotaskqueueisemptyandAngulardoesnotplantoenqueueanymore.

Addhandlerstoeach:



@Component({


template:``

})



zone.onStable.subscribe(()=>console.log('stable'));

zone.onUnstable.subscribe(()=>console.log('unstable'));

}

}

Terrific!However,thelogoutputofthisisquiteboring.Atapplicationstartup,you'llseethattheapplicationisreportedasstable,butnothingfurther.

Demonstratingthezonelifecycle

IfyouunderstandhowAngularuseszones,thelackofloggingshouldn'tsurpriseyou.There'snothingtogenerateasynchronoustasksinthiszone.Goaheadandaddsomebycreatingabuttonwithahandlerthatsetsatimeoutlogstatement:



@Component({


template:`<button(click)="foo()">foo</button>`

})



zone.onStable.subscribe(()=>console.log('stable'));

zone.onUnstable.subscribe(()=>console.log('unstable'));

}

foo(){

setTimeout(()=>console.log('timeouthandler'),1000);

}

}

Nowwitheachclick,youshouldseeanunstable-stablepair,followedbyanunstable-timeouthandler-stablesetonesecondlater.Thismeansyou'vesuccessfullytiedintoAngular'szoneemitters.

Howitworks...Inordertoobviatethenecessityofa$scope.apply()construct,Angularneedstheabilitytointelligentlydecidewhenitshouldchecktoseewhetherthestateoftheapplicationhaschanged.

Inanasynchronoussetting,suchasabrowserenvironment,thisseemslikeamessytaskatfirst.Somethingliketimedeventsandinputeventsare,bytheirverynature,difficulttokeeptrackof.Forexample,refertothefollowingcode:

element.addEventListener('click',_=>{

//dosomestuff

setInterval(_=>{

//dosomestuff

},1000);

});

Thiscodeiscapableofchangingthemodelintwodifferentplaces,bothofwhichareasynchronous.Codesuchasthisiswrittenallthetimeandinsomanydifferentplaces;it'sdifficulttoimagineawayofkeepingtrackofsuchcodewithoutsprinklingsomethinglike$scope.$apply()allovertheplace.

Theutilityofzone.js

Thebigideaofzonesistogiveyoutheabilitytograsphowandwhenthebrowserisperformingasynchronousactionsthatyoucareabout.

NgZoneiswrappingtheunderlyingzoneAPIforyouinsteadofexposingEventEmitterstothevariouspartsofthelifecycle,butthisshouldn'tconfuseyouonebit.Forthisexample,thelogoutputisdemonstratingthefollowing:

1. Theapplicationinitializesandexaminestheapplicationzone.Therearenotasksscheduled,soAngularemitsastableevent.

2. Youclickonthebutton.3. Thisgeneratesaclickevent,whichinturngeneratesataskinsidethezonetoexecutethe

clickhandler.Angularseesthisandemitsanunstableevent.4. Theclickhandlerisexecuted,schedulingataskin1second.5. Theclickhandleriscompleted,andtheapplicationonceagainhasnopendingtasks.Angular

emitsastableevent.6. OnesecondelapsesandthebrowsertimeraddsthesetTimeouthandlertothetaskqueue.

Sincethisisshimmedbythezone,Angularseesthisoccurandemitsanunstableevent.7. ThesetTimeouthandlerisexecuted.8. ThesetTimeouthandleriscompleted,andtheapplicationonceagainhasnopendingtasks.

Angularemitsastableevent.

SeealsoWorkingwithzonesoutsideAngularisanexcellentintroductiontohowzonesworkinthebrowserExecutionoutsidetheAngularzoneshowsyouhowtoperformlong-runningoperationswithoutincurringazoneoverheadConfiguringcomponentstouseexplicitchangedetectionwithOnPushdescribeshowtomanuallycontrolAngular'schangedetectionprocess

ExecutionoutsidetheAngularzoneTheutilityofzone.jsisterrific,sinceitworksautomatically,butaseasonedsoftwareengineerknowsthisoftencomesataprice.Thisisespeciallytruewhentheconceptofdatabindingcomesintoplay.

Inthisrecipe,you'lllearnhowtoexecuteoutsidetheAngularzoneandwhatbenefitsthisaffordsyou.

Note



Howtodoit...Tocompareexecutionindifferentcontexts,createtwobuttonsthatrunthesamecodeindifferentzonecontexts.Thebuttonsshouldcountto100withsetTimeoutincrements.Usetheperformanceglobaltomeasurethetimeittakes:



@Component({


template:`

<button(click)="runInsideAngularZone()">

RuninsideAngularzone

</button>

<button(click)="runOutsideAngularZone()">

RunoutsideAngularzone

</button>

`

})


progress:number=0;

startTime:number=0;

constructor(privatezone:NgZone){}

runInsideAngularZone(){

this.start();

this.step(()=>this.finish('InsideAngularzone'));

}

runOutsideAngularZone(){

this.start();

this.step(()=>this.finish('OutsideAngularzone'));

}

start(){

this.progress=0;

this.startTime=performance.now();

}

finish(location:string){

this.zone.run(()=>{

console.log(location);

console.log('Took'+

(performance.now()-this.startTime)+'ms');

});

}

step(doneCallback:()=>void){

if(++this.progress<100){

setTimeout(()=>{

this.step(doneCallback);

},10);

}else{

doneCallback();

}

}

}

Atthispoint,thetwobuttonswillbehaveidentically,asbothofthemarebeingexecutedinsidetheAngularzone.

InordertoexecuteoutsidetheAngularzone,you'llneedtousetherunOutsideAngular()methodexposedbyNgZone:

runInsideAngularZone(){

this.start();

this.step(()=>this.finish('InsideAngularzone'));

}

runOutsideAngularZone(){

this.start();

this.zone.runOutsideAngular(()=>{

this.step(()=>this.finish('OutsideAngularzone'));

});

}

Atthispoint,youcanrunbothofthemagainsidebysideandverifythattheystilltake(roughly)thesameamountoftimetoexecute.Thisshouldnotsurpriseyou,astheyarestillperformingthesametask.Theinclusionofzone.jsmeansthatthebrowserAPIsareshimmedoutsideAngular,soevenrunningthisoutsidetheAngularzonemeansitisstillrunninginsideazone.

Inordertoseeaperformancedifference,you'llneedtointroducesomebindinginsidethetemplate:



@Component({


template:`

<h3>Progress:{{progress}}%</h3>

<button(click)="runInsideAngularZone()">

RuninsideAngularzone

</button>

<button(click)="runOutsideAngularZone()">

RunoutsideAngularzone

</button>

`

})


...

}

Nowyoushouldbegintoseeasubstantivedifferencebetweentheruntimesofeachbutton.Thisshowsthatwhentheoverheadofbindingsiscausingtheapplicationtoslowdown,runOutsideAngular()hasthepotentialtoyieldsurprisinglysubstantiveperformanceoptimizations.

Howitworks...WhenyouexaminetheNgZonesource,you'llfindthatthe"outer"zoneismerelythetopmostbrowserzone.AngularforksthiszoneuponinitializationandbuildsuponittoyieldtheniceNgZoneservicewrapper.

However,becausezonesdonotdiscriminateintherealmofasynchronouscallbacksanddatabinding,eachinvocationofthesetTimeouthandlerinsidetheAngularzoneisrecognizedasaneventthathasimplicationsonthetemplaterenderingprocess.Ineveryinvocation,Angularseesanupdatetothebounddatafollowinganasynchronoustask,andproceedstorerendertheview.Whenthisisdone100times,itaddsuptoseveralhundredextramillisecondsofexecution.

WhenthisisrunoutsidetheAngularzone,AngularisnolongerawareofthesetTimeouttasksthatarebeingexecutedandsodoesnotrequirearerender.Upontheveryfinaliterationthough,invokeNgZone.run();thiswillcausetheexecutiontorejointheAngularzone.Angularseesthetaskandthemodifieddataandupdatesthebindingsaccordingly;thistimethough,thisisdoneonlyonce.

There'smore...Inthisrecipe,thefinish()methodinvokestherun()methodforboththeAngularzoneandthenon-Angularzone.Whenthezonethatthisisinvokeduponisalreadythecontextualzoneinwhichthetaskisbeingexecuted,usingrun()becomesredundantandiseffectivelyano-op.

SeealsoWorkingwithzonesoutsideAngularisanexcellentintroductiontohowzonesworkinthebrowserListeningforNgZoneeventsgivesabasicunderstandingofhowAngularisusingzonesConfiguringcomponentstouseexplicitchangedetectionwithOnPushdescribeshowtomanuallycontrolAngular'schangedetectionprocess

ConfiguringcomponentstouseexplicitchangedetectionwithOnPushTheconventionofAngular'sdataflow,inwhichdataflowsdownwardthroughthecomponenttreeandeventsfloatupwards,engenderssomeinterestingpossibilities.OneoftheseinvolvescontrollingwhenAngularshouldperformchangedetectionatagivennodeinthecomponenttree.

Note



GettingreadyBeginwiththefollowingsimpleapplication:





@Component({

selector:'root',

template:`

<button(click)="shareSubject.next($event)">Share!</button>

<article[shares]="shareEmitter"></article>

`

})


shareSubject:Subject<Event>=newSubject();

shareEmitter:Observable<Event>=

this.shareSubject.asObservable();

}


import{Component,Input,ngOnInit}from'@angular/core';


@Component({

selector:'article',

template:`

<h1>{{title}}</h1>

<p>Shares:{{count}}</p>

`

})

exportclassArticleComponentimplementsOnInit{

@Input()shares:Observable<Event>;

count:number=0;

title:string=

'InsuranceFraudGrowsInWakeofApplePieHubbub';

ngOnInit(){

this.shares.subscribe((e:Event)=>++this.count);

}

}

Thisverysimpleapplicationisjustusinganobservabletopassshareeventsdown,fromaparentcomponenttoachildcomponent.Thechildcomponentkeepstrackoftheclickeventcountandinterpolatesthiscounttothepage.

Yourobjectiveistomodifythissetupsothatthechildcomponentonlydetectsachangewhenaneventisemittedfromtheobservable.

Howtodoit...Outofthebox,Angularalreadyhasaveryrobustwayofdetectingchange:zones.Wheneverthereisaneventinsideazone,Angularrecognizesthatthiseventhasthepotentialtomodifytheapplicationinameaningfulway.Itthenperformschangedetectionfromthetopofthecomponenttreedowntothebottom,checkingwhetheranythingneedstobeupdatedinthechangedmodel.Sincedataonlyflowsdownward,thisisalreadyanextremelyefficientwayofhandlingit.

However,youmightliketoexertsomecontrolinthissituationsinceyoumaybeabletohand-optimizewhenchangedetectionshouldoccurinsideacomponent.Mostlikelyyouwillveryeasilybeabletotellwhenacomponentmayormaynotchange,basedonwhatishappeningaroundit.

ConfiguringtheChangeDetectionStrategy

Angularoffersyoutheoptionofchanginghowthechangedetectionschemeworks.IfyouwouldpreferthatAngularrefrainfromlisteningtozoneeventstokickoffaroundofchangedetection,youcaninsteadconfigureacomponenttoonlyperformchangedetectionwhenaninputischanged.ThiscanbedonebyconfiguringthecomponenttousetheOnPushstrategyinsteadofthedefault.

Surely,thiswilloccurlessoftenthanthefirehoseofbrowserevents.Ifthecomponentwillonlychangewhenaninputischanged,thenthiswillsaveAngularthetroubleofdoinganiterationofchangedetectiononthatcomponent.

ModifyArticleComponenttoinsteaduseOnPush:


import{Component,Input,ngOnInit,ChangeDetectionStrategy}



@Component({

selector:'article',

template:`

<h1>{{title}}</h1>


`,


})



count:number=0;

title:string=


ngOnInit(){

this.shares.subscribe((e:Event)=>++this.count);

}

}

Thissuccessfullychangesthestrategy,butthereisonesignificantproblemnow:thecountwillnolongerbeupdated.Thishappens,ofcourse,becausetheinputtothiscomponentisnotbeingchanged.

ThecountonlyupdatedbeforebecauseAngularwasseeingclickeventsonthebutton,whichcausedchangedetectiononArticleComponent.Now,Angularhasbeeninstructedtoignoretheseclickevents,eventhoughthecountinsidethechildcomponentisstillbeingupdatedfromtheobservablehandlers.

Requestingexplicitchangedetection

Youareabletoinjectareferencetothecomponent'schangedetector.Withthis,itexposesamethodthatallowsyoutoforcearoundofchangedetectionwheneveryoulike.Sincethemodelisbeingupdatedinsideanobservablehandler,thisseemslikeafineplacetotriggerthechangedetectionprocess:


import{Component,Input,ngOnInit,ChangeDetectionStrategy,

ChangeDetectorRef}from'@angular/core';


@Component({

selector:'article',

template:`

<h1>{{title}}</h1>


`,


})



count:number=0;

title:string=


constructor(privatechangeDetectorRef_:ChangeDetectorRef){}

ngOnInit(){

this.shares.subscribe((e:Event)=>{

++this.count;

this.changeDetectorRef_.markForCheck();

});

}

}

Nowyouwillseethecountgettingupdatedonceagain.

Howitworks...UsingOnPushessentiallyconvertsacomponenttooperatelikeablackbox.Iftheinputdoesn'tchange,thenAngularassumesthatthestateinsidethecomponentwillremainconstant,andthereforethereisnoneedtoproceedfurtherwithregardtodetectingachange.

Sincechangedetectionalwaysflowsfromtoptobottominthecomponenttree,therequestforchangedetectionusesmarkForCheck(),marksthecomponent'schangedetectortorunonlywhenAngularreachesthatcomponentinsidethetree.

There'smore...Thisisausefulpatternifyou'relookingtosqueezeadditionalperformancefromyourapplication,butinsomecases,doingthiscandevelopintoananti-pattern.TheneedtoexplicitlydefinewhenAngularshouldperformchangedetectioncanbecometediousasyourcomponentcodegrowsinsize.TherecanpotentiallybebugsthatarisefrommissingoneplacewheremarkForCheck()shouldhavebeeninvokedbutwasnot.Angular'schangedetectionstrategyisalreadyquiteperformantandrobust,sousethisconfigurationwisely.

SeealsoWorkingwithzonesoutsideAngularisanexcellentintroductiontohowzonesworkinthebrowserListeningforNgZoneeventsgivesabasicunderstandingofhowAngularisusingzonesExecutionoutsidetheAngularzoneshowsyouhowtoperformlong-runningoperationswithoutincurringazoneoverheadConfiguringViewEncapsulationformaximumefficiencyshowshowyoucanconfigurecomponentstoutilizetheshadowDOM

ConfiguringViewEncapsulationformaximumefficiencyAlthoughitmaysoundclichéd,Angular2wasbuiltforthebrowsersoftomorrow.Youcanpointtowhythisisthecaseinalargenumberofways,butthereisonewaywherethisisextremelytrue:componentencapsulation.

TheidealcomponentmodelforAngular2istheoneinwhichcomponentsareentirelysandboxed,saveforthefewpiecesthatareexternallyvisibleandmodifiable.Inthisrespect,itdoesabang-upjob,buteventhemostmodernbrowserslimititsabilitytostriveforsuchefficacy.ThisisespeciallytrueintherealmofCSSstyling.

SeveralfeaturesofAngular'scomponentstylingareespeciallyimportant:

YouareabletowritestylesthatareguaranteedtobeonlyapplicabletoacomponentYoucanexplicitlyspecifystylesthatshouldbeinheriteddownwardthroughthecomponenttreeYoucanspecifyanencapsulationstrategyonapiecewisebasis

Thereareanumberofinterestingwaystoaccomplishanefficientcomponentstylingschema.

Note



GettingreadyBeginwithasimpleapplicationcomponent:



@Component({


template:`

<h1>

{{title}}

</h1>

`,

styles:[`

h1{

color:red;

}

`]

})


title='appworks!';

}

Howtodoit...AngularwilldefaulttonotusingShadowDOMforcomponents,asthemajorityofbrowsersdonotsupportittoasatisfactorylevel.Thenextbestthing,whichitwilldefaultto,istoemulatethisstylingencapsulationbynestingyourselectors.Theprecedingcomponentiseffectivelytheequivalentofthefollowing:


import{Component,ViewEncapsulation}from'@angular/core';

@Component({


template:`

<h1>

{{title}}

</h1>

`,

styles:[`

h1{

color:red;

}

`],

encapsulation:ViewEncapsulation.Emulated

})


title='appworks!';

}

Emulatedstylingencapsulation

HowexactlydoesAngularperformthisemulation?Lookattherenderedapplicationtofindout.Yourcomponentwillappearsomethinglikethefollowing:

<app-root_nghost-mqf-1="">

<h1_ngcontent-mqf-1="">

appworks!

</h1>

</app-root>

Intheheadofthedocument:

<style>

h1[_ngcontent-mqf-1]{

color:red;

}

</style>

Thepictureshouldbeabitclearernow.Angularisassigningthiscomponentclass(notaninstance)auniqueID,andthestylesdefinedfortheglobaldocumentwillonlybeapplicableto

tagsthathavethematchingattribute.

Nostylingencapsulation

Ifthisencapsulationisn'tnecessary,youarefreetouseencapsulation:ViewEncapsulation.None.AngularwillhappilyskiptheuniqueIDassignmentstepforyou,givingyouavanilla:

<app-root>

<h1>

appworks!

</h1>

</app-root>

Intheheadofthedocument:

<style>

h1{

color:red;

}

</style>

Nativestylingencapsulation

Thebest,mostfuturistic,andleastsupportedmethodofgoingaboutthisistouseShadowDOMinstancestogoalongwitheachcomponentinstance.Thiscanbeaccomplishedusingencapsulation:ViewEncapsulation.Native.Now,yourcomponentwillrender:

<app-root>

#shadow-root

<style>

h1{

color:red;

}

</style>

<h1>

appworks!

</h1>

</app-root>

Howitworks...Angularissmartenoughtorecognizewhereitneedstoputyourstylesandhowtomodifythemtomakethemworkforyourcomponentconfiguration:

ForNoneandEmulated,stylesgointothedocumentheadForNative,stylesgoinlinewiththerenderedcomponentForNoneandNative,nostylemodificationsareneededForEmulated,stylesarerestrictedbyattributeselectors

There'smore...AnimportantconsiderationofViewEncapsulationchoicesisCSSperformance.ItiswellknownandentirelyintuitivethatCSSstylingismoreefficientwhenithastotraverseasmallerpartoftheDOMandhastomatchusingasimplerselector.

Emulatingcomponentencapsulationaddsanattributeselectortoeachandeverystylethatisdefinedforthatcomponent.Atscale,itisn'thardtoseehowthiscandegradeperformance.ShadowDOMelegantlysolvesthisproblembyofferingunmodifiedstylesinsidearestrictedpieceofDOM.Itsstylescannotescapebutcanbeapplieddownwardtoothercomponents.Furthermore,ShadowDOMcomponentscanbenestedandstrategicallyapplied.

SeealsoUnderstandingandproperlyutilizingenableProdModewithpureandimpurepipesdescribeshowtotakethetrainingwheelsoffyourapplicationConfiguringcomponentstouseexplicitchangedetectionwithOnPushdescribeshowtomanuallycontrolAngular'schangedetectionprocess

ConfiguringtheAngular2RenderertousewebworkersOneofthemostcompellingintroductionsinthenewrenditionoftheAngularframeworkisthetotalabstractionoftherenderingexecution.ThisstemsfromoneofthecoreideasofAngular:youshouldbeabletoseamlesslysubstituteoutanybehaviormoduleandreplaceitwithanother.This,ofcourse,meansthatAngularcannothaveanydependencybleedoutsideofthemodules.

OneplacethatAngularputsemphasisonbeingconfigurableisthelocationwherecodeexecutiontakesplace.Thisismanifestedinanumberofways,andthisrecipewillfocusonAngular'sabilitytoperformrenderingexecutionatalocationotherthaninsidethemainbrowser'sJavaScriptruntime.

Note



GettingreadyBeginwithsomesimpleapplicationelementsthatdonotyetformafullapplication:

[index.html]

<!DOCTYPEhtml>

<html>

<head>



<scriptsrc="system.src.js"></script>


</head>

<body>

<article></article>

<script>

System.import('system-config.js')

.then(function(){

System.import('main.ts');

});

</script>

</body>

</html>



@Component({

selector:'article',

template:`

<h2>{{title}}</h2>

`

})


title:string=

'SurveyIndicatesPlasticFunnelBestWaytoDrinkRareWine';

}

NotethatthisrecipeusesSystemJStohandlemodulesandTypeScripttranspilation,butthisismerelytokeepthedemonstrationsimple.AproperlycompiledapplicationcanuseregularJavaScripttoaccomplishthesamefeat,withnodependencyonSystemJS.

Thisrecipewillstartoffbyassumingyouhaveabasicknowledgeofwhatwebworkersareandhowtheywork.Thereisadiscussionoftheirpropertieslaterinthisrecipe.

Howtodoit...TheSystemJSstartupconfigurationkicksofftheapplicationfrommain.ts,soyou'llbeginthere.Insteadofbootstrappingtheapplicationinthisfileasyounormallywould,you'lluseanimportedAngularhelpertoinitializethewebworkerinstance:

[main.ts]

import{bootstrapWorkerUi}from"@angular/platform-webworker";

bootstrapWorkerUi(window.location.href+"loader.js");

Concernyourselfwiththeprecisedetailsofwhatthisisdoinglater,butthehigh-levelideaisthatthisiscreatingawebworkerinstancethatisintegratedwiththeAngularRenderer.

Note

RecallthatinitializingawebworkerrequiresapathtoitsstartupJSfile,andarelativepathinsidethisfilemightnotalwayswork;therefore,you'reusingthewindowlocationtoprovideanabsoluteURL.Thenecessityofthismaydifferbasedonyourdevelopmentsetup.

Sincethisfilereferencesawebworkerinitializationfilecalledloader.js,writeitnext.WorkerscannotbegivenaTypeScriptfile:

[loader.js]

importScripts(

"system.js",

"zone.js",

"reflect-metadata.js",

"./system-config.js");

System.import("./web-worker-main.ts");

Thisfilefirstimportsthesamefilesthatarelistedinsidethe<head>tagofindex.html.ThisshouldmakesensesincethewebworkerwillneedtoperformsomeofthedutiesofAngularbutwithoutdirectaccesstoanythingthatexistsinsidethemainJavaScriptruntime.Forexample,sincethiswebworkerwillberenderingacomponent,itneedstobeabletounderstandthe@Component({})notation,whichcannotbedonewithoutthereflect-metadataextension.

Justlikethemainapplication,thewebworkeralsohasaninitializationfile.Thistakestheformofweb-worker-main.ts:

[web-worker-main.ts]

import{AppModule}from'./app/app.module';

import{platformWorkerAppDynamic}

from'@angular/platform-webworker-dynamic';

platformWorkerAppDynamic().bootstrapModule(AppModule);

Comparedtoanormalmain.tsfile,thisfileshouldlookdelightfullyfamiliar.Angularprovidesyouwithatotallyseparateplatformmodule,butonethataffordsyouanidenticalAPI,whichyouareusingheretobootstraptheapplicationfromtheyet-to-be-definedAppModule.Definethisnext:

[app/app.module.ts]


import{WorkerAppModule}from'@angular/platform-webworker';



@NgModule({

imports:[

WorkerAppModule

],

bootstrap:[

ArticleComponent

],

declarations:[

ArticleComponent

]

})


SimilartohowyouwouldnormallyuseBrowserModulewithinaconventionaltop-levelappmodule,Angularprovidesaweb-worker-flavoredWorkerAppModulethathandlesallthenecessaryintegration.

Howitworks...Makenomistakeaboutwhatishappeninghere:yourapplicationisnowrunningontwoseparateJavaScriptthreads.

WebworkersarebasicallyjustreallydumbJavaScriptexecutionbuckets.Wheninitialized,theyaregivenaninitialpieceofJavaScripttorun,whichinthisexampletooktheformofloader.js/.Theyhavenounderstandingofwhatisgoingoninthemainbrowserruntime.Theycan'tinteractwiththeDOM,andyouareonlyabletocommunicatewiththemviaPostMessages.AngularbuildsanelegantabstractionontopofPostMessagestocreateabusinterface,anditisthisinterfacethatisusedtojointhetworuntimestogether.

IfyoulookintothePostMessagespecification,youwillnoticethatallofthedatapassedasthemessagemustbeserializedintoastring.HowthencanthisrenderingconfigurationpossiblyworkwiththeDOMinthemainbrowser,handlingeventsanddisplayingtheHTMLandthewebworkerperformingtherenderingonaDOMitcannottouch?

Theanswerissimple:Angularserializeseverything.Whentheinitialrenderingoccurs,oraneventinthebrowseroccurs,Angulargrabseverythingitneedstoknowaboutthecurrentstate,wrapsitupintoaserializedstring,andshipsitofftothewebworkerrendererontheproperchannel.Thewebworkerrendererunderstandswhat'sbeingpassedtoit.AlthoughitcannotaccessthemainDOM,itiscertainlyabletoconstructHTMLelements,understandhowtheserializedeventspassedtoitwillaffectthem,andperformtherendering.

Whenthetimecomestotellthebrowserwhattoactuallyrender,itwillinturnserializetherenderedcomponentandsenditbacktothemainbrowserruntime,whichwillunpackthestringandinsertitintotheDOM.

TotheAngularframework,becauseitisabstractedfromallthebrowserdependenciesthatmightgetinthewayofthis,everythingseemsnormal.Eventscomein,they'rehandled,andarendererservicetellsitwhattoputintotheDOM.EverythingthathappensinbetweenisunimportanttotheAngularframework,whichdoesn'tcarethateverythinghappenedinatotallyseparateJavaScriptruntime.

Note

Notethattheelementsyoubeginwithhavenothingunusualaboutthemtoallowwebworkercompatibility.ThisunderscorestheeleganceofAngular'swebworkerabstraction.

There'smore...Aswebworkersaremorefullysupportedandutilized,patternssuchasthesewillmostlikelybecomemoreandmorecommon,anditisextremelyprescientoftheAngularteamtosupportthisbehavior.Thereare,however,someconsiderations.

Optimizingforperformancegains

Oneoftheprimarybenefitsofusingwebworkersisthatyounowhaveaccesstoanexecutioncontextthatisnotblockedbyanythingrunningonthebrowserexecutioncontext.Forperformancedrags,suchasreflowandblockingofeventloophandlers,thewebworkerwillcontinuewiththeexecutionwithoutacareforwhatishappeningelsewhere.

Therefore,gettingaperformancebenefitbecomesaproblemofoptimization.CommunicationbetweenthetwoJavaScriptthreadsrequiresserializationandtransmissionofevents,whichisobviouslynotasfastashandlingtheminthesamethread.However,inanespeciallycomplicatedapplication,renderingcanquicklybecomeoneofthemostexpensivethingsyourapplicationwilldo.Therefore,youmayneedtoexperimentandmakeajudgmentcallforyourapplication,asnotallapplicationswillseeperformancegainsfromusingwebworkers—onlythosewhererenderingbecomesprohibitivelyexpensive.

Compatibilityconsiderations

Webworkershaveextremelygoodsupport,butthereisstillaverysignificantnumberofbrowsersthatdonotsupportthem.Ifyourapplicationneedstoworkuniversally,webworkersarenotrecommended;sincetheywillnotgracefullydegrade,yourapplicationwillmerelyfail.

SeealsoConfiguringtheAngular2rendererservicetousewebworkersguidesyouthroughthesettingupofyourapplicationtorenderonawebworkerConfiguringapplicationstouseahead-of-timecompilationguidesyouthroughhowtocompileanapplicationduringthebuildConfiguringanapplicationtouselazyloadingshowshowyoucandelayservingchunksofapplicationcodeuntilneeded

Configuringapplicationstouseahead-of-timecompilationAngular2introducestheconceptofahead-of-timecompilation(AOT).Thisisanalternateconfigurationinwhichyoucanrunyourapplicationstomovesomeprocessingtimefrominsidethebrowser(referredtoasjust-in-timecompilationorJIT)towhenyoucompileyourapplicationontheserver.

Note



GettingreadyAOTcompilationisapplication-agnostic,soyoushouldbeabletoaddthistoanyexistingAngular2applicationwithminimalmodification.

Forthepurposesofthisexample,supposeyouhaveanexistingAppModuleinsideapp/app.module.ts.Youneedn'tconcernyourselfwithitscontentsinceitisirrelevantforthepurposeofAOT.

Howtodoit...UsingAOTmeansyouwillcompileandbootstrapyourapplicationdifferently.Dependingonhowitisconfigured,youwillprobablywanttousesiblingfileswith"aot"addedtothename.Bearinmindthatthisisonlyfororganizationalpurposes;Angularisnotconcernedwithwhatyounameyourfiles.

InstallingAOTdependencies

Angularrequiresanewcompilationtoolngc,whichisincludedinthe@angular/compiler-clipackage.ItwillalsomakeuseofplatformBrowsertobootstrap,whichisprovidedinsidethe@angular/platform-browserpackage.Installbothoftheseandsavethedependencytopackage.json:

npminstall@angular/compiler-cli@angular/platform-server--save

Configuringngc

ngcwillessentiallyperformasupersetofdutiesofthetsccompilationtoolyouareaccustomedtousing.Itiswisetoprovideitwithaseparateconfigfile,whichcanbenamedtsconfig-aot.json(butyouarenotbeholdentothisname).

Thefileshouldappearidenticaltoyourexistingtsconfig.jsonfilebutwiththefollowingimportantmodifications:

[tsconfig-aot.json]

{

"compilerOptions":{

(lotsofsettingsherealready,onlychange'module')

"module":"es2015",

},

"files":[

"app/app.module.ts",

"main.ts"

],

"angularCompilerOptions":{

"genDir":"aot",

"skipMetadataEmit":true

}

}

AligningcomponentdefinitionswithAOTrequirements

AOTcompilationrequiresyourapplicationtobeorganizedinafewspecificways.Nothingshouldbreakanexistingapplication,butthey'reimportanttodoandtakenoteof.Ifyou'vebeen

followingAngularbestpractices,theyshouldbeabreeze.

First,componentdefinitionsmusthaveamoduleIdspecified.YouwillfindthatcomponentsgeneratedwiththeAngularCLIalreadyhavethisincluded.Ifnot,themoduleIdshouldalwaysbemodule.id,asshownhere:

@Component({

moduleId:module.id,

(lotsofotherstuff)

})

SincethemoduleisundefinedwhencompilinginAOT,youcanprovideadummyvalueintheroottemplate:

<script>window.module='aot';</script>

Tip

AOTdoesn'tneedthemoduleID,butitallowsyoutohaveacompilationwithouterrors.NotethatthesestepsinvolvingmoduleIdmaybechangedoreliminatedentirelyinfutureversionsofAngular,astheyonlyexisttoallowyoutohavecompatibilitybetweenbothJITandAOTcompilations.

Next,you'llneedtochangethepathofthetemplates,bothCSSandHTML,toberelativetothecomponentdefinitionfile,notapplication-root-relative.IfyouareusingtheconventiongivenbytheAngularCLIorthestyleguide,youareprobablyalreadydoingthis.

Compilingwithngc

ngcisn'tavailabledirectlyonthecommandline;you'llneedtorunthebinaryfiledirectly.Additionally,sinceinthisexampleit'snotusingthetsconfig.jsonnamingconvention,you'llneedtopointthebinarytothelocationofthealternateconfigfile.Runthefollowingcommandfromtherootofyourapplicationtoexecutethecompilation:

node_modules/.bin/ngc-ptsconfig-aot.json

ThiscommandwilloutputacollectionofNgFactoryfileswith.ngfactory.tsinsidetheaotdirectory,asyouspecifiedearlierintheangularCompilerOptionssectionoftsconfig-aot.json.

Thecompilationisdone,butyourapplicationdoesn'tyetknowhowtousetheseNgFactoryinstances.

BootstrappingwithAOT

YourapplicationwillnowstartoffwithAppModuleNgFactoryinsteadofAppModule.Bootstrap

itusingplatformBrowser:

[main.ts]

import{platformBrowser}from'@angular/platform-browser';

import{AppModuleNgFactory}from'aot/app/app.module.ngfactory';

platformBrowser().bootstrapModuleFactory(AppModuleNgFactory);

Withthis,you'llbeabletorunyourapplicationnormallybutthistimeusingprecompiledfiles.

Howitworks...CompilinginAngularisacomplexsubject,butthereareseveralmainpointsrelevanttoswitchinganapplicationtoanAOTbuildprocess:

TheAngularcompilerlivesinsidethe@angular/compilermodule,whichisquitelarge.UsingAOTmeansthismodulenolongerneedstobedeliveredtothebrowser,whichyieldssubstantialbandwidthsavings.TheAngularcompilationprocessinvolvestakingthetemplatestringsinsideyourcomponents,whichexistasdefinedbytemplateortemplateUrl,andconvertingthemintoNgFactoryinstances.TheseinstancesspecifyhowAngularunderstandshowyoudefinedthetemplate.TheconversiontoFactoryinstanceshappensbothinJITandAOTcompilation;switchingtoAOTsimplymeansyouaredoingthisprocessingontheserverinsteadoftheclientandservingNgFactorydefinitionsdirectlyinsteadofuncompiledtemplatestrings.AOTwillobviouslyslowdownyourbuildtimesincemorecomputationisrequiredeachtimethecodebaseneedsupdating.SinceyoucantrustthatAngularwillbeabletocorrectlyinterpretNgFactorydefinitionsthattheAOTcompilationgenerates,itisbesttodoJITcompilationwhendevelopingtheapplicationandAOTcompilationwhenbuildinganddeployingproductionapplications.

There'smore...AOTiscool,butitmightnotbeforeverybody.ItwillverylikelyreducetheloadtimeandinitializationtimeofyourAngularapplication,butyourbuildprocessisconsiderablymoreinvolvednow.What'smore,ifyouwanttouseJITindevelopmentbutAOTinproduction,younowhavetomaintaintwoversionsofthreedifferentfiles:index.html,main.ts,andtsconfig.json.Perhapsthisadditionalbuildcomplexityoverheadisworthit,butitshouldcertainlybeajudgmentcallbasedonyourdevelopmentsituation.

GoingfurtherwithTreeShaking

AngularalsosupportsaseparatestepofoptimizationcalledTreeShaking.Thisusesaseparatenpmlibrarycalledrollup.Essentially,thislibraryreadsinyourentireapplication(asJSfiles),figuresoutwhatmodulesarenotbeingused,andcutsthemoutofthecompiledcodebaseandthereforeofthepayloadthatisdeliveredtothebrowser.Thisisanalogoustoshakingatreetomakethedeadbranchesfallout,hence"treeshaking."

Note

Thees2015moduleconfigurationspecifiedearlierintsconfig-aot.jsonwasforsupportingtherolluplibrary,asitisarequirementforcompatibility.

Ifyourapplicationcodebaseiswell-maintained,youwillmostlikelyseelimitedbenefitsoftreeshakingsinceunusedimportsandthelikewillbecaughtwhencoding.What'smore,onecouldmaketheargumentthattreeshakingmightbeananti-patternsinceitsubtlyencouragesaliberaluseofmoduleinclusionbythedeveloperwiththeknowledgethattreeshakingwilldothedirtyworkingofcuttingoutanyunusedmodules.Thismaythenleadtoaclutteredcodebase.

UsingtreeshakingcanbeausefultoolwhenitcomestoAngular2applications,butitsusefulnessisinmanywaysevaporatedbykeepingacodebasetidy.

SeealsoUnderstandingandproperlyutilizingenableProdModewithpureandimpurepipesdescribeshowtotakethetrainingwheelsoffyourapplicationConfiguringtheAngular2rendererservicetousewebworkersguidesyouthroughtheprocessofsettingupyourapplicationtorenderonawebworkerConfiguringanapplicationtouselazyloadingshowshowyoucandelayservingchunksofapplicationcodeuntilneeded

ConfiguringanapplicationtouselazyloadingLazyloadedapplicationsarethosethatdefertheretrievalofrelevantresourcesuntiltheyareactuallynecessary.Onceapplicationsbegintoscale,thiscanyieldmeaningfulgainsinperformance,andAngular2supportslazyloadingrightoutofthebox.

Note



GettingreadySupposeyoubeginwiththefollowingsimpleapplication:



@Component({

selector:'root',

template:`



`

})


[app/link.component.ts]


@Component({

selector:'app-link',

template:`

<arouterLink="/article">article</a>

`

})

exportclassLinkComponent{}



@Component({

selector:'article',

template:`

<h1>{{title}}</h1>

`

})


title:string=

'Baboon'sStockPicksCrushTop-PerformingHedgeFund';

}

[app/app.module.ts]






import{LinkComponent}from'./link.component';


{

path:'article',

component:ArticleComponent

},

{

path:'**',

component:LinkComponent

}

];

@NgModule({

imports:[

BrowserModule,


],

declarations:[

ArticleComponent,

LinkComponent,

RootComponent

],

bootstrap:[

RootComponent

]

})


Thisapplicationhasonlytworoutes:thedefaultroute,whichdisplaysalinktothearticlepage,andthearticleroute,whichdisplayArticleComponent.Yourobjectiveistodefertheloadingoftheresourcesrequiredbythearticlerouteuntilitisactuallyvisited.

Howtodoit...LazyloadingmeanstheinitialapplicationmodulethatisloadedcannothaveanydependenciesonthemodulethatyouwishtolazilyloadsincenoneofthatcodewillbepresentbeforethenewURLisvisited.First,movetheArticleComponentreferencetoitsownmodule:




@NgModule({

declarations:[

ArticleComponent

],

exports:[

ArticleComponent

]

})


Removingalldependenciesmeansmovingtherelevantroutedefinitionstothismoduleaswell:




import{Routes,RouterModule}from'@angular/router';

constarticleRoutes:Routes=[

{

path:'',


}

];

@NgModule({

imports:[

RouterModule.forChild(articleRoutes)

],

declarations:[

ArticleComponent

],

exports:[

ArticleComponent

]

})


Next,removeallthesemodulereferencesfromAppModule.Inaddition,modifytheroutedefinition,sothatinsteadofspecifyingacomponenttorender,itsimplyreferencesapathtothelazilyloadedmodule,aswellasthenameofthemoduleusingaspecial#syntax:

[app/app.module.ts]







{

path:'article',

loadChildren:'./app/article.module#ArticleModule'

},

{

path:'**',


}

];

@NgModule({

imports:[

BrowserModule,


],

declarations:[

LinkComponent,

RootComponent

],

bootstrap:[

RootComponent

]

})


Thisisallthat'srequiredtosetuplazyloading.Yourapplicationshouldbehaveidenticallytowhenyoubeganthisrecipe.

Howitworks...Toverifythatitisinfactperformingalazyload,starttheapplicationandkeepaneyeontheNetworktabofyourbrowser'sdeveloperconsole.

WhenyouclickonthearticlerouterLink,youshouldseearticle.module.tsandarticle.component.tsrequestsgooutbeforetherenderingoccurs.ThismeansAngularisonlyfetchingtherequiredfilesonceyouactuallyvisittheroute.TheloadChildrenroutepropertytellsAngularthatwhenitvisitsthisroute,ifithasn'tloadedthemodulealready,itshouldusetherelativepathyoumayhaveprovidedtofetchthemodule.Oncethemodulefileisretrieved,Angularisabletoparseitandknowwhichotherfilesitneedstorequesttoloadallthemodule'sdependencies.

There'smore...You'llnotethatthisintroducesabitofadditionallatencytoyourapplicationsinceAngularwaitstoloadtheresourcesrightwhenitactuallyneedsthem.What'smore,inthisexample,ithastoactuallyperformtwoadditionalroundtripstotheserverwhenitvisitsthearticleURL:onetorequestthemodulefileandonetorequestthemodule'sdependencies.

Inaproductionenvironment,thislatencymightbeunacceptable.Aworkaroundmightbetocompilethelazilyloadedpayloadintoasinglefilethatcanbefetchedwithonerequest.Dependingonhowyourapplicationisbuilt,yourmileagemayvary.

Accountingforsharedmodules

Thelazilyloadedmoduleistotallyseparatedfromyourmainapplicationmodule,andthisincludesinjectables.Ifaserviceisprovidedtothetop-levelapplicationmodule,youwillfindthatitwillcreatetwoseparateinstancesofthatserviceforeachplaceitisprovided—certainlyunexpectedbehavior,giventhatanapplicationloadednormallywillonlycreateoneinstanceifitisonlyprovidedonce.

ThesolutionistopiggybackontheforRootmethodthatAngularusestosimultaneouslyprovideandconfigureservices.Morerelevanttothisrecipe,itallowsyoutotechnicallyprovideaserviceatmultiplelocations;however,Angularwillknowhowtoignoreduplicatesofthis,provideditisdoneinsideforRoot().

First,definetheAuthServicethatyouwishtocreateonlyasingleinstanceof:

[app/auth.service.ts]


@Injectable()


constructor(){

console.log('instantiatedAuthService');

}

}

Thisincludesalogstatementsoyoucanseethatonlyoneinstantiationoccurs.

Next,createanNgModulewrapperspeciallyforthisservice:

[app/auth.module.ts]

import{NgModule,ModuleWithProviders}from"@angular/core";

import{AuthService}from"./auth.service";

@NgModule({})

exportclassAuthModule{

staticforRoot():ModuleWithProviders{

return{

ngModule:AuthModule,

providers:[

AuthService

]

};

}

}

SincethisutilizestheforRoot()strategyasdetailedintheprecedingcode,you'refreetoimportthismodulebothinsidetheapplicationmoduleaswellasthelazilyloadedmodule:

[app/app.module.ts]






import{AuthModule}from'./auth.module';


{

path:'article',

loadChildren:'./app/article.module#ArticleModule'

},

{

path:'**',


}

];

@NgModule({

imports:[

BrowserModule,

RouterModule.forRoot(appRoutes),

AuthModule.forRoot()

],

declarations:[

LinkComponent,

RootComponent

],

bootstrap:[

RootComponent

]

})


You'lladdittothelazilyloadedmoduletoo,butdon'tinvokeforRoot().Thismethodisreservedforonlytherootapplicationmodule:




import{Routes,RouterModule}from'@angular/router';

import{AuthModule}from'./auth.module';

constarticleRoutes:Routes=[

{

path:'',


}

];

@NgModule({

imports:[

RouterModule.forChild(articleRoutes),

AuthModule

],

declarations:[

ArticleComponent

],

exports:[

ArticleComponent

]

})


Finally,injecttheserviceintoRootComponentandArticleComponentanduselogstatementstoseethatitdoesindeedreachboththecomponents:




@Component({

selector:'root',

template:`



`

})



console.log(authService_);

}

}




@Component({

selector:'article',

template:`

<h1>{{title}}</h1>

`

})


title:string=

'Baboon'sStockPicksCrushTop-PerformingHedgeFund';


console.log(authService_);

}

}

Youshouldseeasingleserviceinstantiationandsuccessfulinjectionintoboththecomponents.

SeealsoConfiguringtheAngular2rendererservicetousewebworkersguidesyouthroughtheprocessofsettingupyourapplicationtorenderonawebworkerConfiguringapplicationstouseahead-of-timecompilationguidesyouthroughhowtocompileanapplicationduringthebuild

angular 2 cookbook - programmer booksdowngrading angular 2 components to angular 1 directives with...

Documents