Ng-Book: The Complete Guide to Angular 11

769 Pages·2020·19.9 MB·english

by  Felipe Coury

ng-book
The Complete Guide to Angular
Written by Nate Murray, Felipe Coury, Ari Lerner, and Carlos
Taborda
© 2020 Fullstack.io
All rights reserved. No portion of the book manuscript may be reproduced,
stored in a retrieval system, or transmitted in any form or by any means beyond
the number of purchased copies, except for a single backup or archival copy. The
code may be used freely in your projects, commercial or otherwise.
The authors and publisher have taken care in preparation of this book, but make
no expressed or implied warranty of any kind and assume no responsibility for
errors or omissions. No liability is assumed for incidental or consequential
damagers in connection with or arising out of the use of the information or
programs container herein.
Published in San Francisco, California by Fullstack.io.

FULLSTACK.io
We’dliketothankourcontributorstothisbookincluding:
• FrodeFikkefortechnicaledits
• NicRaboy,andBurkeHollandfortheircontributiontotheNativeScriptchapter
• TravasNolteforhisworkonmanychapters
• DanielRaufforhiseditsonRxJS,Redux,andRouting
Contents
BookRevision . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
JoinNewlinePro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
JoinourDiscordChat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
VoteforNewContent(new!) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
BenotifiedofupdatesviaTwitter . . . . . . . . . . . . . . . . . . . . . . . . . 1
BugReports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
We’dlovetohearfromyou! . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
BecomeATechnicalContributor-FreeUpdatesforLife . . . . . . . . . . . 3
SpecialThankstoOurTechnicalContributors . . . . . . . . . . . . . . . . . 3
HowtoReadThisBook . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
RunningCodeExamples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
AngularCLI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
CodeBlocksandContext . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
CodeBlockNumbering . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
AWordonVersioning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
GettingHelp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
EmailingUs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
ChapterOverview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
WritingYourFirstAngularWebApplication . . . . . . . . . . . . . . . . . . . 1
SimpleRedditClone . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Gettingstarted . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
Node.jsandnpm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
TypeScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
SpecialinstructionforWindowsusers . . . . . . . . . . . . . . . . . . . . . . 5
AngularCLI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
CONTENTS
ExampleProject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Runningtheapplication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
MakingaComponent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
ImportingDependencies. . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
ComponentDecorators . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
AddingatemplatewithtemplateUrl . . . . . . . . . . . . . . . . . . . . 17
Addingatemplate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
AddingCSSStyleswithstyleUrls . . . . . . . . . . . . . . . . . . . . . 18
LoadingOurComponent . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
AddingDatatotheComponent . . . . . . . . . . . . . . . . . . . . . . . . . . 20
WorkingWithArrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
UsingtheUserItemComponent. . . . . . . . . . . . . . . . . . . . . . . . . . 28
RenderingtheUserItemComponent. . . . . . . . . . . . . . . . . . . . . . 29
AcceptingInputs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
PassinganInputvalue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
BootstrappingCrashCourse . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
declarations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
imports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
providers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
bootstrap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
ExpandingourApplication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
AddingCSS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
TheApplicationComponent . . . . . . . . . . . . . . . . . . . . . . . . . 39
AddingInteraction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
AddingtheArticleComponent . . . . . . . . . . . . . . . . . . . . . . . 46
RenderingMultipleRows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
CreatinganArticleclass. . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
StoringMultipleArticles . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
ConfiguringtheArticleComponentwithinputs . . . . . . . . . . . . . 63
RenderingaListofArticles . . . . . . . . . . . . . . . . . . . . . . . . . . 65
AddingNewArticles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
FinishingTouches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
DisplayingtheArticleDomain . . . . . . . . . . . . . . . . . . . . . . . . 68
Re-sortingBasedonScore. . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
BuildingOurAppforProduction . . . . . . . . . . . . . . . . . . . . . . 71
CONTENTS
UploadingtoaServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Installingnow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
FullCodeListing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
WrappingUp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
GettingHelp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
TypeScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
AngularisbuiltinTypeScript . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
WhatdowegetwithTypeScript? . . . . . . . . . . . . . . . . . . . . . . . . . 76
Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
TryingitoutwithaREPL . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
Built-intypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Inheritance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
FatArrowFunctions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
TemplateStrings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Wrappingup. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
HowAngularWorks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
TheNavigationComponent . . . . . . . . . . . . . . . . . . . . . . . . . 95
TheBreadcrumbsComponent . . . . . . . . . . . . . . . . . . . . . . . . 95
TheProductListComponent . . . . . . . . . . . . . . . . . . . . . . . . . 95
HowtoUseThisChapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
ProductModel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
ComponentDecorator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
Componentselector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
Componenttemplate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
AddingAProduct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
ViewingtheProductwithTemplateBinding . . . . . . . . . . . . . . . 107
AddingMoreProducts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
CONTENTS
SelectingaProduct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Listingproductsusing<products-list> . . . . . . . . . . . . . . . . . . 109
TheProductsListComponent . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
ConfiguringtheProductsListComponent@ComponentOptions . . . . . 113
Componentinputs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
Componentoutputs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
EmittingCustomEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
WritingtheProductsListComponentControllerClass . . . . . . . . . . 120
WritingtheProductsListComponentViewTemplate. . . . . . . . . . . 121
TheFullProductsListComponentComponent. . . . . . . . . . . . . . . 123
TheProductRowComponentComponent . . . . . . . . . . . . . . . . . . . . . . 125
ProductRowComponentConfiguration . . . . . . . . . . . . . . . . . . . . 126
ProductRowComponenttemplate . . . . . . . . . . . . . . . . . . . . . . . 127
TheProductImageComponentComponent . . . . . . . . . . . . . . . . . . . . 128
ThePriceDisplayComponentComponent . . . . . . . . . . . . . . . . . . . . 128
TheProductDepartmentComponent . . . . . . . . . . . . . . . . . . . . . . . . 129
NgModuleandBootingtheApp. . . . . . . . . . . . . . . . . . . . . . . . . . . 131
Bootingtheapp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
TheCompletedProject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
DeployingtheApp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
AWordonDataArchitecture . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
Built-inDirectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
NgIf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
NgSwitch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
NgStyle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
NgClass . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
NgFor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
Gettinganindex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
NgNonBindable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
Conclusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
FormsinAngular . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
FormsareCrucial,FormsareComplex. . . . . . . . . . . . . . . . . . . . . . 155
FormControlsandFormGroups . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
CONTENTS
FormControl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
FormGroup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
OurFirstForm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
LoadingtheFormsModule . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
Reactive-vs.template-drivenForms . . . . . . . . . . . . . . . . . . . . 160
SimpleSKUForm:@ComponentDecorator. . . . . . . . . . . . . . . . 160
SimpleSKUForm:template . . . . . . . . . . . . . . . . . . . . . . . . . 161
SimpleSKUForm:ComponentDefinitionClass . . . . . . . . . . . . . 164
Tryitout! . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
UsingFormBuilder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
ReactiveFormswithFormBuilder . . . . . . . . . . . . . . . . . . . . . . . . . 168
UsingFormBuilder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
UsingmyFormintheview . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
Tryitout! . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
AddingValidations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
ExplicitlysettingtheskuFormControlasaninstancevariable . . . . . 174
CustomValidations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
WatchingForChanges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
ngModel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
WrappingUp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
DependencyInjection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
InjectionsExample:PriceService . . . . . . . . . . . . . . . . . . . . . . . . 187
DependencyInjectionParts . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
PlayingwithanInjector. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
ProvidingDependencieswithNgModule . . . . . . . . . . . . . . . . . . . . . 196
ProvidersaretheKey . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
Providers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
UsingaClass . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
UsingaFactory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
DependencyInjectioninApps . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
MoreResources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
HTTP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
Using@angular/common/http . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
CONTENTS
importfrom@angular/common/http . . . . . . . . . . . . . . . . . . . . 209
ABasicRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
BuildingtheSimpleHttpComponentComponentDefinition . . . . . . . 212
BuildingtheSimpleHttpComponenttemplate . . . . . . . . . . . . . . . 212
BuildingtheSimpleHttpComponentController . . . . . . . . . . . . . . 213
FullSimpleHttpComponent . . . . . . . . . . . . . . . . . . . . . . . . . . 214
WritingaYouTubeSearchComponent . . . . . . . . . . . . . . . . . . . . . . . . 215
WritingaSearchResult . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
WritingtheYouTubeSearchService . . . . . . . . . . . . . . . . . . . . . 218
WritingtheSearchBoxComponent . . . . . . . . . . . . . . . . . . . . . . 224
WritingSearchResultComponent . . . . . . . . . . . . . . . . . . . . . . . 232
WritingYouTubeSearchComponent . . . . . . . . . . . . . . . . . . . . . . 233
@angular/common/httpAPI. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
MakingaPOSTrequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238
PUT/PATCH/DELETE/HEAD . . . . . . . . . . . . . . . . . . . . . . . . . . 238
CustomHTTPHeaders . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
Routing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
WhyDoWeNeedRouting? . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
Howclient-sideroutingworks . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
Thebeginning:usinganchortags . . . . . . . . . . . . . . . . . . . . . . 243
Theevolution:HTML5client-siderouting . . . . . . . . . . . . . . . . . 244
Writingourfirstroutes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245
ComponentsofAngularrouting . . . . . . . . . . . . . . . . . . . . . . . . . . 245
Imports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245
Routes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
InstallingourRoutes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248
RouterOutletusing<router-outlet> . . . . . . . . . . . . . . . . . . . 248
RouterLinkusing[routerLink] . . . . . . . . . . . . . . . . . . . . . . . 250
Puttingitalltogether . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251
CreatingtheComponents . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
HomeComponent. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
AboutComponent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
ContactComponent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
ApplicationComponent . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
CONTENTS
ConfiguringtheRoutes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
RoutingStrategies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259
Runningtheapplication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
RouteParameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263
ActivatedRoute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264
MusicSearchApp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265
FirstSteps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267
TheSpotifyService . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
TheSearchComponent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
Tryingthesearch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
TrackComponent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282
Wrappingupmusicsearch . . . . . . . . . . . . . . . . . . . . . . . . . . 284
RouterHooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285
AuthService . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
LoginComponent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288
ProtectedComponentandRouteGuards . . . . . . . . . . . . . . . . . . 290
NestedRoutes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297
ConfiguringRoutes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297
ProductsModule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304
DataArchitectureinAngular . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305
AnOverviewofDataArchitecture . . . . . . . . . . . . . . . . . . . . . . . . 305
DataArchitectureinAngular . . . . . . . . . . . . . . . . . . . . . . . . 306
DataArchitecturewithObservables-Part1:Services . . . . . . . . . . . . . 308
ObservablesandRxJS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308
Note:SomeRxJSKnowledgeRequired . . . . . . . . . . . . . . . . . . . 308
LearningReactiveProgrammingandRxJS. . . . . . . . . . . . . . . . . 309
ChatAppOverview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310
Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312
Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313
Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314
ImplementingtheModels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
User . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315