Magento2DevelopmentQuickStartGuide

BuildbetterstoresbyextendingMagento

BrankoAjzele

BIRMINGHAM-MUMBAI

Magento2DevelopmentQuickStartGuideCopyright©2018PacktPublishing

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

Everyefforthasbeenmadeinthepreparationofthisbooktoensuretheaccuracyoftheinformationpresented.However,theinformationcontainedinthisbookissoldwithoutwarranty,eitherexpressorimplied.Neithertheauthor,norPacktPublishingoritsdealersanddistributors,willbeheldliableforanydamagescausedorallegedtohavebeencauseddirectlyorindirectlybythisbook.

PacktPublishinghasendeavoredtoprovidetrademarkinformationaboutallofthecompaniesandproductsmentionedinthisbookbytheappropriateuseofcapitals.However,PacktPublishingcannotguaranteetheaccuracyofthisinformation.

CommissioningEditor:AmarabhaBanerjeeAcquisitionEditor:ReshmaRamanContentDevelopmentEditor:KirkDsouzaTechnicalEditor:VaibhavDwivediCopyEditor:SafisEditingProjectCoordinator:HardikBhindeProofreader:SafisEditingIndexer:AishwaryaGangawaneGraphics:AlishonMendonsaProductionCoordinator:DeepikaNaik

Firstpublished:September2018

Productionreference:1180918

PublishedbyPacktPublishingLtd.LiveryPlace35LiveryStreetBirminghamB32PB,UK.

ISBN978-1-78934-344-1

www.packtpub.com

mapt.io

Maptisanonlinedigitallibrarythatgivesyoufullaccesstoover5,000booksandvideos,aswellasindustryleadingtoolstohelpyouplanyourpersonaldevelopmentandadvanceyourcareer.Formoreinformation,pleasevisitourwebsite.

Whysubscribe?SpendlesstimelearningandmoretimecodingwithpracticaleBooksandVideosfromover4,000industryprofessionals

ImproveyourlearningwithSkillPlansbuiltespeciallyforyou

GetafreeeBookorvideoeverymonth

Maptisfullysearchable

Copyandpaste,print,andbookmarkcontent

Packt.comDidyouknowthatPacktofferseBookversionsofeverybookpublished,withPDFandePubfilesavailable?YoucanupgradetotheeBookversionatwww.packt.comandasaprintbookcustomer,youareentitledtoadiscountontheeBookcopy.Getintouchwithusatcustomercare@packtpub.comformoredetails.

Atwww.packt.com,youcanalsoreadacollectionoffreetechnicalarticles,signupforarangeoffreenewsletters,andreceiveexclusivediscountsandoffersonPacktbooksandeBooks.

Contributors

AbouttheauthorBrankoAjzeleisarespectedandhighlyaccomplishedsoftwaredeveloper,bookauthor,solutionspecialist,consultant,andteamleader.HecurrentlyworksforInteractiveWebSolutionsLtd(iWeb),whereheholdstheroleofseniordeveloperandisthedirectorofiWeb'sCroatiaoffice.

BrankoholdsseveralrespectedITcertifications,includingZendCertifiedPHPEngineer,MagentoCertifiedDeveloper,MagentoCertifiedDeveloperPlus,MagentoCertifiedSolutionSpecialist,Magento2CertifiedSolutionSpecialist,Magento2CertifiedProfessionalDeveloper,tomentionjustafew.

Hewascrownedthee-commerceDeveloperoftheYearbytheDigitalEntrepreneurAwardsinOctober2014forhisexcellentknowledgeandexpertiseine-commercedevelopment.

Specialthankstomysupportivewife,Ivana,forherunderstandingwhenItookquiteabitofourfamilytimeforthisendeavor.

Aboutthereviewer

Andrew"Pembo"PembertonisaCertifiedMagentoDeveloperwithover20years'experiencebuildingwebsites.HeisbasedinStoke-on-Trent,UKandstartedbuildingwebsitesfromtheyoungageof13.HehasadegreeincomputersciencefromStaffordshireUniversity.

AndrewisnowthedevelopmentdirectoratiWeb(basedinStafford,UK),which,forover20years,hascreatedindustry-leadingwebsitesandnowspecializesinlargescaleMagentosolutionsandPIM-basedprojectsforawiderangeofclients.

Outsideofhisdigitallife,Andrewenjoysspendingtimewithhisfamilyofpets,travelingwithhiswife,andbeinganavidgamer.

PacktissearchingforauthorslikeyouIfyou'reinterestedinbecominganauthorforPackt,pleasevisitauthors.packtpub.comandapplytoday.Wehaveworkedwiththousandsofdevelopersandtechprofessionals,justlikeyou,tohelpthemsharetheirinsightwiththeglobaltechcommunity.Youcanmakeageneralapplication,applyforaspecifichottopicthatwearerecruitinganauthorfor,orsubmityourownidea.

TableofContentsTitlePageCopyrightandCredits

Magento2DevelopmentQuickStartGuidePacktUpsell

Whysubscribe?Packt.com

ContributorsAbouttheauthorAboutthereviewerPacktissearchingforauthorslikeyou

PrefaceWhothisbookisforWhatthisbookcoversTogetthemostoutofthisbook

DownloadtheexamplecodefilesCodeinAction

ConventionsusedGetintouch

Reviews1. UnderstandingtheMagentoArchitecture

TechnicalrequirementsInstallingMagentoModesAreasRequestflowprocessingModules

CreatingtheminimalmoduleCacheDependencyinjection

ArgumentinjectionVirtualtypesProxiesFactories

PluginsThebeforepluginThearoundpluginTheafterplugin

EventsandobserversConsolecommandsCronjobsSummary

2. WorkingwithEntitiesTechnicalrequirementsUnderstandingtypesofmodels

CreatingasimplemodelMethodsworthmemorizing

WorkingwithsetupscriptsThe InstallSchemascriptThe UpgradeSchemascriptTheRecurringscriptThe InstallDatascriptThe UpgradeDatascriptTheRecurringDatascript

ExtendingentitiesCreatingextensionattributes

Summary3. UnderstandingWebAPIs

TechnicalrequirementsTypesofusersTypesofauthenticationTypesofAPIsUsingexistingwebAPIsCreatingcustomwebAPIsUnderstandingsearchcriteriaSummary

4. BuildingandDistributingExtensionsTechnicalrequirementsBuildingashippingextensionDistributingviaGitHubDistributingviaPackagistSummary

5. DevelopingforAdminTechnicalrequirementsUsingthelistingcomponentUsingtheformcomponentSummary

6. DevelopingforStorefrontTechnicalrequirementsSettinguptheplaygroundCallingandinitializingJScomponentsMeetRequireJSReplacingjQuerywidgetcomponentsExtendingjQuerywidgetcomponentsCreatingjQuerywidgetscomponentsCreatingUI/KnockoutJScomponentsExtendingUI/KnockoutJScomponentsSummary

7. CustomizingCatalogBehaviorTechnicalrequirementsCreatingthesizeguideCreatingthesamedaydeliveryFlaggingnewproductsSummary

8. CustomizingCheckoutExperiencesTechnicalrequirementsPassingdatatothecheckoutAddingordernotestothecheckoutSummary

9. CustomizingCustomerInteractionsTechnicalrequirementsUnderstandingthesectionmechanismAddingcontactpreferencestocustomeraccountsAddingcontactpreferencestothecheckoutSummary

OtherBooksYouMayEnjoyLeaveareview-letotherreadersknowwhatyouthink

PrefaceMagentoisapopularopensourcee-commerceplatformwritteninPHP.Itisusedprimarilyforbuildingwebshops,thoughitcaneasilybeusedforothertypesofwebsitesaswell.WiththehelpofitspowerfulwebAPI,wecanbuildrobustsolutionsthatsatisfymodern-dayapplicationrequirements.

Bytheendofthisbook,thereadershouldbefamiliarwithconfigurationfiles,models,collections,blocks,controllers,events,observers,plugins,UIcomponentsandotherbuildingelementsofMagento.

WhothisbookisforThisbookisintendedforPHPdevelopersgettingstartedwithMagentov2.xdevelopment.Thoughcompactintermsofpagenumbers,thebookcoversawiderangeoffunctionality,allowingthereadertomasterday-to-dayMagentoskillsinaclearandconciseway.NopreviousMagentoknowledgeisrequired.

WhatthisbookcoversChapter1,UnderstandingtheMagentoArchitecture,takesalookatsomeofthekeyMagentocomponents.WewillgothroughpluginsandeventobserversandlearnhowtheyprovideapowerfulwayofextendingMagento,eitherbychangingthebehaviorofexistingfunctionsorbyrunningsomefollow-upcodeinresponsetocertainevents.

Chapter2,WorkingwithEntities,demonstrateshowtodifferentiatebetweenthethreetypesofMagentomodels:non-persistable,persistablesimple,andpersistableEAV.Wewilltakealookatthesixdifferentsetupscriptsandhowtheyallowusagreatdealofflexibilityforschemaanddatamanagement.

Chapter3,UnderstandingWebAPI,showsthereaderhowtodifferentiatebetweentypesofwebAPIusers,authentication,andmethodsitprovides.WewillalsotakealookathoweasyitistocreateourownAPIswithjustafewlinesofXML.WewillseehowtheroutedefinitionallowsforeasybindingbetweenwhatarrivesviaHTTPrequestsandwhatisexecutedincode,respectingtheaccesslistpermissionsintheprocess.

Chapter4,BuildingandDistributingExtensions,discusseshowtocreateasimpleshippingmodule.Weshalltakealookathoweasyitistoaddspecificshippingcalculationsaspartofofflineshippingmethods.WewillthenpackagethismoduleanddistributeitviaPackagist.Thismakesiteasyfortheendconsumertouseourmodulewithjustafewsimpleconsolecommands.

Chapter5,DevelopingforAdmin,walksthereaderthroughbuildingtwoverydifferentscreensintheMagentoadminarea.Oneutilizesthelistingcomponent,whereastheotherutilizestheformcomponent.

Chapter6,DevelopingforStorefront,coversthebitsandpiecesinvolvedinstorefrontdevelopment,whichJScomponentsmakethemostchallengingpartof.Wewillunderstandhowtowritenewcomponents,aswellashowtooverrideorbypassexistingones–anessentialskillforanyMagentodeveloper,beitbackendorfrontend.

Chapter7,CustomizingCatalogBehavior,demonstratesbuildingthreedistinctivefunctionalities,allofwhichrelatetothecatalogpartofMagento.TheydemonstratehoweasilyMagentocanbeextendedwithnewfeatureswithoutreallyoverridinganyofthecorefiles.UsingpluginsandJScomponentsarejustsomeoftheapproacheswemighttake.

Chapter8,CustomizingCheckoutExperience,demonstrateswritingasmallbutfunctionalordernotesmodule.Thiswillallowustofamiliarizeourselveswithanimportantaspectofcustomizingthecheckoutexperience,thegistofwhichliesinunderstandingthecheckout_index_indexlayouthandle,theJavaScriptwindow.checkoutConfigobject,anduiComponent.

Chapter9,CustomizingCustomerInteractions,walksthereaderthroughbuildingasmallmodulethatallowsustogetagreaterinsightintoMagento'scustomerdataandsectionsmechanism.Wewilllearnhowtomanageandbuildasinglecomponent,whichwillgetusedbothonthecustomer'sMyAccountpage,aswellasatthecheckout.

TogetthemostoutofthisbookTogetthemostoutofthebook,thereaderisexpectedtohave:

AdegreeofPHPobject-orientedprogramming(OOP)knowledgeAbasicunderstandingofJavaScriptandXML

DownloadtheexamplecodefilesYoucandownloadtheexamplecodefilesforthisbookfromyouraccountatwww.packtpub.com.Ifyoupurchasedthisbookelsewhere,youcanvisitwww.packtpub.com/supportandregistertohavethefilesemaileddirectlytoyou.

Youcandownloadthecodefilesbyfollowingthesesteps:

1. Loginorregisteratwww.packtpub.com.2. SelecttheSUPPORTtab.3. ClickonCodeDownloads&Errata.4. EnterthenameofthebookintheSearchboxandfollowtheonscreen

instructions.

Oncethefileisdownloaded,pleasemakesurethatyouunziporextractthefolderusingthelatestversionof:

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

ThecodebundleforthebookisalsohostedonGitHubathttps://github.com/PacktPublishing/Magento-2-Quick-Start-Guide.Incasethere'sanupdatetothecode,itwillbeupdatedontheexistingGitHubrepository.

Wealsohaveothercodebundlesfromourrichcatalogofbooksandvideosavailableathttps://github.com/PacktPublishing.Checkthemout!

CodeinActionVisitthefollowinglinktocheckoutvideosofthecodebeingrun:

http://bit.ly/2D98D8q

ConventionsusedThereareanumberoftextconventionsusedthroughoutthisbook.

CodeInText:Indicatescodewordsintext,databasetablenames,foldernames,filenames,fileextensions,pathnames,dummyURLs,userinput,andTwitterhandles.Hereisanexample:"Thedefaultareaisthefrontend,asdefinedbythedefaultargumentundermodulestore/etc/di.xml."

Ablockofcodeissetasfollows:

constAREA_GLOBAL='global';

constAREA_FRONTEND='frontend';

constAREA_ADMINHTML='adminhtml';

constAREA_DOC='doc';

constAREA_CRONTAB='crontab';

constAREA_WEBAPI_REST='webapi_rest';

constAREA_WEBAPI_SOAP='webapi_soap';

Whenwewishtodrawyourattentiontoaparticularpartofacodeblock,therelevantlinesoritemsaresetinbold:

constAREA_GLOBAL='global';

constAREA_FRONTEND='frontend';

constAREA_ADMINHTML='adminhtml';

constAREA_DOC='doc';

constAREA_CRONTAB='crontab';

constAREA_WEBAPI_REST='webapi_rest';

constAREA_WEBAPI_SOAP='webapi_soap';

Anycommand-lineinputoroutputiswrittenasfollows:

phpbin/magentosetup:install\

--db-host="/Applications/MAMP/tmp/mysql/mysql.sock"\

--db-name=magelicious\

Bold:Indicatesanewterm,animportantword,orwordsthatyouseeonscreen.Forexample,wordsinmenusordialogboxesappearinthetextlikethis.Hereisanexample:"Thetabelementofthefile,whichisusedtoprovideasidebarmenupresenceunderMagentoadminStores|Settings|Configuration,isaniceexample."

Warningsorimportantnotesappearlikethis.

Tipsandtricksappearlikethis.

GetintouchFeedbackfromourreadersisalwayswelcome.

Generalfeedback:Emailfeedback@packtpub.comandmentionthebooktitleinthesubjectofyourmessage.Ifyouhavequestionsaboutanyaspectofthisbook,pleaseemailusatquestions@packtpub.com.

Errata:Althoughwehavetakeneverycaretoensuretheaccuracyofourcontent,mistakesdohappen.Ifyouhavefoundamistakeinthisbook,wewouldbegratefulifyouwouldreportthistous.Pleasevisitwww.packtpub.com/submit-errata,selectingyourbook,clickingontheErrataSubmissionFormlink,andenteringthedetails.

Piracy:IfyoucomeacrossanyillegalcopiesofourworksinanyformontheInternet,wewouldbegratefulifyouwouldprovideuswiththelocationaddressorwebsitename.Pleasecontactusatcopyright@packtpub.comwithalinktothematerial.

Ifyouareinterestedinbecominganauthor:Ifthereisatopicthatyouhaveexpertiseinandyouareinterestedineitherwritingorcontributingtoabook,pleasevisitauthors.packtpub.com.

ReviewsPleaseleaveareview.Onceyouhavereadandusedthisbook,whynotleaveareviewonthesitethatyoupurchaseditfrom?Potentialreaderscanthenseeanduseyourunbiasedopiniontomakepurchasedecisions,weatPacktcanunderstandwhatyouthinkaboutourproducts,andourauthorscanseeyourfeedbackontheirbook.Thankyou!

FormoreinformationaboutPackt,pleasevisitpacktpub.com.

UnderstandingtheMagentoArchitectureBuildingwebshopsisachallengingandtediousjob,andevenmoresoifaplatformyouareworkingonislimitedviafeatures,extensibility,andtheoverallecosystemitprovides.Choosingtherightplatformcanoftenmakethedifferencebetweenaproject'ssuccessorfailure.Theabundanceofavailablee-commercesoftware,fromSaaStoself-hostedsolutions,doesnotreallymakeitaneasychoice.

TheMagentoe-commerceplatformhasbeenaroundforover10yearsnow.WithitsfirststablereleasedatingbacktoMarch2008,itimmediatelycaughttheattentionofdevelopersasanextensibleandfeature-richopensourceplatform.Overtime,Magentoestablisheditselfasnotjustastunningtechnicalandfeature-richplatform,butasarobustecosystemaswell.Byallowingdeveloperstovalidatetheirreal-worldskillsthroughtheMagentocertificationprogram,certainstandardshavebeenputintoeffect,makingiteasierformerchantstobetterrecognizetheirsolutionpartners.Trainingcourseshavebeenfurtherprovidedforotherrolesine-commercebusinessaswell,suchasmerchants,marketers,systemadministrators,andbusinessanalysts.

Inthischapter,wewilltakealookatsomeofthekeymust-knowsaboutMagento:

InstallingMagentoModesAreasRequestflowprocessingModulesCacheDependencyinjectionPluginsEventsandobserversConsolecommandsCronjobs

Tokeepthingscompactaswemoveforward,let'sassumethefollowingthroughoutthisbook:

Weareworkingonthemagelicious.locprojectWearereferringtoourprojectrootdirectoryas<PROJECT_DIR>Wearereferringtothe<PROJECT_DIR>/app/code/Mageliciousdirectoryas<MAGELICIOUS_DIR>

WearereferringtoMagento'svendor/magentodirectoryas<MAGENTO_DIR>WehavearunningLAMP/MAMP/WAMPstack(Apache,MySQL,PHP)thatiscompliantwithMagento'srequirementsWehaveaComposerpackagemanagerinstalledWehaveaccesstocrontab(Linux,MacOS)orTaskScheduler(Windows)

AMPPSisaneasytouse,allinoneLAMP/MAMP/WAMPsoftwarestackfromSoftaculous,whichenablesApache,MySQL,andPHP.WithAMPPS,youcaneveninstallMagento2.xbytheclickofabutton,whichmeansitcomesloadedwithalltherightPHPextensions.Whileitisn'tsuitedforproductionpurposes,itcomesinhandyforquicklykickingthedevelopmentenvironment.Seehttp://www.ampps.com/formoreinformation.Consultthedevdocs(https://devdocs.magento.com)forMagentotechnologystackrequirements.

TechnicalrequirementsYouwillneedtohavebasicknowledgeofPHP,OOP,JavaScript,andXML.YouwillalsoneedApache,MySQL,andAMPPSinstalledonyoursystemtoexecutethecodes.

ThecodefilesofthischaptercanbefoundonGitHub:https://github.com/PacktPublishing/Magento-2-Quick-Start-Guide.

CheckoutthefollowingvideotoseetheCodeinAction:

http://bit.ly/2D8kOlF.

InstallingMagentoTheMagentoplatformcomesintwoflavors:

MagentoOpenSource:Thefreeversion,targetingsmallbusinessesMagentoCommerce:Thecommercialversion,targetingsmall,medium,orenterprisebusinesses

ThedifferencebetweenthetwocomesmainlyintheformofextramodulesthatwereaddedtotheCommerceversion,whereasallthecodingconceptsandcorefeaturesremainthesame.ItgoestosaythatanyknowledgeweobtainthroughfollowingMagentoOpenSourceexamplesisfullyapplicabletoanyoneworkingonMagentoCommerce.

ThereareseveralwaysthatwecanobtainsourcefilesforMagentoOpenSource:

Sourcefilearchive(.zip,.tar.gz,.tar.bz2),availableathttps://magento.comGitrepository,availableathttps://github.com/magento/magento2Composerrepository,availableathttps://repo.magento.com

ObtainingsourcefilesviaaCLIfromthecomposerrepositoryisourpreferredmethod.Assumingwearewithintheempty<PROJECT_DIR>directory,wecankickoffthisprocessviathefollowingcommand:

composercreate-project--repository-url=https://repo.magento.com/magento/project-community-edition.

Thedot(.)attheendofthiscommandthistellsthecomposertopullthefilesintoacurrentdirectory.

OncetheComposerprocessisfinished,wecanstartinstallingMagento.TherearetwowayswecaninstallMagento:

ViatheWebSetupWizard:Thegraphical,browser-basedprocessViathecommandline:Thecommand-line-basedprocess

KnowinghowtoinstallMagentoviathecommandlineisanessentialskillinday-to-daydevelopment,asthemajorityofdevelopmentrequiresthedeveloper

totacklevariousbin/magentocommands—nottomentionthecommandlineapproachissomewhatfasterandeasilyscripted.

Let'sinstallMagentowiththebuilt-inphpbin/magentosetup:installcommandandafewoftherequiredinstallationoptionsasfollows:

phpbin/magentosetup:install\

--db-host="/Applications/MAMP/tmp/mysql/mysql.sock"\

--db-name=magelicious\

--db-user=root

--db-password=root\

--admin-firstname=John\

--admin-lastname=Doe\

--admin-email=john@magelicious.loc\

--admin-user=john\

--admin-password=jrdJ%0i9a69n

Aftertheprecedingcommandhasbeenexecuted,weshouldbegintoseeconsoleprogress,startingwithsomethinglikethefollowing:

StartingMagentoinstallation:

Filepermissionscheck...

[Progress:1/513]

Requiredextensionscheck...

[Progress:2/513]

EnablingMaintenanceMode...

[Progress:3/513]

Installingdeploymentconfiguration...

[Progress:4/513]

Installingdatabaseschema:

Schemacreation/updates:

Module'Magento_Store':

[Progress:5/513]

Whileitmighttakeuptoafewminutes,asuccessfulinstallationshouldendwithamessagethat'ssimilartothefollowing:

[Progress:508/513]

Installingadminuser...

[Progress:509/513]

Cachesclearing:

Cacheclearedsuccessfully

[Progress:510/513]

DisablingMaintenanceMode:

[Progress:511/513]

Postinstallationfilepermissionscheck...

Forsecurity,removewritepermissionsfromthesedirectories:'/Users/branko/Projects/magelicious/app/etc'

[Progress:512/513]

Writeinstallationdate...

[Progress:513/513]

[SUCCESS]:Magentoinstallationcomplete.

[SUCCESS]:MagentoAdminURI:/admin_mxq00c

Nothingtoimport.

Rightafterinstallation,ourfirststepshouldbetosetMagentotodevelopermodebyusingthefollowingcommand:

phpbin/magentodeploy:mode:setdeveloper

WewilltakeacloserlookatMagentomodessoon;fornow,thisistobetakenasis.

MagentoautomaticallyassignsanadminURLduringconsoleinstallation,unlessexplicitlyspecifiedthroughtheinstallcommandviathe--backend-frontnameoption.Outofalltheinstallationoptionslisted,onlythefollowingareactuallyrequired:--admin-firstname,--admin-lastname,--admin-email,--admin-user,and--admin-password.ItisworthtakingsometimetoreadthroughtheofficialMagentodocumentation(https://devdocs.magento.com)andlookingatwhattherestoftheinstallationoptionshavetooffer.

IfallwentwellduringtheMagentoinstallation,weshouldbeabletoopenthestorefrontandadmininourbrowser.

ModesModesplayacrucialroleinMagento'sdevelopmentanddeploymentprocesses.Theyarehandledbythedeploymodule,whichcanbefoundunderthe<MAGENTO_DIR>/module-deploydirectory.

Thebuilt-inphpbin/magentocommandprovidesuswiththefollowingdeploycommands:

deploy

deploy:mode:setSetapplicationmode.

deploy:mode:showDisplayscurrentapplicationmode.

Wealreadyusedthedeploy:mode:setdevelopercommandtoswitchfromdefaulttodevelopermode.

Magentodifferentiatesbetweenfollowingthreemodes:

default:Thedefaultafter-installmode:NotoptimizedforproductionSymlinkstostaticviewfilesarepublishedtothepub/staticdirectoryErrorsandexceptionsarenotshowntotheuser,astheyareloggedtothefilesystemShouldavoidusingit

developer:Fordevelopmentsystemsonly:Symlinkstostaticviewfilesarepublishedtothepub/staticdirectoryProvidesverboseloggingEnablesautomaticcodecompilationEnablesenhanceddebuggingSlowestperformance

production:Forproductionsystems:Errorsandexceptionsarenotshowntotheuser,astheyareloggedtothefilesystemStaticviewfilesarenotmaterialized,astheyareservedfromthecacheonlyAutomaticcodefilecompilationisdisabled,asneworupdatedfilesarenotwrittentothefilesystemEnablinganddisablingthecachetypesisnotpossiblefromthe

MagentoadminFastestperformance

Carefullybalancingdevelopermodewithsomeofthecachetypesbeingenabled/disabledcanprovideoptimalperformanceduringdevelopment.

AreasTheareaisalogicalcomponentthatorganizescodeforoptimizedrequestprocessing.Whilethemajorityofthetimewedon'treallyhavetocodeanythingspecificregardingareas,understandingthemiskeytounderstandingMagento.

TheMagento\Framework\App\AreaclassAREA_*constantshintatthefollowingareas:

constAREA_GLOBAL='global';

constAREA_FRONTEND='frontend';

constAREA_ADMINHTML='adminhtml';

constAREA_DOC='doc';

constAREA_CRONTAB='crontab';

constAREA_WEBAPI_REST='webapi_rest';

constAREA_WEBAPI_SOAP='webapi_soap';

Bydoingalookupforthe<argumentname="areas"stringacrossallofthe<MAGENTO_DIR>di.xmlfiles,wecanseethatfiveoftheseareashavebeenexplicitlyaddedtotheareasargumentoftheMagento\Framework\App\AreaListclass:

adminhtmlvia<MAGENTOI_DIR>/module-backend/etc/di.xmlwebapi_restvia<MAGENTOI_DIR>/module-webapi/etc/di.xmlwebapi_soapvia<MAGENTOI_DIR>/magento/module-webapi/etc/di.xmlfrontendvia<MAGENTOI_DIR>/magento/module-store/etc/di.xmlcrontabvia<MAGENTOI_DIR>/magento/module-cron/etc/di.xml

Thedefaultareaisfrontend,asdefinedbythedefaultargumentundermodule-store/etc/di.xml.Theglobalareaisusedasafallbackforfilesthatareabsentintheadminhtmlandfrontendareas.

Let'stakeacloserlookatthe<MAGENTO_DIR>/module-webapi/etc/di.xmlfile:

<typename="Magento\Framework\App\AreaList">

<arguments>

<argumentname="areas"xsi:type="array">

<itemname="webapi_rest"xsi:type="array">

<itemname="frontName"xsi:type="string">rest</item>

</item>

<itemname="webapi_soap"xsi:type="array">

<itemname="frontName"xsi:type="string">soap</item>

</item>

</argument>

</arguments>

</type>

ThefrontNameiswhatsometimesappearsatthefrontoftheURL,whereastheareanameisusedinternallytorefertotheareainconfigurationfiles.DifferentareasdefinedbyMagentocancontaindifferentcodeforprocessingURLsandrequests.ThisallowsMagentotoloadonlythedependentcodeforthespecifiedarea.

Whendevelopingmodules,wedefinewhichresourcesarevisibleandaccessibleinagivenarea.Thisway,wegettocontrolthespecificareabehaviorifneeded.Anexampleofonesuchbehaviormightbethedefinitionoftheeventobserverunderthefrontendareaforcustomer_save_afterevent.Thisobserverwouldonlytriggeroncustomersaveoperationsthataretriggeredfromthestorefront,whichusuallyindicatesacustomerregisteraction.Theadminhtmlareaoperations,suchasMagentoadminmanuallycreatingacustomer,wouldfailtotriggerthisobserver,asitwasdefinedunderthefrontendarea.

Onoccasion,wemightneedtorunsomecodethatonlyexecutesundercertainareas.Insuchcases,emulationhelpsusemulateanystoreprogrammatically.TheMagento\Store\Model\App\EmulationclassprovidesthestartEnvironmentEmulationandstopEnvironmentEmulationmethods,whichwecanuseforthispurpose,asperthefollowingpartialexample:

protected$storeRepository;

protected$emulation;

publicfunction__construct(

\Magento\Store\Api\StoreRepositoryInterface$storeRepository,

\Magento\Store\Model\App\Emulation$emulation

){

$this->storeRepository=$storeRepository;

$this->emulation=$emulation;

}

publicfunctiontest(){

$store=$this->storeRepository->get('store-to-emulate');

$this->emulation->startEnvironmentEmulation(

$store->getId(),

\Magento\Framework\App\Area::AREA_FRONTEND

);

//Codetoexecuteinemulatedenvironment

$this->emulation->stopEnvironmentEmulation();

}

Whileitisnotacommonthingtodo,wecanfurtherregisternewareasourselves.Thisiseasilydonebyusingthemodule'sdi.xml.

RequestflowprocessingURLsinMagentohavetheformatof<AreaFrontName>/<VendorName>/<ModuleName>/<ControllerName>/<ActionName>,butthisdoesnotmeanthatweactuallyusethearea,vendor,ormodulenameintheURLanytimewewishtoaccessacertaincontroller.Forexample,theareaforarequestisdefinedbythefirstrequestpathsegment,suchasadminforadminhtmlarea,andnoneforfrontendarea.

WeusetherouterclasstoassignaURLtoacorrespondingcontrolleranditsaction.Therouter'smatchmethodfindsamatchingcontroller,whichisdeterminedbyanincomingrequest.

Conceptually,creatinganewrouterisassimpleasdoingthefollowing:

1. InjectthenewitemundertherouterListargumentoftheMagento\Framework\App\RouterListtypeviathedi.xmlfile.

2. Createarouterfile(byusingthematchmethod,whichimplements\Magento\Framework\App\RouterInterface).

3. Returnaninstanceof\Magento\Framework\App\ActionInterface.

Bydoingalookupforthename="routerList"stringacrossallofthe<MAGENTO_DIR>di.xmlfiles,wecanseethefollowingrouterdefinitions:

Magento\Robots\Controller\Router(robots)

Magento\Cms\Controller\Router(cms)

Magento\UrlRewrite\Controller\Router(urlrewrite)

Magento\Framework\App\Router\Base(standard)

Magento\Framework\App\Router\DefaultRouter(default)

Magento\Backend\App\Router(admin)

Let'stakeacloserlookattherobotsrouterunder<MAGENTO_DIR>/module-robots.etc/frontend/di.xmlinjectsthenewitemundertherouterListargumentasfollows:

<typename="Magento\Framework\App\RouterList">

<arguments>

<argumentname="routerList"xsi:type="array">

<itemname="robots"xsi:type="array">

<itemname="class"xsi:type="string">Magento\Robots\Controller\Router</item>

<itemname="disable"xsi:type="boolean">false</item>

<itemname="sortOrder"xsi:type="string">10</item>

</item>

</argument>

</arguments>

</type>

TheMagento\Robots\Controller\Routerclasshasbeenfurtherdefinedasperthefollowingpartialextract:

classRouterimplements\Magento\Framework\App\RouterInterface{

//Magento\Framework\App\ActionFactory

private$actionFactory;

//Magento\Framework\App\Router\ActionList

private$actionList;

//Magento\Framework\App\Route\ConfigInterface

private$routeConfig;

publicfunctionmatch(\Magento\Framework\App\RequestInterface$request){

$identifier=trim($request->getPathInfo(),'/');

if($identifier!=='robots.txt'){

returnnull;

}

$modules=$this->routeConfig->getModulesByFrontName('robots');

if(empty($modules)){

returnnull;

}

$actionClassName=$this->actionList->get($modules[0],null,'index','index');

$actionInstance=$this->actionFactory->create($actionClassName);

return$actionInstance;

}

}

Thematchmethodchecksiftherobots.txtfilewasrequestedandreturnstheinstanceofthematched\Magento\Framework\App\ActionInterfacetype.Byfollowingthissimpleimplementation,wecaneasilycreatetherouteofourown.

Conceptually,creatinganewcontrollerisassimpleasdoingthefollowing:

1. Registerarouteviarouter.xml.2. Createanabstractcontrollerfile(asanabstractclass,whichextends

\Magento\Framework\App\Action\Action).

3. Createanactioncontrollerfile(whichextendsthemaincontrollerfilewiththeexecutemethod,andimplements\Magento\Framework\App\ActionInterface).

4. Returnaninstanceof\Magento\Framework\Controller\ResultInterface.

Theseparationofthecontrollerintothemainandactioncontrollerfilesisnotatechnicalrequirement,butratherarecommendedorganizationalone.Magentodoesthisacrossthe

majorityofitsmodules.

Bydoingalookupforthe<routestringacrossthe<MAGENTO_DIR>routes.xmlfiles,wecanseethatMagentouseshundredsofroutedefinitions,whicharespreadacrossitsmodules.Eachrouterepresentsonecontroller.

Let'stakeacloserlookatoneofMagento'scontrollers,<MAGENTO_DIR>/module-customer,whichmapstothehttp://magelicious.loc/customer/address/formURL.Therouteitselfisregisteredviafrontend/di.xmlunderthestandardrouterwithacustomerIDandacustomerfrontName,asfollows:

<routerid="standard">

<routeid="customer"frontName="customer">

<modulename="Magento_Customer"/>

</route>

</router>

TheabstractcontrollerfileController/Address.phpisdefinedpartiallyasfollows:

abstractclassAddressextends\Magento\Framework\App\Action\Action{

//Therestofthecode...

}

Theabstractcontrolleriswherewewanttoaddfunctionalityanddependenciesthataresharedacrossallofthechildactioncontrollers.

Wecanfurtherseethreedifferentactioncontrollersdefinedwithinthesubdirectorywhichhasthesamenameastheabstractclass.TheController/Addressdirectorycontainssixactioncontrollers:Delete.php,Edit.php,Form.php,FormPost.php,Index.php,andNewAction.php.Let'stakeacloserlookatthefollowingpartialForm.phpfile'scontent:

classFormextends\Magento\Customer\Controller\Address{

publicfunctionexecute(){

/**@var\Magento\Framework\View\Result\Page$resultPage*/

$resultPage=$this->resultPageFactory->create();

$navigationBlock=$resultPage->getLayout()->getBlock('customer_account_navigation');

if($navigationBlock){

$navigationBlock->setActive('customer/address');

}

return$resultPage;

}

}

TheexamplehereusesthecreatemethodoftheinjectedMagento\Framework\View\Result\PageFactorytypetocreateanewpageresult.Thevarioustypesofcontrollerresultscanbefoundwithinthe<MAGENTO_DIR>/framework

directory:

Magento\Framework\Controller\Result\Json

Magento\Framework\Controller\Result\Raw

Magento\Framework\Controller\Result\Redirect

Magento\Framework\Controller\Result\Forward

Magento\Framework\View\Result\Layout

Magento\Framework\View\Result\Page

Wecantaketheunifiedwayofcreatingresultinstancesbyusingthecreatemethodof\Magento\Framework\Controller\ResultFactory.TheResultFactorydefinestheTYPE_*constantforeachofthementionedcontrollerresulttypes:

constTYPE_JSON='json';

constTYPE_RAW='raw';

constTYPE_REDIRECT='redirect';

constTYPE_FORWARD='forward';

constTYPE_LAYOUT='layout';

constTYPE_PAGE='page';

Keepingtheseconstantsinmind,wecaneasilywriteouractioncontrollercodeasfollows:

$resultRedirect=$this->resultFactory->create(ResultFactory::TYPE_REDIRECT);

$resultRedirect->setPath('adminhtml/*/index');

return$resultRedirect;

Aquicklookupforthe$this->resultFactory->createstring,acrosstheentire<MAGENTO_DIR>directory,cangiveuslotsofexamplesofhowtousetheResultFactoryforourowncode.

ModulesThetop-levelMagentostructureisrathersimple.Whenwestripaway(seemingly)non-relevantfilessuchaslicenses,samplefiles,andchangelogs,whatremainslooksmuchlikethefollowing:

app/

code/

design/

etc/

config.php

env.php

bin/

composer.json

composer.lock

dev/

generated/

index.php

lib/

phpserver/

pub/

static/

adminhtml/

frontend/

setup/

update/

var/

cache/

log/

page_cache/

view_preprocessed/

pub/

static/

adminhtml/

frontend/

vendor/

composer/

magento/

symfony/

Theapp/code/<VendorName>/<ModuleName>directory,<MAGELICIOUS_DIR>forshort,iswhereourcustomcodewillreside.

Whendevelopermodeisenabled,wecanmanuallycleanthecache,compilation,andstaticfilesviatherm-rfvar/cache/*&&rm-rfvar/page_cache/*&&rm-rfvar/view_preprocessed/*&&rm-rfgenerated/*&&rm-rfpub/static/*command.Underlimitedusecases,thiscanprovideafasterdevelopmentworkflow.

Thevendor/magentodirectory,<MAGENTO_DIR>forshort,iswhereMagentosourcecoderesides,asperthefollowingpartiallisting:

vendor/

magento/

composer/

framework/

language-de_de/

language-en_us/

magento-composer-installer/

magento2-base/

module-catalog/

module-checkout/

theme-adminhtml-backend/

theme-frontend-blank/

theme-frontend-luma/

Theindividualmoduledirectoryiswherethingsgetinteresting.Let'stakeaquicklookatthestructureofoneofthesimplerMagentomodules,<MAGENTO_DIR>/module-contact:

Block/

Controller/

etc/

Helper/

i18n/

Model/

Test/

view/

composer.json

LICENSE.txt

LICENSE_AFL.txt

README.md

registration.php

Thisisbynomeansthefinalstructureoftheindividualmodule.Thereareotherdirectoriesthemodulecandefine,aswewillseeaswemoveforwardthroughoutthisbook.

CreatingtheminimalmoduleLet'screatethemostminimalmodulethereisinMagento.OurmodulewillbecalledCoreanditwillbelongtotheMageliciousvendor.Theformulafordeterminingthedirectoryofcustommodulesisapp/code/<VendorName>/<ModuleName>,orinourcase<MAGELICIOUS_DIR>/Core.

Westartoffbycreatingthe<MAGELICIOUS_DIR>/Core/registration.phpfilewiththefollowingcontent:

\Magento\Framework\Component\ComponentRegistrar::register(

\Magento\Framework\Component\ComponentRegistrar::MODULE,

'Magelicious_Core',

__DIR__

);

Theregistration.phpfileisessentiallytheentrypointofourmodule.TheregistermethodoftheMagento\Framework\Component\ComponentRegistrarclassprovidestheabilitytostaticallyregistercomponents,whereasacomponentcanbemorethanjustamodule,asdefinedviathefollowingconstants:

Magento\Framework\Component\ComponentRegistrar::MODULE

Magento\Framework\Component\ComponentRegistrar::LIBRARY

Magento\Framework\Component\ComponentRegistrar::THEME

Magento\Framework\Component\ComponentRegistrar::LANGUAGE

Next,wewillcreatethe<MAGELICIOUS_DIR>/Core/etc/module.xmlfilewiththefollowingcontent:

<config>

<modulename="Magelicious_Core"setup_version="1.0.0">

<sequence>

<modulename="Magento_Store"/>

<modulename="Magento_Backend"/>

<modulename="Magento_Config"/>

</sequence>

</module>

</config>

Thenameandsetup_versionattributesofamoduleelementareconsideredrequired.Thesequence,ontheotherhand,isoptional.WeuseittodefineanypotentialdependenciesaroundotherMagentomodules.

Finally,weaddcomposer.jsonwiththefollowingcontent:

{

"name":"magelicious/module-core",

"description":"Thecoremodule",

"require":{

"php":"^7.0.0"

},

"type":"magento2-module",

"version":"1.0.0",

"license":[

"OSL-3.0",

"AFL-3.0"

],

"autoload":{

"files":[

"registration.php"

],

"psr-4":{

"Magelicious\\Core\\":""

}

}

}

Magentosupportsthefollowingcomposer.jsontypes:

magento2-moduleformodulesmagento2-themeforthemesmagento2-languageforlanguagepackagesmagento2-componentforgeneralextensionsthatdonotfitanyoftheothertypes

Thoughcomposer.jsonisnotrequiredforourcustommoduletobeseenbyMagento,itisrecommendedtoaddittoanycomponentwearebuilding.

Youcantriggermoduleinstallationbyrunningthephpbin/magentomodule:enableMagelicious_Corecommand,likeso:

$phpbin/magentomodule:enableMagelicious_Core

Thefollowingmoduleshavebeenenabled:

-Magelicious_Core

Tomakesurethattheenabledmodulesareproperlyregistered,run'setup:upgrade'.

Cacheclearedsuccessfully.

Generatedclassesclearedsuccessfully.Pleaserunthe'setup:di:compile'commandtogenerateclasses.

Info:Somemodulesmightrequirestaticviewfilestobecleared.Todothis,run'module:enable'withthe--clear-static-contentoptiontoclearthem.

Youcanrunthephpbin/magentosetup:upgradecommandtotriggeranyinstalland/orupdatescriptsthatneedtobetriggered:

Cacheclearedsuccessfully

Filesystemcleanup:

generated/code/Composer

generated/code/Magento

generated/code/Symfony

Updatingmodules:

Schemacreation/updates:

Module'Magento_Store':

...

Module'Magento_CmsUrlRewrite':

Module'Magelicious_Core':

Module'Magento_ConfigurableImportExport':

...

Nothingtoimport.

Thisfinishesourmoduleinstallation.

Creatingthe<VendorName>/Coremoduleisoftenagoodpracticewhenworkingonaprojectwithlotsofcustom<VendorName>modules.Usedcarefully,theCoremodulecanprovidecommonbitsthataresharedacrossseveralothermodules.Thetabelementofthesystem.xmlfile,whichisusedtoprovideasidebarmenupresenceunderMagento'sadminStores|Settings|Configuration,isaniceexample.Similarly,wecanuseittoprovidetop-levelaccessresourcesforothermodulestouse.

Toconfirmourmodulewasinstalledcorrectly,performthefollowing:

Checkthe<PROJECT_DIR>/app/etc/config.phpfileforthe'Magelicious_Core'=>1entryCheckthesetup_moduletablefortheMagelicious_Core1.0.01.0.0entry

Atthemoment,ourmoduledoesabsolutelynothing,asidefromjustsittingthere.However,thesefewsimplestepsarethebasisforusmovingforwardwithMagentodevelopment,becausethemajorityofthingsinMagentoaredoneviaamodule,alongsideothertypesofcomponents,whichwehavealreadymentioned.

CacheMagentomakesextensiveuseofcaching.TheSystem|Tools|CacheManagementsectionenablesustoEnable|Disable|Refreshthecachefromthecomfortofthegraphicalinterface.Duringdevelopment,theuseoftheconsoleismoreconvenientandfaster.

Thefollowingcache-relatedcommandsaresupported:

cache

cache:cleanCleanscachetype(s)

cache:disableDisablescachetype(s)

cache:enableEnablescachetype(s)

cache:flushFlushescachestorageusedbycachetype(s)

cache:statusCheckscachestatus

Outofthebox,MagentoOpenSourcecomeswith14differentcachetypes.Wecaneasilygetthestatusofeachcachetypebyrunningthephpbin/magentocache:statuscommand,whichgivesthefollowingoutput:

Currentstatus:

config:0

layout:0

block_html:0

collections:0

reflection:0

db_ddl:0

eav:0

customer_notification:0

the_custom_cache:1

config_integration:0

config_integration_api:0

full_page:0

translate:0

config_webservice:0

Wecanusetheenable|disable|cleancachecommandstoimpactoneormorecachetypesatonce.

Disabledcachetypesarenotcleaned.Usethecache:flushcommandwithcare,asflushingthecachetypepurgestheentirecachestorage.This,inturn,mightaffectotherapplicationsthatareusingthesamestorage.

Ifbuilt-incachetypesarenotenough,wecanalwayscreateourown.

CreatinganewcachetypeinMagentoisaseasyasdoingthefollowing:

Createthe<MAGELICIOUS_DIR>/Core/etc/cache.xmlfilewiththefollowingcontent:

<config>

<typename="the_custom_cache"translate="label,description"instance="Magelicious\Core\Model\Cache\TheCustomCache">

<label>TheCustomCache</label>

<description>Ourcustomcachetype</description>

</type>

</config>

Createthe<MAGELICIOUS_DIR>/Core/Model/Cache/TheCustomCache.phpfilewiththefollowingcontent:

classTheCustomCacheextends\Magento\Framework\Cache\Frontend\Decorator\TagScope{

constTYPE_IDENTIFIER='the_custom_cache';

constCACHE_TAG='THE_CUSTOM_CACHE';

publicfunction__construct(\Magento\Framework\App\Cache\Type\FrontendPool$cacheFrontendPool){

parent::__construct($cacheFrontendPool->get(self::TYPE_IDENTIFIER),self::CACHE_TAG);

}

}

TheTYPE_IDENTIFIERisusedinternallyasacachetypecodethatisuniqueamongallcachetypes.TheCACHE_TAGisacachetagthat'susedtodistinguishthecachetypefromallothercaches.Runningcache:statusshouldnowshowourcustomcachetypeonthelist.

WecanusetheinstanceofMagento\Framework\App\Cache\TypeListInterfacetoinvalidatethecache,asfollows:

$this->typeList->invalidate(\Magelicious\Core\Model\Cache\TheCustomCache::TYPE_IDENTIFIER);

WecanusetheinstanceofMagento\Framework\App\Cache\Manager$cacheManagertoprogrammaticallyexecutethesameenable|disable|cleanoperationsasperthefollowingexample:

$cacheManager->setEnabled(

[\Magelicious\Core\Model\Cache\TheCustomCache::TYPE_IDENTIFIER],

true

);

$cacheManager->clean([\Magelicious\Core\Model\Cache\TheCustomCache::TYPE_IDENTIFIER]);

$cacheManager->flush([\Magelicious\Core\Model\Cache\TheCustomCache::TYPE_IDENTIFIER]);

Savingdatatocacherequiresserialization,asperthefollowingexample:

//\Magento\Framework\Config\CacheInterface$cache

//\Magento\Framework\Serialize\SerializerInterface$serializer

//\Magento\Framework\App\Cache\StateInterface$cacheState

$isCacheEnabled=$cacheState->isEnabled(\Magelicious\Core\Model\Cache\TheCustomCache::TYPE_IDENTIFIER);

$cacheId='some-unique-identifier';

if($isCacheEnabled){

$cache->save(

$serializer->serialize('some-data'),

$cacheId,

[

\Magelicious\Core\Model\Cache\TheCustomCache::CACHE_TAG

]

);

}

Readingdatafromthecacheisaseasyasperthefollowingexample:

if($cacheData=$this->cache->load($cacheId);){

$someData=$this->getSerializer()->unserialize($cacheData);

}else{

$someData=$this->fetchSomeData();

}

DependencyinjectionDependencyinjectionhasbecomeadefactostandardofmodern-daysoftware.Magentomakesheavyuseofthistechnique,basedonmappingsfoundindi.xmlfiles.TheworkloadofMagento'sdependencyinjectionishandledbytheMagento\Framework\ObjectManager\ObjectManagerinstance,whichimplementsthelightweightMagento\Framework\ObjectManagerInterface.

Thedi.xmlfileconfigurestheobjectmanager,tellingithowtohandlethefollowing:

ArgumentinjectionVirtualtypesProxiesFactoriesPlugins

Thesefeaturesallowforagreatdegreeofflexibilityandextensibility,aswewillsoonsee.

Everymodulecanhaveaglobalandarea-specificdi.xmlfile.

Magentoloadsconfigurationfilesinthefollowingorder:

Initial(app/etc/di.xml)Global(<ModuleDir>/etc/di.xml)Area-specific(<ModuleDir>/etc/<area>/di.xml)

WhenMagentoreadsalloftheseconfigurationfiles,itmergesthemalltogetherbyappendingallnodes.

ArgumentinjectionArgumentinjectionisdoneviapreferenceandtypedefinitionswithinthedi.xml.

Byperformingalookupforthe<preferencestringacrosstheentire<MAGENTO_DIR>directory'sdi.xmlfiles,wecanseethatMagentouseshundredsofpreferencedefinitions,spreadacrossthemajorityofitsmodules.

Let'stakeaquicklookatoneofthe__constructmethod,ofthetypeMagento\Eav\Model\Attribute\Data\AbstractData:

publicfunction__construct(

\Magento\Framework\Stdlib\DateTime\TimezoneInterface$localeDate,

\Psr\Log\LoggerInterface$logger,

\Magento\Framework\Locale\ResolverInterface$localeResolver

){

$this->_localeDate=$localeDate;

$this->_logger=$logger;

$this->_localeResolver=$localeResolver;

}

Wecanfindthepreferencedefinitionsfortheseinterfacesunderthe<MAGENTO_DIR>/magento2-base/app/etc/di.xmlfile:

<preferencefor="Magento\Framework\Stdlib\DateTime\TimezoneInterface"type="Magento\Framework\Stdlib\DateTime\Timezone"/>

<preferencefor="Psr\Log\LoggerInterface"type="Magento\Framework\Logger\Monolog"/>

<preferencefor="Magento\Framework\Locale\ResolverInterface"type="Magento\Framework\Locale\Resolver"/>

Theoretically,wecanusetheobjectmanagerdirectly,asfollows:

classType{

protected$objectManager;

publicfunction__construct(

\Magento\Framework\ObjectManagerInterface$objectManager

){

$this->objectManager=$objectManager;

}

publicfunctionexample(){

$this->objectManager->create(\Fully\Qualified\Class\Name::class);

$this->objectManager->get(\Fully\Qualified\Class\Name::class);

\Magento\Framework\App\ObjectManager::getInstance()

->create(\Fully\Qualified\Class\Name::class);

\Magento\Framework\App\ObjectManager::getInstance()

->get(\Fully\Qualified\Class\Name::class);

}

}

ThedirectuseoftheobjectManagerishighlydiscouraged,asitpreventstypevalidationandtype

hintingthatafactoryclassprovides.

Bydoingalookupforthe<typestringacrosstheentire<MAGENTO_DIR>directory'sdi.xmlfiles,wecanseethatMagentousesoverathousandtypedefinitions,spreadacrossthemajorityofitsmodules.

Hereisaverysimpleexample,takenfromthe<MAGENTO_DIR>/module-customer/etc/di.xmlfile:

<typename="Magento\Customer\Model\Visitor">

<arguments>

<argumentname="ignoredUserAgents"xsi:type="array">

<itemname="google1"xsi:type="string">Googlebot/1.0(googlebot@googlebot.comhttp://googlebot.com/)</item>

<itemname="google2"xsi:type="string">Mozilla/5.0(compatible;Googlebot/2.1;+http://www.google.com/bot.html)</item>

<itemname="google3"xsi:type="string">Googlebot/2.1(+http://www.googlebot.com/bot.html)</item>

</argument>

</arguments>

</type>

LookingintothesourceoftheMagento\Customer\Model\Visitorclass,wecanseethatithasitsconstructordefinedbythe$ignoredUserAgents=[]array.Usingthetypeelement,theprecedingexampleinjectstheignoredUserAgentsargumentwiththegivenarrayvalues.

Whenconfigurationfilesforagivenscopegetmerged,arrayargumentswiththesamenamegetmergedintoanewarray.However,ifanynewconfigurationisloadedatalatertime,eitherbyamorespecificscopeorthroughthecode,thenanyarraydefinitionsinthenewconfigurationwillreplacetheloadedconfigurationinsteadofmerging.

Thelistofavailableitemtypevaluesgoeswellbeyondjustastring,andincludesthefollowing:

boolean

string

number

null

object

const

init_parameter

array

See<MAGENTO_DIR>/framework/Data/etc/argument/types.xsdand

<MAGENTO_DIR>/framework/ObjectManager/etc/config.xsdforspecifictypedefinitions.

Argumentinjectionoftengoeshandinhandwithvirtualtypes,aswewillsoonsee.

VirtualtypesVirtualtypesareaveryneatfeatureofMagentothatallowustochangetheargumentsofaspecificinjectabledependencyandthuschangethebehaviorofaparticularclasstype.

The<MAGENTO_DIR>/module-checkout/etc/di.xmlfileprovidesasimpleexampleofvirtualTypeanditsusage:

<virtualTypename="Magento\Checkout\Model\Session\Storage"type="Magento\Framework\Session\Storage">

<arguments>

<argumentname="namespace"xsi:type="string">checkout</argument>

</arguments>

</virtualType>

<typename="Magento\Checkout\Model\Session">

<arguments>

<argumentname="storage"xsi:type="object">Magento\Checkout\Model\Session\Storage</argument>

</arguments>

</type>

ThevirtualTypehere(virtually)extendsMagento\Framework\Session\Storagebyrewritingitsconstructor's$namespace='default'argumentto$namespace='checkout'.However,thischangedoesnotkickinonitsown,astheMagento\Checkout\Model\Session\Storagevirtualtypemustbeusedfirst.Itisusedinthiscase,viaatypedefinition,wherethestorageargumentisreplacedentirelybythevirtualtype.

MostofthevirtualTypenameattributesacrossMagentotaketheformofanon-existingfullyqualifiedclassname,thoughthiscanbeanycharactercombinationthat'sallowedinPHParraykeys.

Bydoingalookupforthe<virtualTypestringacrosstheentire<MAGENTO_DIR>directory'sdi.xmlfiles,wecanseethatMagentouseshundredsofvirtualtypesacrossthemajorityofitsmodules.

AmorecomplexexampleofvirtualtypeusagecanbefoundundertheMagento_LayeredNavigationmodule.

The<MAGENTO_DIR>/module-layered-navigation/etc/frontend/di.xmlfiledefinestwovirtualtypes,asfollows:

<virtualTypename="Magento\LayeredNavigation\Block\Navigation\Category"type="Magento\LayeredNavigation\Block\Navigation">

<arguments>

<argumentname="filterList"xsi:type="object">categoryFilterList</argument>

</arguments>

</virtualType>

<virtualTypename="Magento\LayeredNavigation\Block\Navigation\Search"type="Magento\LayeredNavigation\Block\Navigation">

<arguments>

<argumentname="filterList"xsi:type="object">searchFilterList</argument>

</arguments>

</virtualType>

Here,wehavetwovirtualtypesdefined,eachchangingthefilterListargumentoftheMagento\LayeredNavigation\Block\Navigationclass.categoryFilterListandsearchFilterListarethenamesoftwoothervirtualtypesthataredefinedin<MAGENTO_DIR>/module-catalog-search/etc/di.xml,asvisiblehere:https://github.com/magento/magento2/blob/2.2/app/code/Magento/CatalogSearch/etc/di.xml.

TheMagento\LayeredNavigation\Block\Navigation\CategoryandMagento\LayeredNavigation\Block\Navigation\Searchvirtualtypesarethenusedinlayoutfilesforblockdefinition,asfollows:

<!--view/frontend/layout/catalog_category_view_type_layered.xml-->

<referenceContainername="sidebar.main">

<blockclass="Magento\LayeredNavigation\Block\Navigation\Category"...

</referenceContainer>

<!--view/frontend/layout/catalogsearch_result_index.xml-->

<referenceContainername="sidebar.main">

<blockclass="Magento\LayeredNavigation\Block\Navigation\Search"...

</referenceContainer>

WhatthiseffectivelydoesistellMagentothat,forthecategoryviewpageandsearchpage,usethevirtualtypeforclass,thusinstructingittogothroughalltheargumentchangesspecifiedinthevirtualtype.

Thisisaninterestingexampleasitrevealsthepotentialcomplexityofusingvirtualtypes.Basically,wehaveonevirtualtype(Magento\LayeredNavigation\Block\Navigation\Search)changingthesinglefilterListargumentofarealtype(Magento\LayeredNavigation\Block\Navigation)withanothervirtualtype(categoryFilterList).Likewise,wejustlearnedhowtheclasspropertyoftheblockelementiscapableofnotjustacceptingthefullyqualifiedclassname,butthevirtualTypenameaswell.

ProxiesProxyclassesareusedwhenobjectcreationisexpensiveandaclass'constructorisunusuallyresource-intensive.Toavoidunnecessaryperformanceimpact,MagentousesProxyclassestoturngiventypesintobecominglazy-loadedversionsofthem.

Aquicklookupforthe\Proxy</argument>stringacrossallMagentodi.xmlfilesrevealsoverahundredoccurrencesofthisstring.ItgoestosaythatMagentoextensivelyusesproxiesacrossitscode.

Thetypedefinitionunder<MAGENTO_DIR>/module-customer/etc/di.xmlisaniceexampleofusingproxies:

<typename="Magento\Customer\Model\Session">

<arguments>

<argumentname="configShare"xsi:type="object">Magento\Customer\Model\Config\Share\Proxy</argument>

<argumentname="customerUrl"xsi:type="object">Magento\Customer\Model\Url\Proxy</argument>

<argumentname="customerResource"xsi:type="object">Magento\Customer\Model\ResourceModel\Customer\Proxy</argument>

<argumentname="storage"xsi:type="object">Magento\Customer\Model\Session\Storage</argument>

<argumentname="customerRepository"xsi:type="object">Magento\Customer\Api\CustomerRepositoryInterface\Proxy</argument>

</arguments>

</type>

IfwelookattheconstructoroftheMagento\Customer\Model\Sessiontype,wecanseethatnoneofthefourarguments(configShare,customerUrl,customerResource,andcustomerRepository)weredeclaredasProxywithinthePHPfile.Theywhererewrittenthroughdi.xml.TheseProxytypesdonotreallyexistjustyet,astheMagentodependencyinjection(di)compilationprocesscreatesthem.Theyareautomaticallygeneratedunderthegenerateddirectory.

Onceitiscompiled,theMagento\Customer\Model\Url\Proxytypecaneasilybefoundunderthegenerated/code/Magento/Customer/Model/Url/Proxy.phpfile.Let'stakeapartiallookatit:

classProxyextends\Magento\Customer\Model\Url

implements\Magento\Framework\ObjectManager\NoninterceptableInterface{

publicfunction__construct(

\Magento\Framework\ObjectManagerInterface$objectManager,

$instanceName='\\Magento\\Customer\\Model\\Url',

$shared=true){

$this->_objectManager=$objectManager;

$this->_instanceName=$instanceName;

$this->_isShared=$shared;

}

publicfunction__sleep(){

return['_subject','_isShared','_instanceName'];

}

publicfunction__wakeup(){

$this->_objectManager=\Magento\Framework\App\ObjectManager::getInstance();

}

publicfunction__clone(){

$this->_subject=clone$this->_getSubject();

}

protectedfunction_getSubject(){

if(!$this->_subject){

$this->_subject=true===$this->_isShared

?$this->_objectManager->get($this->_instanceName)

:$this->_objectManager->create($this->_instanceName);

}

return$this->_subject;

}

publicfunctiongetLoginUrl(){

return$this->_getSubject()->getLoginUrl();

}

publicfunctiongetLoginUrlParams(){

return$this->_getSubject()->getLoginUrlParams();

}

}

ThecompositionoftheProxyclassshowsthemechanismbywhichitwrapsaroundtheoriginalMagento\Customer\Model\Urltype.Thisnowmeansthat,acrossMagento,everytimetheMagento\Customer\Model\Urltypeisrequested,theMagento\Customer\Model\Url\Proxyisgoingtogetpassedinstead.Unliketheoriginaltype's__constructmethodwhichmightbeperformanceheavy,theautogeneratedProxy's__constructmethodisalightweightone.Thiseliminatespossibleperformancebottlenecks.The_getSubjectmethodisusedtoinstantiate/lazyloadtheoriginaltypewheneveranyoftheoriginaltypepublicmethodsarecalled.Forexample,thecalltothegetLoginUrlmethodwouldgothroughtheproxy.

EveryproxygeneratedbyMagentoimplementsMagento\Framework\ObjectManager\NoninterceptableInterface.Thoughtheinterfaceitselfisempty,itisusedasamarkertoidentifyproxiesforwhichwedon'tneedtogenerateinterceptors(plugins).

Whenwritingcustomtypes,suchasMagelicious\Core\Model\Customer,wecouldeasilyspecifytheproxyrightthereintheconstructor:

classCustomer{

publicfunction__construct(

\Magento\Customer\Model\Url\Proxy$customerUrl

){

//...

}

}

Thisapproach,however,isabadpractice.Thewaytodothisproperlyistospecify__constructwithanoriginalMagento\Customer\Model\Urltypeandthenaddthedi.xmlasfollows:

<typename="Magelicious\Core\Model\Customer">

<arguments>

<argumentname="customerUrl"xsi:type="object">Magento\Customer\Model\Url\Proxy</argument>

</arguments>

</type>

FactoriesFactoriesareclassesthatcreateotherclasses—muchliketheobjectmanager,exceptthistimeweareencouragedtousethemdirectly.Theirpurposeistoinstantiatethenon-injectableclasses—thosethatweshouldnotinjectdirectlyinto__construct.Thebeautyofusingfactoriesisthat,mostofthetime,wedon'tevenhavetowritethem,astheyareautomaticallygeneratedbyMagentounlessweneedtoimplementsomesortofspecificbehaviorforourfactoryclasses.

BydoingalookupfortheFactory$stringacrosstheentire<MAGENTO_DIR>directory's*.phpfiles,wecanseethousandsoffactoryexamples,spreadacrossthemajorityofMagento'smodules.

Whileagreatdealofthesefactoriesactuallyexist,othersareautomaticallygeneratedwhenneeded.

Let'stakeaquicklookatoneautomaticallygeneratedfactory,thatofMagento\Newsletter\Model\SubscriberFactory,whichisusedinseveralMagentomodulessuchasthenewsletter,subscriber,andreviewmodules:

classSubscriberFactory{

protected$_objectManager=null;

protected$_instanceName=null;

publicfunction__construct(

\Magento\Framework\ObjectManagerInterface$objectManager,

$instanceName='\\Magento\\Newsletter\\Model\\Subscriber'

){

$this->_objectManager=$objectManager;

$this->_instanceName=$instanceName;

}

publicfunctioncreate(array$data=array()){

return$this->_objectManager->create($this->_instanceName,$data);

}

}

Theautogeneratedfactorycodeisessentiallyjustathinwrapperontopofanobjectmanagercreatemethod.

Factoriesworkwellwiththedi.xmlpreferencemechanism,whichmeanswecaneasilypassinterfacesintotheconstructor,likeso:

publicfunction__construct(

\Magento\CatalogInventory\Api\StockItemRepositoryInterface$stockItemRepository,

\Magento\CatalogInventory\Api\StockItemCriteriaInterfaceFactory$stockItemCriteriaFactory

){

$this->stockItemRepository=$stockItemRepository;

$this->stockItemCriteriaFactory=$stockItemCriteriaFactory;

}

//$criteria=$this->stockItemCriteriaFactory->create();

//$result=$this->stockItemRepository->getList($criteria);

Thepreferencemechanismmakessurethatconcreteimplementationsgetpassedtotheobjectinstancewhenitsconstructorisinvoked.

Whileindevelopermode,Magentoperformsautomaticcompilation,meaningthatchangestodi.xmlareautomaticallypickedup.Sometimes,however,ifwestumbleuponunexpectedresults,runningthebin/magentosetup:di:compileconsolecommandorevenmanuallyclearingthegeneratedfolder(rm-rfgenerated/*)mighthelpsortouttheissues.

PluginsPluginsarelikelyoneofthemostpowerfulfeaturesofMagento.Theyallowustomodifythebehaviorofpublicclassfunctionsbyinterceptingafunctioncallandrunningcodebefore,after,oraroundthatfunctioncall.

Beforeweeagerlystartusingthem,itisworthemphasizinghowpluginscan'tbeusedonthefollowing:

FinalmethodsFinalclassesNon-publicmethodsClassmethods(suchasstaticmethods)__construct

VirtualtypesObjectsthatareinstantiatedbeforeMagentoorFramework\Interceptionisbootstrapped

Pluginscanbeusedonthefollowing:

ClassesInterfacesAbstractclassesParentclasses

Bydoingalookupforthe<pluginstringacrosstheentire<MAGENTO_DIR>directory'sdi.xmlfiles,wecanseehundredsofpluginexamplesspreadacrossthemajorityofMagento'smodules.

ThebeforepluginThebeforeplugin,asitsnamesuggests,runsbeforetheobservedmethod.

Whenwritingabeforeplugin,thereareafewkeypointstoremember:

1. Thebeforekeywordisappendedtotheobservedinstancemethod.IftheobservedmethodiscalledgetSomeValue,thenthepluginmethodiscalledbeforeGetSomeValue.

2. Thefirstparameterofthebeforepluginmethodisalwaystheobservedinstancetype,oftenabbreviatedas$subjectordirectlybytheclasstype–whichis$processorinourexample.Wecantypecastitforgreaterreadability.

3. Allotherparametersofthepluginmethodmustmatchtheparametersoftheobservedmethod.

4. Thepluginmethodmustreturnanarraywiththesametypeandnumberofparametersastheobservedmethod'sinputparameters.

Let'stakealookatoneofMagento'sbeforepluginimplementations,theonespecifiedinthe<MAGENTO_DIR>module-payment/etc/frontend/di.xmlfile:

<typename="Magento\Checkout\Block\Checkout\LayoutProcessor">

<pluginname="ProcessPaymentConfiguration"

type="Magento\Payment\Plugin\PaymentConfigurationProcess"/>

</type>

TheoriginalmethodthispluginistargetingistheprocessmethodoftheMagento\Checkout\Block\Checkout\LayoutProcessorclass:

publicfunctionprocess($jsLayout){

//Therestofthecode...

return$jsLayout;

}

TheimplementationofthebeforepluginisprovidedviathebeforeProcessmethodoftheMagento\Payment\Plugin\PaymentConfigurationProcessclass,asperthefollowingpartialexample:

publicfunctionbeforeProcess(

\Magento\Checkout\Block\Checkout\LayoutProcessor$processor,

$jsLayout){

//Therestofthecode...

return[$jsLayout];

}

ThearoundpluginThearoundpluginrunsaroundtheobservedmethodinawaythatallowsustorunsomecodebeforeandaftertheoriginalmethodcall.Thisisaverypowerfulconcept,aswegettochangetheincomingparametersaswellasthereturnvalueofafunction.

Whenwritingthearoundplugin,thereareafewkeypointstoremember:

1. Thefirstparametercomingintothepluginistheobservedtypeinstance.2. Thesecondparametercomingintothepluginisacallable/Closure.Usually,

thisparameteristypedandnamedascallable$proceed.Wemustmakesuretoforwardthesameparameterstothiscallableastheoriginalmethodsignature.

3. Allotherparametersareparametersoftheoriginalobservedmethod.4. Thepluginmustreturnthesamevalueastheoriginalfunction,ideallyreturn

$proceed(…)or$returnValue=$proceed();followedby$returnValue;forcaseswhereweneedtomodifythe$returnValue.

Let'stakealookatoneofMagento'saroundpluginimplementations,theonespecifiedinthe<MAGENTO_DIR>module-grouped-product/etc/di.xmlfile:

<typename="Magento\Catalog\Model\ResourceModel\Product\Link">

<pluginname="groupedProductLinkProcessor"type="Magento\GroupedProduct\Model\ResourceModel\Product\Link\RelationPersister"/>

</type>

TheoriginalmethodofthispluginistargetingthedeleteProductLinkmethodoftheMagento\Catalog\Model\ResourceModel\Product\Linkclass:

publicfunctiondeleteProductLink($linkId){

return$this->getConnection()

->delete($this->getMainTable(),['link_id=?'=>$linkId]);

}

TheimplementationofthearoundpluginisprovidedviathearoundDeleteProductLinkmethodoftheMagento\GroupedProduct\Model\ResourceModel\Product\Link\RelationPersisterclass,asperthefollowingpartialexample:

publicfunctionaroundDeleteProductLink(

\Magento\GroupedProduct\Model\ResourceModel\Product\Link$subject,

\Closure$proceed,$linkId){

//Therestofthecode...

$result=$proceed($linkId);

//Therestofthecode...

return$result;

}

TheafterpluginTheafterplugin,asitsnamesuggests,runsaftertheobservedmethod.

Whenwritingtheafterplugin,thereareafewkeypointstoremember:

1. Thefirstparametercomingintothepluginisanobservedtypeinstance.2. Thesecondparametercomingintothepluginistheresultoftheobserved

method,oftencalled$resultorcalledafterthevariablereturnedfromtheobservedmethod(asinthefollowingexample:$data).

3. Allotherparametersareparametersoftheobservedmethod.4. Thepluginmustreturnthesame$result|$datavariableofthesametype,as

wearefreetomodifythevalue.

Let'stakealookatoneofMagento'safterpluginimplementations,theonespecifiedinthemodule-catalog/etc/di.xmlfile:

<typename="Magento\Indexer\Model\Config\Data">

<pluginname="indexerProductFlatConfigGet"

type="Magento\Catalog\Model\Indexer\Product\Flat\Plugin\IndexerConfigData"/>

</type>

TheoriginalmethodthispluginistargetingisthegetmethodoftheMagento\Indexer\Model\Config\Dataclass:

publicfunctionget($path=null,$default=null){

//Therestofthecode...

return$data;

}

TheimplementationoftheafterpluginisprovidedviatheafterGetmethodoftheMagento\Catalog\Model\Indexer\Product\Flat\Plugin\IndexerConfigDataclass,asperthefollowingpartialexample:

publicfunctionafterGet(Magento\Indexer\Model\Config\Data,$data,$path=null,$default=null){

//Therestofthecode...

return$data;

}

Specialcareshouldbetakenwhenusingplugins.Whiletheyprovidegreatflexibility,theyalsomakeiteasytoinducebugs,performancebottlenecks,andotherlessobvioustypesofinstabilities–evenmoresoifseveralpluginsare

observingthesamemethod.

EventsandobserversMagentohasaneatpublish-subscribepatternimplementationthatwecalleventsandobservers.Bydispatchingeventswhencertainactionsaretriggered,wecanrunourcustomcodeinresponsetothetriggeredevent.TheeventsaredispatchedusingtheMagento\Framework\Event\Managerclass,whichimplementsMagento\Framework\Event\ManagerInterface.

Todispatchanevent,wesimplycallthedispatchmethodoftheeventmanagerinstance,providingitwiththenameoftheeventwearedispatchingwithanoptionalarrayofdatawewishtopassontotheobservers,asperthefollowingexampletakenfromthe<MAGENTO_DIR>/module-customer/Controller/Account/CreatePost.phpfile:

$this->_eventManager->dispatch(

'customer_register_success',

['account_controller'=>$this,'customer'=>$customer]

);

Observersareregisteredviaanevents.xmlfile,asperthefollowingexamplefromthe<MAGENTO_DIR>/module-persistent/etc/frontend/events.xmlfile:

<eventname="customer_register_success">

<observername="persistent"instance="Magento\Persistent\Observer\RemovePersistentCookieOnRegisterObserver"/>

</event>

BydoingalookupfortheeventManager->dispatchstringacrosstheentire<MAGENTO_DIR>directory's*.phpfiles,wecanseehundredsofeventsexamples,spreadacrossthemajorityofMagento'smodules.Whilealloftheseeventsareofthesametechnicalimportance,wemightsaythatsomearelikelytobeusedmoreonadaytodaybasisthanothers.

Thismakesitworthtakingsometimetostudythefollowingclassesandtheeventstheydispatch:

TheMagento\Framework\App\Action\Actionclass,withthefollowingevents:controller_action_predispatch

'controller_action_predispatch_'.$request->getRouteName()

'controller_action_predispatch_'.$request->getFullActionName()

'controller_action_postdispatch_'.$request->getFullActionName()

'controller_action_postdispatch_'.$request->getRouteName()

controller_action_postdispatch

TheMagento\Framework\Model\AbstractModelclass,withthefollowingevents:model_load_before

$this->_eventPrefix.'_load_before'

model_load_after

$this->_eventPrefix.'_load_after'

model_save_commit_after

$this->_eventPrefix.'_save_commit_after'

model_save_before

$this->_eventPrefix.'_save_before'

model_save_after

clean_cache_by_tags

$this->_eventPrefix.'_save_after'

model_delete_before

$this->_eventPrefix.'_delete_before'

model_delete_after

clean_cache_by_tags

$this->_eventPrefix.'_delete_after'

model_delete_commit_after

$this->_eventPrefix.'_delete_commit_after'

$this->_eventPrefix.'_clear'

TheMagento\Framework\Model\ResourceModel\Db\Collectionclass,withthefollowingevents:

core_collection_abstract_load_before

$this->_eventPrefix.'_load_before'

core_collection_abstract_load_after

$this->_eventPrefix.'_load_after'

Somemoreimportanteventscanbefoundinafewofthetypesdefinedunderthe<MAGENTO_DIR>/framework/Viewdirectory:

view_block_abstract_to_html_before

view_block_abstract_to_html_after

view_message_block_render_grouped_html_after

layout_render_before

'layout_render_before_'.$this->request->getFullActionName()

core_layout_block_create_after

layout_load_before

layout_generate_blocks_before

layout_generate_blocks_after

core_layout_render_element

Let'stakeacloserlookatoneoftheseevents,theonefoundinthe<MAGENTO_DIR>/framework/Model/AbstractModel.phpfile:

publicfunctionafterCommitCallback(){

$this->_eventManager->dispatch('model_save_commit_after',['object'=>$this]);

$this->_eventManager->dispatch($this->_eventPrefix.'_save_commit_after',$this->_getEventData());

return$this;

}

protectedfunction_getEventData(){

return[

'data_object'=>$this,

$this->_eventObject=>$this,

];

}

The$_eventPrefixand$_eventObjecttypepropertiesareparticularlyimportanthere.IfweglimpseovertypessuchasMagento\Catalog\Model\Product,Magento\Catalog\Model\Category,Magento\Customer\Model\Customer,Magento\Quote\Model\Quote,Magento\Sales\Model\Order,andothers,wecanseethatagreatdealoftheseentitytypesareessentiallyextendingfromMagento\Framework\Model\AbstractModelandprovidetheirownvaluestoreplace$_eventPrefix='core_abstract'and$_eventObject='object'.Whatthismeansisthatwecanuseeventssuchas$this->_eventPrefix.'_save_commit_after'tospecifyobserversviaevents.xml.

Let'stakealookatthefollowingexample,takenfromthe<MAGENTO_DIR>/module-downloadable/etc/events.xmlfile:

<config>

<eventname="sales_order_save_commit_after">

<observername="downloadable_observer"instance="Magento\Downloadable\Observer\SetLinkStatusObserver"/>

</event>

</config>

Observersareplacedinsidethe<ModuleDir>/Observerdirectory.EveryobserverimplementsasingleexecutemethodontheMagento\Framework\Event\ObserverInterfaceclass:

classSetLinkStatusObserverimplements\Magento\Framework\Event\ObserverInterface{

publicfunctionexecute(\Magento\Framework\Event\Observer$observer){

$order=$observer->getEvent()->getOrder();

}

}

Muchlikeplugins,badlyimplementedobserverscaneasilycausebugsorevenbreaktheentireapplication.Thisiswhyweneedtokeepourobserversmallandcomputationallyefficient—toavoidperformancebottlenecks.

Thecyclicaleventloopisatrapthat'seasytofallinto.Thishappenswhenanobserver,atsomepoint,isdispatchingthesameeventthatitlistensto.Forexample,ifanobserverlistenstothemodel_save_beforeevent,andthentriestosavethesameentityagainwithintheobserver,thiswouldtriggeracyclicaleventloop.

Tomakeourobserversasspecificaspossible,weneedtodeclaretheminanappropriatescope:

Forobservingfrontendonlyevents,youcandeclareobserversin<ModuleDir>/etc/frontend/events.xml

Forobservingbackendonlyevents,youcandeclareobserversin<ModuleDir>/etc/adminhtml/events.xml

Forobservingglobalevents,youcandeclareobserversin<ModuleDir>/etc/events.xml

Unlikeplugins,observersareusedfortriggeringthefollow-upfunctionality,ratherthanchangingthebehavioroffunctionsordatawhichispartoftheeventtheyareobserving.

ConsolecommandsThebuilt-inbin/magentotoolplaysamajorrole–notjustinMagentodevelopment,butinproductiondeploymentsaswell.

Rightoutofthebox,itprovidesadozencommandsthatwecanusetomanagecaches,indexers,dependencycompilation,deployingstaticviewfiles,creatingCSSfromLESS,puttingourstoretomaintenance,installingmodules,andmore.

Quiteeasily,MagentoenablesustoaddourowncommandstoitsSymfony-likecommand-lineinterface(CLI).TheMagentoCLIessentiallyextendsfromSymfony\Component\Console\Command.

Therealvalueincreatingourowncommandliesintheargumentsandoptionsthatwecanmakeavailable,thuspassingdynamicinformationtothecommand.

Magentoconsolecommandsresideunderthe<ModuleName>/Consoledirectory,whichcanfurtherbeorganizedtobetteraccommodateourcommands.Magentomostlyusesthe<ModuleName>/Console/CommanddirectorytoplacetheactualCLIcommandclass,whereasvariousoptionsandotheraccompanyingclassesresideinthe<ModuleName>/Consoledirectory.

Conceptually,creatinganewCLIcommandisaseasyasdoingthefollowing:

1. Creatingthecommandclass2. Wiringitupviadi.xml3. Clearingthecacheandcompileddirectories

Let'screateourownsimpleconsolecommand.Wewillstartoffbycreatingthe<MAGELICIOUS_DIR>/Core/Console/Command/RunStockImportCommand.phpfilewiththefollowingcontent:

useSymfony\Component\Console\Command\Command;

useSymfony\Component\Console\Input\InputArgument;

useSymfony\Component\Console\Input\InputOption;

useSymfony\Component\Console\Input\InputInterface;

useSymfony\Component\Console\Output\OutputInterface;

classRunStockImportCommandextendsCommand{

constORDER_ID_ARGUMENT='order_id';

constDAYS_BACK_OPTION='days_back';

protectedfunctionconfigure(){

$this->setName('magelicious:stock:import')

->setDescription('TheMageliciousStockImport.')

->setDefinition([

newInputArgument(

self::ORDER_ID_ARGUMENT,/*name*/

InputArgument::REQUIRED,/*modeREQUIREDorOPTIONAL*/

'Theargumenttoset.',/*description*/

null/*default*/

),

newInputOption(

self::DAYS_BACK_OPTION,/*name*/

null,/*shortcut*/

InputOption::VALUE_OPTIONAL,/*VALUE_NONEorVALUE_REQUIREDorVALUE_OPTIONALorVALUE_IS_ARRAY*/

'Theoptiontoset.'/*description*/

)

]);

parent::configure();

}

protectedfunctionexecute(InputInterface$input,OutputInterface$output){

try{

$output->setDecorated(true);

//$input->getArgument(self::ORDER_ID_ARGUMENT);

//$input->getOption(self::DAYS_BACK_OPTION);

//greentext

$output->writeln('<info>Theinfomessage.</info>');

//yellowtext

$output->writeln('<comment>Thecommentmessage.</comment>');

//blacktextonacyanbackground

$output->writeln('<question>Thequestionmessage.</question>');

return\Magento\Framework\Console\Cli::RETURN_SUCCESS;

}catch(\Exception$e){

//whitetextonaredbackground

$output->writeln('<error>'.$e->getMessage().'</error>');

if($output->getVerbosity()>=OutputInterface::VERBOSITY_VERBOSE){

$output->writeln($e->getTraceAsString());

}

return\Magento\Framework\Console\Cli::RETURN_FAILURE;

}

}

}

Wethenwireitupvia<MAGELICIOUS_DIR>/etc/di.xml,asfollows:

<typename="Magento\Framework\Console\CommandListInterface">

<arguments>

<argumentname="commands"xsi:type="array">

<itemname="runStockImport"xsi:type="object">Magelicious\Core\Console\Command\RunStockImportCommand</item>

</argument>

</arguments>

</type>

Wecannowclearthecacheandthecompileddirectorieseitherbyrunningthephpbin/magentocache:cleanconfigfollowedbyphpbin/magentosetup:di:compile,orbyrunningrm-rfgenerated/*andrm-rfvar/cache/*.

Now,ifwerunthephpbin/magentocommand,weshouldseeourcommandonthelist:

magelicious

magelicious:stock:importTheMageliciousStockImport.

Ifwenowtestourmethodbyrunningphpbin/magentomagelicious:stock:import,thisshouldimmediatelytriggeranerror,asfollows:

[Symfony\Component\Console\Exception\RuntimeException]

Notenougharguments(missing:"order_id").

magelicious:stock:import[--days_back[DAYS_BACK]][--]<order_id>

Eitherofthefollowingcallsshouldwork:

phpbin/magentomagelicious:stock:import000000060

phpbin/magentomagelicious:stock:import000000060--days_back=7

CronjobsCreatinganewcronjobisaseasyasdoingthefollowing:

1. Creatingajobdefinitionunderthe<ModuleName>/etc/crontab.xmlfile2. Creatingaclasswithapublicmethodthathandlesthejobexecution

Let'screateasimplecronjob.Wewillstartoffbycreatingthe<MAGELICIOUS_DIR>/Core/etc/crontab.xmlfilewiththefollowingcontent:

<groupid="default">

<jobname="the_job"instance="Magelicious\Core\Cron\TheJob"method="execute">

<schedule>*/15****</schedule>

</job>

</group>

Theinstanceandmethodvaluesmaptotheclassandmethodwithinthatclass,whichwillbeexecutedwhencronjobisrun.Thescheduleisacron,liketheexpressionforwhenthejobistobeexecuted.Unlesstherearespecificrequirementstellingusotherwise,wecansafelyusethedefaultgroup.

Wethencreatethe<MAGELICIOUS_DIR>/Core/Cron/TheJob.phpfilewiththefollowingcontent:

classTheJob{

publicfunctionexecute(){

//...

}

}

TheMagentoconsolecommandsupportsseveralconsolecommands:

cron

cron:installGeneratesandinstallscrontabforcurrentuser

cron:removeRemovestasksfromcrontab

cron:runRunsjobsbyschedule

Togetourcronjobrunning,weneedtomakesurethatcrontabisinstalled,byrunningphpbin/magentocron:install.Thiscommandgeneratesandinstallscrontabforthecurrentuser.Wecanconfirmthatbyfollowingupwiththecrontab-ecommand,likeso:

#~MAGENTOSTART6f7c468a10aea2972eab1da53c8d2fce

*****/bin/php/magelicious/bin/magentocron:run2>&1|grep-v"Ranjobsbyschedule">>/magelicious/var/log/magento.cron.log

*****/bin/php/magelicious/update/cron.php>>/magelicious/var/log/update.cron.log

*****/bin/php/magelicious/bin/magentosetup:cron:run>>/magelicious/var/log/setup.cron.log

#~MAGENTOEND6f7c468a10aea2972eab1da53c8d2fce

Now,ifweexecutephpbin/magentocron:run,the_jobshouldfinditswayunderthecron_scheduletable.

Dependingontheschedule_generate_everyandschedule_ahead_foroptionsforaparticularcrongroup,wemightnotseesomecronjobsinstantlyshowingupinthecron_scheduletable.

MagentoOpenSourceprovidestwocrongroups:defaultandindex.Whilethemajorityoftimesourcronjobswillbeplacedunderthedefaultgroup,theremightbeaneedtocreateacompletelynewcrongroup.Luckily,thisisquiteeasy.

Tocreateanewcrongroup,allweneedisa<MAGELICIOUS_DIR>/etc/cron_groups.xmlfilewiththefollowingcontent:

<config>

<groupid="magelicious">

<schedule_generate_every>15</schedule_generate_every>

<schedule_ahead_for>20</schedule_ahead_for>

<schedule_lifetime>15</schedule_lifetime>

<history_cleanup_every>10</history_cleanup_every>

<history_success_lifetime>10080</history_success_lifetime>

<history_failure_lifetime>10080</history_failure_lifetime>

<use_separate_process>0</use_separate_process>

</group>

</config>

Whilegroupinformationisnotstoredinthecron_scheduletable,wecanuseitviatheMagentoCLItorunjobsthatarespecifictoacertaingroup:

phpbin/magentocron:run--group=default

SummaryInthischapter,wetoucheduponsomeofMagento'skeyscomponents.PluginsandeventobserversprovideapowerfulwayofextendingMagento,eitherbychangingthebehaviorofexistingfunctionsorbyrunningsomefollow-upcodeinresponsetocertainevents.

Movingforward,wewilldeepenourMagentoknowledgefurtherbylookingintotheinstallandupdatescripts,theEntity–Attribute–Valuemodel(EAV),creatingnewEAVtypes,indexers,extension,andcustomattributes.

WorkingwithEntitiesEveryMagentomodulehostsitsmodelswithintheModelsdirectory.Someofthesemodelsarepersistable,whileothersarenon-persistable.Agreatdealofcustom,third-party,andcoreMagentomodulespersistdatatothedatabase.DatapersistenceisoneofthekeyfunctionalitiesthatplatformslikeMagentoneedtodealwith.Terminology-wise,Magentousestermssuchasmodel,resourcemodel,andcollectionforagroupofthreeclassesthatdealwithdatapersistence,thatis,create,read,update,anddelete(CRUD)operations.

Tobetterunderstandtheoverallmechanismofentities,wearegoingtotakeacloserlookatthefollowing:

Understandingtypesofmodels:CreatingasimplemodelMethodsworthmemorizing

Workingwithsetupscripts:TheInstallSchemascriptTheUpgradeSchemascriptTheRecurringscriptTheInstallDatascriptTheUpgradeDatascriptTheRecurringDatascript

Creatingextensionattributes

TechnicalrequirementsYouwillneedtohavebasicknowledgeofPHP,OOP,JavaScript,andXML.YouwillalsoneedApache,MySQL,andAMPPSinstalledonyoursystemtoexecutethecodes.

ThecodefilesofthischaptercanbefoundonGitHub:https://github.com/PacktPublishing/Magento-2-Quick-Start-Guide.

CheckoutthefollowingvideotoseetheCodeinAction:

http://bit.ly/2PKYvUx.

UnderstandingtypesofmodelsTherearetwotypesofpersistencemodelsinMagento:simpleandEntity–attribute–value(EAV).Thetermentityistossedaroundinterchangeablybetweenthetwotypesofmodels.Wecanthinkofanentityasanypersistablemodel.

TheSubscriberentityoftheMagento_Newslettermoduleisanexampleofasimplemodel.Wecanseethatit'scomprisedofthefollowing:

AmodeloftypeMagento\Newsletter\Model\SubscriberextendsMagento\Framework\Model\AbstractModel

AresourcemodeloftypeMagento\Newsletter\Model\ResourceModel\SubscriberextendsMagento\Framework\Model\ResourceModel\Db\AbstractDbAcollectionoftypeMagento\Newsletter\Model\ResourceModel\Subscriber\CollectionextendsMagento\Framework\Model\ResourceModel\Db\Collection\AbstractCollection

TheCustomerentityoftheMagento_CustomermoduleisanexampleofanEAVmodel.Wecanseethatit'scomprisedofthefollowing:

AmodeloftypeMagento\Customer\Model\CustomerextendsMagento\Framework\Model\AbstractModelAresourcemodeloftypeMagento\Customer\Model\ResourceModel\CustomerextendsMagento\Eav\Model\Entity\VersionControl\AbstractEntityAcollectionoftypeMagento\Customer\Model\ResourceModel\Customer\CollectionextendsMagento\Eav\Model\Entity\Collection\VersionControl\AbstractCollection

WhatdifferentiatesEAVfromsimplemodelsisessentiallytheirresourcemodelandcollectionclasses.Theresourcemodelisourlinktothedatabase—ourpersistor,ifyouwill.

Whenasubscriberissaved,itsdatagetssavedhorizontallyinthedatabase.Datafromthesubscribermodelgetsdumpedintothesinglenewsletter_subscribertable.

Whenacustomerissaved,itsdatagetssavedverticallyinthedatabase.Data

fromthecustomermodelgetsdumpedintothefollowingtables:

customer_entity

customer_entity_datetime

customer_entity_decimal

customer_entity_int

customer_entity_text

customer_entity_varchar

Thedecisionastowheretostoreavalueforanindividualattributeiscontainedintheeav_attribute.backend_typecolumn.TheSELECTDISTINCTbackend_typeFROMeav_attribute;queryrevealsthefollowing:

Thestaticattributevaluegetsstoredinthe<entityName>_entitytableThevarcharattributevaluegetsstoredinthe<entityName>_entity_varchartableTheintattributevaluegetsstoredinthe<entityName>_entity_inttableThetextattributevaluegetsstoredinthe<entityName>_entity_texttableThedatetimeattributevaluegetsstoredinthe<entityName>_entity_datetimetableThedecimalattributevaluegetsstoredinthe<entityName>_entity_decimaltable

Nexttotheeav_attributetable,theremainingrelevantinformationisscatteredaroundthedozenofothereav_*tables,themostimportantbeingtheeav_attribute_*tables:

eav_attribute

eav_attribute_group

eav_attribute_label

eav_attribute_option

eav_attribute_option_swatch

eav_attribute_option_value

eav_attribute_set

TheSELECTentity_type_code,entity_modelFROMeav_entity_type;queryindicatesthatthefollowingMagentoentitiesarefromanEAVmodel:

customer:Magento\Customer\Model\ResourceModel\Customercustomer_address:Magento\Customer\Model\ResourceModel\Addresscatalog_category:Magento\Catalog\Model\ResourceModel\Categorycatalog_product:Magento\Catalog\Model\ResourceModel\Product

order:Magento\Sales\Model\ResourceModel\Orderinvoice:Magento\Sales\Model\ResourceModel\Order\Invoicecreditmemo:Magento\Sales\Model\ResourceModel\Order\Creditmemoshipment:Magento\Sales\Model\ResourceModel\Order\Shipment

However,notallofthemusetheEAVmodeltoitsfullextent,asindicatedbytheSELECTDISTINCTentity_type_idFROMeav_attribute;query,whichpointsonlytothefollowing:

customer

customer_address

catalog_category

catalog_product

WhatthismeansisthatonlyfourmodelsinMagentoOpenSourcereallyuseEAVmodelsformanagingtheirattributesandstoringdataverticallythroughEAVtables.Therestareallflattables,asallattributesandtheirvaluesareinasingletable.

TheEAVmodelsareinherentlymorecomplextoworkwith.Theycomeinhandyforcaseswheredynamicattributecreationisneeded,ideallyviaanadmininterface,asisthecasewithproducts.Themajorityofthetime,however,simplemodelswilldothejob.

CreatingasimplemodelUnlikeEAVmodels,creatingsimplemodelsisprettystraightforward.Let'sgoaheadandcreateamodel,resourcemodel,andacollectionforaLogentity.

Wewillstartoffbycreatingthe<MAGELICIOUS_DIR>/Core/Model/Log.phpfilewiththefollowingcontent:

classLogextends\Magento\Framework\Model\AbstractModel{

protected$_eventPrefix='magelicious_core_log';

protected$_eventObject='log';

protectedfunction_construct(){

$this->_init(\Magelicious\Core\Model\ResourceModel\Log::class);

}

}

Theuseof$_eventPrefixand$_eventObjectisnotmandatory,butitishighlyrecommended.ThesevaluesareusedbytheMagento\Framework\Model\AbstractModeleventdispatcherandaddtothefutureextensibilityofourmodule.WhileMagentousesthe<ModuleName>_<ModelName>conventionfor$_eventPrefixnaming,wemightbesaferusing<VendorName>_<ModuleName>_<ModelName>.The$_eventObject,byconvention,usuallybearsthenameofthemodelitself.

Wethencreatethe<MAGELICIOUS_DIR>/Core/Model/ResourceModel/Log.phpfilewiththefollowingcontent:

classLogextends\Magento\Framework\Model\ResourceModel\Db\AbstractDb{

protectedfunction_construct(){

$this->_init('magelicious_core_log','entity_id');

}

}

The_initmethodheretakestwoarguments:themagelicious_core_logvalueforthe$mainTableargumentandtheentity_idvalueforthe$idFieldNameargument.The$idFieldNameisthenameoftheprimarycolumninthedesignateddatabase.It'sworthnotingthatthemagelicious_core_logtablestilldoesn'texist,butwewilladdressthatinabit.

Wewillthencreatethe<MAGELICIOUS_DIR>/Core/Model/ResourceModel/Log/Collection.phpfilewiththefollowingcontent:

classCollectionextends\Magento\Framework\Model\ResourceModel\Db\Collection\AbstractCollection{

protectedfunction_construct(){

$this->_init(

\Magelicious\Core\Model\Log::class,

\Magelicious\Core\Model\ResourceModel\Log::class

);

}

}

The_initmethodheretakestwoarguments:thestringnamesof$modeland$resourceModel.Magentousesthe<FULLY_QUALIFIED_CLASS_NAME>::classsyntaxforthis,asitusesaniftysolutioninsteadofpassingclassstringsaround.

MethodsworthmemorizingBothEAVandsimplemodelsextendfromtheMagento\Framework\Model\AbstractModelclass,whichfurtherextendsfromMagento\Framework\DataObject.TheDataObjecthassomeneatmethodsworthmemorizing.

Groupofthefollowingmethodsdealwithdatatransformation:

toArray:Convertsanarrayofobjectdatatoanarraywithkeysrequestedinthe$keysarraytoXml:ConvertsobjectdataintoanXMLstringtoJson:ConvertsobjectdatatoJSONtoString:Convertsobjectdataintoastringwithapredefinedformatserialize:Convertsobjectdataintoastringwithdefinedkeysandvalues

Theothergroupsofthesemethods,implementedthroughthemagic__callmethod,enablesthefollowingneatsyntax:

get<AttributeName>,forexample,$object->getPackagingOption()set<AttributeName>,forexample,$object->setPackagingOption('plastic_bag')uns<AttributeName>,forexample,$object->unsPackagingOption()has<AttributeName>,forexample,$object->hasPackagingOption()

Toquicklyputthismagicintoperspective,let'smanuallycreatethemagelicious_core_logtableasfollows:

CREATETABLE`magelicious_core_log`(

`entity_id`int(10)unsignedNOTNULLAUTO_INCREMENT,

`severity_level`varchar(24)NOTNULL,

`note`textNOTNULL,

`created_at`timestampNOTNULLDEFAULTCURRENT_TIMESTAMPONUPDATECURRENT_TIMESTAMP,

PRIMARYKEY(`entity_id`)

)ENGINE=InnoDBDEFAULTCHARSET=utf8;

WiththemagicofDataObject,ouremptyMagelicious\Core\Model\Logmodelwillstillbeabletosaveitsdata,asfollows:

$log->setCreatedAt(new\DateTime());

$log->setSeverityLevel('info');

$log->setNote('JustSomeNote');

$log->save();

Whilethisexamplewouldwork,thereisfarmoretoitthanthis.Creatingtablesmanuallyisnotaviableoptionforbuildingmodules.Magentohasjusttherightmechanismforthis,whichiscalledsetupscripts.

WorkingwithsetupscriptsEverytimeamoduleisinstalledviaaphpbin/magentomodule:enablecommand,Magentoshowsthefollowingmessage:Tomakesurethattheenabledmodulesareproperlyregistered,run'setup:upgrade'.Thephpbin/magentosetup:upgradecommandupgradestheMagentoapplication,databasedata,andschema.Oncetriggered,theupgradecommandinstantiatesMagento\Setup\Model\Installer,whichthengoesthroughaseriesofmethods.ItsgetSchemaDataHandlermethodrevealsthetypesofavailablesetupscripts:

InstallSchema.php

UpgradeSchema.php

Recurring.php

InstallData.php

UpgradeData.php

RecurringData.php

Thesescriptsliveunderthe<VendorName>/<ModuleName>/Setupdirectory.

Oncesuccessfullyfinished,thesetup:upgradecommandmakesanewentry,orupdatesanexistingone,inthesetup_moduletable.There,wecanseetheschema_versionanddata_versionvaluesloggedagainsteachmodule.

Whentestingoutsetupscripts,wecanmanuallydeleteandadjustourmoduleentriesunderthesetup_moduletabletotriggerindividualtypeofsetupscript.Forexample,wecanleaveschema_versionasis,whilechangingthedata_version.

Let'stakeacloserlookatwritingeachofthosescripts.

TheInstallSchemascriptTheInstallSchemascriptisusedwhenwewishtoaddnewcolumnstoexistingtablesorcreatenewtables.Thisscriptisrunonlywhenamoduleisenabled.Onceenabled,themodulegetsacorrespondingentryunderthesetup_module.schema_versiontablecolumn.ThisentrypreventstheInstallSchemascriptrunningonanysubsequentsetup:upgradecommandwherethemodule'ssetup_versionremainsthesame.

Let'sgoaheadandcreatethe<MAGELICIOUS_DIR>/Core/Setup/InstallSchema.phpfilewiththefollowingcontent:

use\Magento\Framework\Setup\InstallSchemaInterface;

useMagento\Framework\Setup\ModuleContextInterface;

useMagento\Framework\Setup\SchemaSetupInterface;

classInstallSchemaimplementsInstallSchemaInterface{

publicfunctioninstall(SchemaSetupInterface$setup,ModuleContextInterface$context){

$setup->startSetup();

echo'InstallSchema->install()'.PHP_EOL;

$setup->endSetup();

}

}

Theuseof$setup->startSetup();and$setup->endSetup();isacommonpracticeamongthemajorityofsetupscripts.Theimplementationofthesetwomethodsdealswithrunningadditionalenvironmentsetupsteps,suchassettingSQL_MODEandFOREIGN_KEY_CHECKS,ascanbeseenunderMagento\Framework\DB\Adapter\Pdo\Mysql.

Tomakesomethingusefuloutofit,let'sgoaheadandreplacetheecholinewiththecodethatactuallycreatesourmagelicious_core_logtable:

$table=$setup->getConnection()

->newTable($setup->getTable('magelicious_core_log'))

->addColumn(

'entity_id',

\Magento\Framework\DB\Ddl\Table::TYPE_INTEGER,

null,

['identity'=>true,'unsigned'=>true,'nullable'=>false,'primary'=>true],

'EntityID'

)->addColumn(

'severity_level',

\Magento\Framework\DB\Ddl\Table::TYPE_TEXT,

24,

['nullable'=>false],

'SeverityLevel'

)->addColumn(

'note',

\Magento\Framework\DB\Ddl\Table::TYPE_TEXT,

null,

['nullable'=>false],

'Note'

)->addColumn(

'created_at',

\Magento\Framework\DB\Ddl\Table::TYPE_TIMESTAMP,

null,

['nullable'=>false],

'CreatedAt'

)->setComment('MageliciousCoreLogTable');

$setup->getConnection()->createTable($table);

$setup->getConnection()getsusthedatabaseadapterinstance.Fromthereon,wegetaccesstomethodsthatareneededfordatabasetablecreation.WhenitcomestoInstallSchemascripts,themajorityofthetime,thefollowingmethodswilldothejob:

newTable:RetrievesaDDLobjectforthenewtableaddColumn:AddscolumnstothetableaddIndex:AddsanindextothetableaddForeignKey:AddsaforeignkeytothetablesetComment:SetsacommentforthetablecreateTable:CreatesatablefromaDDLobject

Themagelicious_core_logtablehereisessentiallystoragebehindourMagelicious\Core\Model\Logsimplemodel.IfourmodelwasanEAVmodel,wewouldbeusingthesameInstallSchemascripttocreatetablessuchasthefollowing:

log_entity

log_entity_datetime

log_entity_decimal

log_entity_int

log_entity_text

log_entity_varchar

However,inthecaseoftheEAVmodel,theactualattributesseverity_levelandnotewouldthenlikelybeaddedviaanInstallDatascript.Thisisbecauseattributesdefinitionsareessentiallydataundertheeav_attribute_*tables—primarilytheeav_attributetable.Therefore,attributesarecreatedinsideoftheInstallDataandUpgradeDatascripts.

TheUpgradeSchemascriptTheUpgradeSchemascriptisusedwhenwewishtocreatenewtablesoraddcolumnstoexistingtables.Giventhatitisrunoneverysetup:upgrade,wheresetup_module.schema_versionislowerthansetup_versionunder<VendorName>/<ModuleName>/etc/module.xml,weareinchargeofcontrollingthecodeforaspecificversion.Thisisusuallydoneviatheif-edversion_compareapproach.

Tobetterdemonstratethis,let'screatethe<MAGELICIOUS_DIR>/Core/Setup/UpgradeSchema.phpfilewiththefollowingcontent:

use\Magento\Framework\Setup\UpgradeSchemaInterface;

useMagento\Framework\Setup\ModuleContextInterface;

useMagento\Framework\Setup\SchemaSetupInterface;

classUpgradeSchemaimplementsUpgradeSchemaInterface{

publicfunctionupgrade(SchemaSetupInterface$setup,ModuleContextInterface$context){

$setup->startSetup();

if(version_compare($context->getVersion(),'2.0.2')<0){

$this->upgradeToVersionTwoZeroTwo($setup);

}

$setup->endSetup();

}

privatefunctionupgradeToVersionTwoZeroTwo(SchemaSetupInterface$setup){

echo'UpgradeSchema->upgradeToVersionTwoZeroTwo()'.PHP_EOL;

}

}

Theif-edversion_compareherereadsasfollows:ifthecurrentmoduleversionisequalto2.0.2,thenexecutetheupgradeToVersionTwoZeroTwomethod.Ifweweretoreleaseanupdatedversionofourmodule,wewouldneedtoproperlybumpupthesetup_versionof<VendorName>/<ModuleName>/etc/module.xml,orelseUpgradeSchemadoesnotmakealotofsense.Likewise,weshouldalwaysbesuretotargetaspecificmoduleversion,thusavoidingcodethatexecutesoneveryversionchange.

WhenitcomestoUpgradeSchemascripts,thefollowingmethodsofadatabaseadapterinstance,alongsidethepreviouslymentionedone,willbeofinterest:

dropColumn:DropsthecolumnfromatabledropForeignKey:DropstheforeignkeyfromatabledropIndex:Dropstheindexfromatable

dropTable:DropsthetablefromadatabasemodifyColumn:Modifiesthecolumndefinition

TheRecurringscriptTheRecurringscriptsexecutesoneachandeverysetup:upgradecommand,regardlessoftheschema_versionordata_versionloggedagainstthesetup_moduletable.

Let'screatethe<MAGELICIOUS_DIR>/Core/Setup/Recurring.phpfilewiththefollowingcontent:

useMagento\Framework\Setup\InstallSchemaInterface;

useMagento\Framework\Setup\ModuleContextInterface;

useMagento\Framework\Setup\SchemaSetupInterface;

classRecurringimplementsInstallSchemaInterface{

publicfunctioninstall(SchemaSetupInterface$setup,ModuleContextInterface$context){

$setup->startSetup();

echo'Recurring->install()'.PHP_EOL;

$setup->endSetup();

}

}

Thoughinteresting,theRecurringscriptsarerarelyusedinMagento.Onlyahandfulofthemareused,andthatismostlyforinstallingexternalforeignkeys.Thisisnottosaythatwecannotusethemforourpurposes–itisjustthattheirusecaseisquitelimitedwhenwethinkaboutit.

TheInstallDatascriptTheInstallDatascriptisusedwhenwewishtoaddnewdatatoexistingtables.Thisscriptisrunonlywhenamoduleisenabled.Onceenabled,themodulegetsacorrespondingentryunderthesetup_module.data_versiontablecolumn.ThisentrypreventstheInstallDatascripttorunonanysubsequentsetup:upgradecommandexecution,wherethemodule'ssetup_versionremainsthesame.

Let'screatethe<MAGELICIOUS_DIR>/Core/Setup/InstallData.phpfilewiththefollowingcontent:

use\Magento\Framework\Setup\InstallDataInterface;

useMagento\Framework\Setup\ModuleContextInterface;

useMagento\Framework\Setup\ModuleDataSetupInterface;

classInstallDataimplementsInstallDataInterface{

publicfunctioninstall(ModuleDataSetupInterface$setup,ModuleContextInterface$context){

$setup->startSetup();

echo'InstallData->install()'.PHP_EOL;

$setup->endSetup();

}

}

Chancesare,wewillbeinteractingwiththistypeofscriptmoreoftenthannot.ReplacingtheecholinewithmodifiedpiecesoftheequivalentMagentoInstallDatascriptmightgiveusabetterunderstandingofthepossibilitiesbehindthesescripts.

TheUpgradeDatascriptLet'screatethe<MAGELICIOUS_DIR>/Core/Setup/UpgradeData.phpfilewiththefollowingcontent:

useMagento\Framework\Setup\ModuleContextInterface;

useMagento\Framework\Setup\ModuleDataSetupInterface;

classUpgradeDataimplements\Magento\Framework\Setup\UpgradeDataInterface{

publicfunctionupgrade(ModuleDataSetupInterface$setup,ModuleContextInterface$context){

$setup->startSetup();

if(version_compare($context->getVersion(),'2.0.2')<0){

$this->upgradeToVersionTwoZeroTwo($setup);

}

$setup->endSetup();

}

privatefunctionupgradeToVersionTwoZeroTwo(ModuleDataSetupInterface$setup){

echo'UpgradeData->upgradeToVersionTwoZeroTwo()'.PHP_EOL;

}

}

Let'sgoaheadandreplacetheecholinewithsomethingpractical,likeaddinganewcolumntoanexistingtable:

$salesSetup=$this->salesSetupFactory->create(['setup'=>$setup]);

$salesSetup->addAttribute('order','merchant_note',[

'type'=>\Magento\Framework\DB\Ddl\Table::TYPE_TEXT,

'visible'=>false,

'required'=>false

]);

Here,weusedtheinstanceofMagento\Sales\Setup\SalesSetupFactory,injectedthrough__construct.ThisfurthercreatesaninstanceoftheMagento\Sales\Setup\SalesSetupclass.WeneedthisclassinordertocreatesalesEAVattributes.Theorderentityissomewhatofastrangemix;whileitisregisteredasanEAVtypeofentityundertheeav_entity_typetable,itdoesnotreallyuseeav_attribute_*tables–itusesasinglesales_ordertabletostoreitsattributes.Wecouldhaveeasilyused(Install|Upgrade)Schemascriptstosimplyaddanewcolumnvia$setup->getConnection()->addColumn().Onceexecuted,thiscodeaddsthemerchant_notecolumntothesales_ordertable.Wewillusethiscolumnlateron,aswereachtheExtendingentitiessection.

TheRecurringDatascriptMuchlikerecurringscripts,theRecurringDatascriptsarerarelyusedinMagento.Theyalsoexecuteoneachandeverysetup:upgradecommand,regardlessoftheschema_versionordata_versionloggedagainstthesetup_moduletable.MagentoOpenSourceusesmerelythreeRecurringDatascriptsthroughoutitscodebase.

Let'screatethe<MAGELICIOUS_DIR>/Core/Setup/RecurringData.phpfilewiththefollowingcontent:

useMagento\Framework\Setup\InstallDataInterface;

useMagento\Framework\Setup\ModuleContextInterface;

useMagento\Framework\Setup\ModuleDataSetupInterface;

classRecurringDataimplementsInstallDataInterface{

publicfunctioninstall(ModuleDataSetupInterface$setup,ModuleContextInterface$context){

$setup->startSetup();

echo'RecurringData->install()'.PHP_EOL;

$setup->endSetup();

}

}

Thesetupscriptsprovideawayforustomanagethedataanditsrepresentationinthedatabase.Whereasaddinganewattributetosimplemodelislikelyacaseofextendingitstablebyanextracolumn(*Schemascripts),addinganewattributetoanEAVmodelisamatterofaddingnewdataundertheeav_attributetable(*Datascripts).

ExtendingentitiesWeextendentitiesbyaddingadditionalattributestothem.ReferringbacktothemagicalgetterandsettermethodsmentionedinthecontextofMagento\Framework\DataObject,thelogicalthinkingmightbe:what'sthebigdeal;can'twejustaddnewdatabasecolumnsviaUpgradeSchemaandusemagicalgetterandsettermethodstogoaroundit?Theanswerisbothyesandno,butmainlyleaningtowardno–wewillsoonlearnwhy.

Tobetterexplainthis,let'stakealookatMagento\Sales\Model\Order,theentitymodel.ThismodelimplementstheMagento\Sales\Api\Data\OrderInterfaceinterface,whichfurtherextendsMagento\Framework\Api\ExtensibleDataInterface.Here,wecanseeaconstantdefiningakeyfortheextensionattributesobject.Thisissomewhatofastartingpointforextendingentities.Sufficetosay,thereisanextraabstractionlayerontopofsomeofthemodels.Thisabstractionlayer,calledservicecontracts,isasetofPHPinterfacesthatensureawell-defined,durableAPIthatothermodulesandthird-partyextensionsmightimplement.

This,however,iseasiersaidthandone.Whenyouthinkaboutit,ifwehadamodulethat'salreadyheavilyinuse,addingevenasimpleattributetooneofitsentitymodelsmightbreakitsfunctionality.Thisiswhereextensionattributescomeintothepicture.

CreatingextensionattributesCreatinganewextensionattributeforanexistingentityisusuallyacaseofdoingthefollowing:

1. Usingsetupscriptstosettheattribute,column,ortableforpersistence2. Definingtheextensionattributevia

<VendorName>/<ModuleName>/etc/extension_attributes.xml

3. Addinganafterand/orbeforeplugintothesave,get,andgetListmethodsofanentityrepository

Movingforward,wearegoingtocreateextensionattributesfortheorderentity,thatis,customer_noteandmerchant_note.

Wecanimaginecustomer_noteasanattributethatdoesnotpersistitsvalue(s)inthesales_ordertableasorderentitydoes,whereasmerchant_noteattributedoes.Thisiswhywecreatedthesales_order.merchant_notecolumnearlierviatheUpgradeData

script.

Let'sgoaheadandcreatethe<MAGELICIOUS_DIR>/Core/Api/Data/CustomerNoteInterface.phpfilewiththefollowingcontent:

interfaceCustomerNoteInterfaceextends\Magento\Framework\Api\ExtensibleDataInterface

{

constCREATED_BY='created_by';

constNOTE='note';

publicfunctionsetCreatedBy($createdBy);

publicfunctiongetCreatedBy();

publicfunctionsetNote($note);

publicfunctiongetNote();

}

Thecustomer_noteattributeisgoingtobeafull-blownobject,sowewillcreateaninterfaceforit.

Whileomittedintheexample,besuretosetthedocblocksoneachmethod,otherwisetheMagentowebAPIwillthrowanEachgettermusthaveadocblockerroroncewehookupthepluginmethods.

Wewillthencreatethe<MAGELICIOUS_DIR>/Core/Model/CustomerNote.phpfilewiththe

followingcontent:

classCustomerNoteextends\Magento\Framework\Model\AbstractExtensibleModelimplements\Magelicious\Core\Api\Data\CustomerNoteInterface

{

publicfunctionsetCreatedBy($createdBy){

return$this->setData(self::CREATED_BY,$createdBy);

}

publicfunctiongetCreatedBy(){

return$this->getData(self::CREATED_BY);

}

publicfunctiongetNote(){

return$this->getData(self::NOTE);

}

publicfunctionsetNote($note){

return$this->setData(self::NOTE,$note);

}

}

Thisclassisessentiallyourcustomer_noteentitymodel.Tokeepthingsminimal,wewilljustimplementtheCustomerNoteInterface,withoutanyextralogic.

Wewillthengoaheadandcreatethe<MAGELICIOUS_DIR>/Core/etc/extension_attributes.xmlfilewiththefollowingcontent:

<?xmlversion="1.0"?>

<config>

<extension_attributesfor="Magento\Sales\Api\Data\OrderInterface">

<attributecode="customer_note"type="Magelicious\Core\Api\Data\CustomerNoteInterface"/>

<attributecode="merchant_note"type="string"/>

</extension_attributes>

</config>

Theextension_attributes.xmlfileiswhereweregisterourextensionattributes.Thetypeargumentallowsustoregistereithercomplextypes,suchasaninterface,orscalartypes,suchasastringorinteger.Withtheextensionattributesregistered,itistimetoregisterthecorrespondingplugins.Thisisdoneviathedi.xmlfile.

Let'sgoaheadandcreatethe<MAGELICIOUS_DIR>/Core/etc/di.xmlfilewiththefollowingcontent:

<?xmlversion="1.0"?>

<config>

<preferencefor="Magelicious\Core\Api\Data\CustomerNoteInterface"type="Magelicious\Core\Model\CustomerNote"/>

<typename="Magento\Sales\Api\OrderRepositoryInterface">

<pluginname="customerNoteToOrderRepository"type="Magelicious\Core\Plugin\CustomerNoteToOrderRepository"/>

<pluginname="merchantNoteToOrderRepository"type="Magelicious\Core\Plugin\MerchantNoteToOrderRepository"/>

</type>

</config>

Thereasonforregisteringpluginsinthefirstplaceistohaveourcustomer_noteandmerchant_noteattributesavailableonthegetList,get,andsavemethodsoftheMagento\Sales\Api\OrderRepositoryInterfaceinterface.TherepositoryinterfacesarethemainwayofCRUD-ingentitiesunderservicecontracts.Withoutproperplugins,Magentosimplywouldnotseeourattributes.

Let'screatethe<MAGELICIOUS_DIR>/Core/Plugin/CustomerNoteToOrderRepository.phpfilewiththefollowingcontent:

classCustomerNoteToOrderRepository{

protected$orderExtensionFactory;

protected$customerNoteInterfaceFactory;

publicfunction__construct(

\Magento\Sales\Api\Data\OrderExtensionFactory$orderExtensionFactory,

\Magelicious\Core\Api\Data\CustomerNoteInterfaceFactory$customerNoteInterfaceFactory

){

$this->orderExtensionFactory=$orderExtensionFactory;

$this->customerNoteInterfaceFactory=$customerNoteInterfaceFactory;

}

privatefunctiongetCustomerNoteAttribute(

\Magento\Sales\Api\Data\OrderInterface$resultOrder

){

$extensionAttributes=$resultOrder->getExtensionAttributes()?:$this->orderExtensionFactory->create();

//TODO:Getcustomernotefromsomewhere(belowwefakeit)

$customerNote=$this->customerNoteInterfaceFactory->create()

->setCreatedBy('Mark')

->setNote('Thenote'.\time());

$extensionAttributes->setCustomerNote($customerNote);

$resultOrder->setExtensionAttributes($extensionAttributes);

return$resultOrder;

}

privatefunctionsaveCustomerNoteAttribute(

\Magento\Sales\Api\Data\OrderInterface$resultOrder

){

$extensionAttributes=$resultOrder->getExtensionAttributes();

if($extensionAttributes&&$extensionAttributes->getCustomerNote()){

//TODO:Save$extensionAttributes->getCustomerNote()somewhere

}

return$resultOrder;

}

}

Rightnow,therearenopluginmethodsdefined.getCustomerNoteAttributeandsaveCustomerNoteAttributeareessentiallyhelpermethodsthatwewillsoonuse.

Let'sextendourCustomerNoteToOrderRepositoryclassbyaddingtheafterpluginforthegetListmethod,asfollows:

publicfunctionafterGetList(

\Magento\Sales\Api\OrderRepositoryInterface$subject,

\Magento\Sales\Model\ResourceModel\Order\Collection$resultOrder

){

foreach($resultOrder->getItems()as$order){

$this->afterGet($subject,$order);

}

return$resultOrder;

}

Now,let'sextendourCustomerNoteToOrderRepositoryclassbyaddingtheafterpluginforthegetmethod,asfollows:

publicfunctionafterGet(

\Magento\Sales\Api\OrderRepositoryInterface$subject,

\Magento\Sales\Api\Data\OrderInterface$resultOrder

){

$resultOrder=$this->getCustomerNoteAttribute($resultOrder);

return$resultOrder;

}

Finally,let'sextendourCustomerNoteToOrderRepositoryclassbyaddingtheafterpluginforthesavemethod,asfollows:

publicfunctionafterSave(

\Magento\Sales\Api\OrderRepositoryInterface$subject,

\Magento\Sales\Api\Data\OrderInterface$resultOrder

){

$resultOrder=$this->saveCustomerNoteAttribute($resultOrder);

return$resultOrder;

}

Withthepluginsforcustomer_notesorted,let'sgoaheadandaddressthepluginsformerchant_note.Wewillcreatethe<MAGELICIOUS_DIR>/Core/Plugin/MerchantNoteToOrderRepository.phpfilewiththefollowingcontent:

classMerchantNoteToOrderRepository{

protected$orderExtensionFactory;

publicfunction__construct(

\Magento\Sales\Api\Data\OrderExtensionFactory$orderExtensionFactory

){

$this->orderExtensionFactory=$orderExtensionFactory;

}

privatefunctiongetMerchantNoteAttribute(

\Magento\Sales\Api\Data\OrderInterface$order

){

$extensionAttributes=$order->getExtensionAttributes()?:$this->orderExtensionFactory->create();

$extensionAttributes->setMerchantNote($order->getData('merchant_note'));

$order->setExtensionAttributes($extensionAttributes);

return$order;

}

privatefunctionsaveMerchantNoteAttribute(

\Magento\Sales\Api\Data\OrderInterface$order

){

$extensionAttributes=$order->getExtensionAttributes();

if($extensionAttributes&&$extensionAttributes->getMerchantNote()){

$order->setData('merchant_note',$extensionAttributes->getMerchantNote());

}

return$order;

}

}

Rightnow,therearenopluginmethodsdefined.getMerchantNoteAttributeandsaveMerchantNoteAttributeareessentiallyhelpermethodsthatwewillsoonuse.

Let'sextendourMerchantNoteToOrderRepositoryclassbyaddingtheafterpluginforthegetListmethod,asfollows:

publicfunctionafterGetList(

\Magento\Sales\Api\OrderRepositoryInterface$subject,

\Magento\Sales\Model\ResourceModel\Order\Collection$order

){

foreach($order->getItems()as$_order){

$this->afterGet($subject,$_order);

}

return$order;

}

Now,let'sextendourMerchantNoteToOrderRepositoryclassbyaddingtheafterpluginforthegetmethod,asfollows:

publicfunctionafterGet(

\Magento\Sales\Api\OrderRepositoryInterface$subject,

\Magento\Sales\Api\Data\OrderInterface$order

){

$order=$this->getMerchantNoteAttribute($order);

return$order;

}

Finally,let'sextendourMerchantNoteToOrderRepositoryclassbyaddingthebeforepluginforthesavemethod,asfollows:

publicfunctionbeforeSave(

\Magento\Sales\Api\OrderRepositoryInterface$subject,

\Magento\Sales\Api\Data\OrderInterface$order

){

$order=$this->saveMerchantNoteAttribute($order);

return[$order];

}

Theobviousdifferencehereisthat,withMerchantNoteToOrderRepository,weareusingbeforeSave,whereasweusedafterSavewithCustomerNoteToOrderRepository.Thereasonforthisisthatmerchant_noteistobesaveddirectlyontheentitywhoserepositoryweareplugginginto,thatis,itstableinthesales_orderdatabase.This

way,weuseitsMagento\Framework\DataObjectpropertiesofsetDatatofetchwhatwasassuminglynotealreadysetviaextensionattributesandpassitontotheobject'smerchant_notepropertybeforeitissaved.Magento'sbuilt-insavemechanismthentakesoverandstorestheproperty,aslongasthecorrespondingcolumnexistsinthedatabase.

Withthepluginsinplace,ourattributesshouldnowbevisibleandpersistablewhenusedthroughtheOrderRepositoryInterface.WithoutgettingtoodeepintothewebAPIatthispoint,wecanquicklytestthisviaperformingthefollowingRESTrequest:

GET/index.php/rest/V1/orders?searchCriteria[filter_groups][0][filters][0][field]=entity_id&searchCriteria[filter_groups][0][filters][0][value]=1

Host:magelicious.loc

Content-Type:application/json

Authorization:Bearer0vq6d4kabpxgc5kysb2sybf3n4ct771x

WhereastheBearertokenissomethingwegetbyrunningthefollowingRESTloginaction:

POST/index.php/rest/V1/integration/admin/token

Host:magelicious.loc

Content-Type:application/json

{"username":"john","password":"grdM%0i9a49n"}

ThesuccessfulresponseofGET/V1/ordersshouldyieldaresultofthefollowingpartialstructure:

{

"items":[

{

"extension_attributes":{

"shipping_assignments":[...],

"customer_note":{

"created_by":"Mark",

"note":"NoteABC"

},

"merchant_note":"NoteXYZ"

}

}

]

}

Wecanseethatourtwoattributesarenicelynestedwithintheextension_attributeskey.

Postman,theAPIdevelopmenttool,makesiteasytotestAPIs.Seehttps://www.getpostman.comformoreinformation.

TheOrderRepositoryInterfacetowebAPIRESTrelationshipmapsoutasfollows:

getList:GET/V1/orders(plusthesearchcriteriapart)get:GET/V1/orders/:idsave:POST/V1/orders/create

WewilllearnmoreaboutthewebAPIinthenextchapter.Theexamplegivenherewasmerelyforthepurposeofvisualizingtheworkwehavedonearoundplugins.Usingextensionattributes,withthehelpofplugins,wehaveessentiallyextendedtheMagentowebAPI.

SummaryThroughoutthischapter,welearnedhowtodifferentiatethethreetypesofMagentomodels:non-persistable,persistablesimple,andpersistableEAV.TheinnersofEAVmodelsareleftoutofscopeduetotheirinherentlycomplexnature.Wethentookalookthroughsixdifferentsetupscripts.Thesegiveusagreatdealofflexibilityoverschemaanddatamanagement.Combinedwithextensionattributes,wegetapowerfulmechanismforextendingbuilt-inentities.Thoughsomewhattedious,theextensionattributesmechanismuseofinterfacesensuresthatintegratorscanextendthisbuilt-infunctionalitywithcomplexdatatypes.

Movingforward,wearegoingtotakealookatthepowerfulwebAPIthat'simplementedinMagento.

UnderstandingWebAPIsWebapplicationprogramminginterfaces(API)playamajorroleinmodernapplicationdevelopment.Theyallowvariousthird-partyintegratorstointeractwithapplicationsthroughtheHTTPlayer.MagentosupportsbothRepresentationalStateTransfer(REST)andSimpleObjectAccessProtocol(SOAP)APIs.ItswebAPIframeworkisbasedonthecreate,read,update,delete(CRUD)andsearch(searchcriteria)models.ThescopeoffunctionalitythatAPIsofferisquitebig,allowingustousethemforawiderangeoftasks,suchascreatingacompletelynewshoppingapplication,integratingwithcustomerrelationshipmanagement(CRM)systems,enterpriseresourceplanning(ERP)systems,andcontentmanagementsystems(CMS),aswellascreatingJavaScriptwidgetsintheMagentostorefrontitself.

Movingforward,wearegoingtotakeacloserlookatthefollowingwebAPIsections:

TypesofusersTypesofauthenticationTypesofendpointsUsingexistingWebAPIsCreatingcustomWebAPIsUnderstandingsearchcriteria

TechnicalrequirementsYouwillneedtohavebasicknowledgeofPHP,OOP,JavaScript,andXML.YouwillalsoneedApache,MySQL,andAMPPSinstalledonyoursystemtoexecutethecodes.

ThecodefilesofthischaptercanbefoundonGitHub:https://github.com/PacktPublishing/Magento-2-Quick-Start-Guide.

CheckoutthefollowingvideotoseetheCodeinAction:

http://bit.ly/2Oz3Gqs.

TypesofusersTheMagentowebAPIframeworkdifferentiatesthreefundamentaltypesofusers:

Guest:Authorizedagainstananonymousresource:

<resources>

<resourceref="anonymous"/>

</resources>

Customer:Authorizedagainstaselfresource:

<resources>

<resourceref="self"/>

</resources>

Integrator:Authorizedagainstaspecificresourcedefinedinacl.xml:

<resources>

<resourceref="Magento_Cms::save""/>

</resources>

Tofurtherunderstandwhatthismeans,weneedtounderstandthelinkbetween<VendorName>/<ModuleName>/acl.xmland<VendorName>/<ModuleName>/webapi.xml.

Theacl.xmliswherewedefineouraccessresources.Let'stakeacloserlookatthepartialextractofonesuchresource,definedinthe<MAGENTO_DIR>/module-cms/etc/acl.xmlfile:

<config>

<acl>

<resources>

<resourceid="Magento_Backend::admin">

<resourceid="Magento_Backend::content">

<resourceid="Magento_Backend::content_elements">

<resourceid="Magento_Cms::page"title="Pages">

<resourceid="Magento_Cms::save"title="SavePage"/>

</resource>

</resource>

</resource>

</resource>

</resources>

</acl>

</config>

OurfocushereisontheMagento_Cms::saveresource.Magentomergesallofthese

individualacl.xmlfilesintoonebigACLtree.WecanseethistreeintwoplacesintheMagentoadminarea:

TheRoleResourcetaboftheSystem|Permissions|UserRoles|Edit|AddNewRolescreenTheAPItaboftheSystem|Extensions|Integrations|Edit|AddNewIntegrationscreen:

ThesearethetwoscreenswherewedefineaccesspermissionsforastandardadminuserandaspecialwebAPIintegratoruser.ThisisnottosaythatastandardadminusercannotexecutewebAPIcalls.ThedifferencewillbecomemoreobviouswhenwegettotheTypesofauthenticationsection.

Tothispoint,theseresourcesdon'treallydoanythingontheirown.Simplydefiningthemwithinacl.xmlwon'tmagicallymakeaCMSpageinthiscaseaccess-protected,oranythinglikethat.Thisiswherecontrollerscomeintothemix,asoneexampleofanaccess-controllingmechanism.AquicklookupagainstMagento_Cms::savestringusage,revealsaMagento\Cms\Controller\Adminhtml\Page\EditclassusingitaspartofitsconstADMIN_RESOURCE='Magento_Cms::save'definition.

TheADMIN_RESOURCEconstantisdefinedfurtherdowntheinheritancechain,onthe\Magento\Backend\App\AbstractActionasconstADMIN_RESOURCE='Magento_Backend::admin'.Thisisfurtherusedbythe_isAllowedmethodimplementationasfollows:

protectedfunction_isAllowed()

{

return$this->_authorization->isAllowed(static::ADMIN_RESOURCE);

}

TheAbstractActionclasshereisthebasisforprettymuchanyMagentoadmincontroller.Thismeansthatthecontrolleristheonethatutilizestheresourcedefinedinacl.xml,whereasdefinitionsinacl.xmlservethepurposeofbuildingtheACLtree,whichwecanmanagefromtheMagentoadmininterface.Thismeansthatanyonetryingtoaccessthecms/page/editURLinadminmusthaveaMagento_Cms::saveresourcepermissiontodoso.Otherwise,the_isAllowedmethod,readingtheADMIN_RESOURCEvalue,willreturnfalseandforbidaccesstothepage.

WebAPIs,ontheotherhand,don'tusecontrollers,sothereisnoaccesstotheADMIN_RESOURCEconstantandthe_isAllowedmethod.APIsusewebapi.xmltodefineroutes.Let'sfollowupwiththeCMSpagesaveanalogue,asperthe<MAGENTO_DIR>/module-cms/etc/webapi.xmlfile:

<routes>

<routeurl="/V1/cmsPage"method="POST">

<serviceclass="Magento\Cms\Api\PageRepositoryInterface"method="save"/>

<resources>

<resourceref="Magento_Cms::page"/>

</resources>

</route>

<routeurl="/V1/cmsPage/:id"method="PUT">

<serviceclass="Magento\Cms\Api\PageRepositoryInterface"method="save"/>

<resources>

<resourceref="Magento_Cms::page"/>

</resources>

</route>

</routes>

Theindividualroutedefinitionbindstogetherafewthings.TheurlandmethodargumentofarouteelementspecifywhatURLwilltriggerthisroute.Theclassandmethodargumentsofaserviceelementspecifywhichinterfaceandmethodonthatinterfacewillexecuteoncetherouteistriggered.Finally,therefargumentofaresourceelementspecifiesthesecuritychecktobeexecuted.IfauserexecutingawebAPIcallisunauthenticatedorauthenticatedwitharolethatdoesnothaveMagento_Cms::page,therequestwon'texecutetheservicemethodspecified.

Thecustomertypeofuseristhemostconvenientforworkingwithwidgets.The

Magentocheckoutisanexcellentexampleofthat.ThewholecheckoutisafullyAJAX-enabledapponitsown,separatefromtheusualMagentostorefront,suchasitsCMS,category,andproductpages.

TypesofauthenticationMagentosupportsthreedifferenttypesofauthenticationmethods:

Session-basedauthentication:BestsuitedforJavaScriptwidgetapplicationsrunningaspartoftheMagentostorefrontitself.Magentousesthelogged-instateofanadminuserorcustomertoverifytheiridentityandauthorizeaccesstotherequestedresource.Token-basedauthentication:Bestsuitedformobileorothertypesofapplicationsthatwishtoavoidthecomplexitiesoffull-blownOAuth-basedauthentication.Toobtainthetoken(withREST),oneinitiallyusesthePOST/V1/integration/customer/tokenorthePOST/V1/integration/admin/token.Asuccessfulresponsereturnsarandom32-character-longstring,forexample,8pcvbwrp97l5m1pvcdnis6e3930n4rsj.Thisisourtoken,usedforanysubsequentAPIcalls,viaaheadergivenasAuthorization:Bearer<token>.Thesimplicitybehindthisauthenticationmakesitanappealingchoicefordevelopers.OAuth-basedauthentication:Bestsuitedforthird-partyapplicationsthatintegratewithMagentoonbehalfoftheuser,withoutrevealingorstoringanyuserIDsorpasswords.ThestartingpointforsettingupOAuth-basedauthenticationisforaMagentoadminusertocreateintegration,undertheSystem|Extensions|Integration|AddNewIntegrationscreen.HerewecanprovideoptionssuchasCallbackURLandIdentitylinkURL,whichdefinetheexternalapplicationendpointthatreceivestheOAuthcredentials.Ifgiven,thevaluesoftheselinkspointtotheexternalappthatstandsastheOAuthclient.SuccessfullysavedintegrationgeneratesthekeyOAuthartefacts,suchasConsumerKey,ConsumerSecret,AccessToken,andAccessTokenSecret.

UsingOAuth-basedauthenticationexceedsthescopeofthisbook,whichiswhymovingforward,allofourexampleswillusesimplertoken-basedauthentication.

TypesofAPIsMagentosupportstwotypesofAPIs:

RepresentationalStateTransfer(REST):TheendpointsforAPIsdependonwebapi.xmlandtheindividualurlargumentsofeachrouteelement,aswewillsoonsee.Theauthenticationiscarriedoverinarequest'sheaderviaaBearertoken.SimpleObjectAccessProtocol(SOAP):TheWebServicesDescriptionLanguage(WSDL)isavailableviaaURLsuchashttp://magelicious.loc/soap/default?wsdl&services=catalogProductRepositoryV1.Whereasthedefaultstringisoptional,anditmatchesthecodenameoftheMagentostoreinthiscase,ifomitted,Magentowilldefaulttoadefaultstore,whateveritscodemightbe.Likewise,theservicesparameteracceptsoneormore(comma-separated)listsofservices.ThefulllistofavailableservicescanbeobtainedviaaURLsuchashttp://magelicious.loc/soap/default?wsdl_list.Withoutgoingintothedetailsofit,sufficeittosaythatMagentogeneratestheservicenamesautomaticallybasedonmoduleandinterfacenames.MuchlikewithRESTAPIs,theauthenticationiscarriedoverinarequest'sheaderviaaBearertoken.

Thegreatthingaboutthesetwoisthatwedon'tgettowritetwodifferentAPIsinMagento.TheapproachtowritingAPIsisunified,sotospeak.Wedefinesomeinterfaces,classes,andconfigurations,andMagentothengeneratestheAPIendpointsforbothRESTandSOAPonitsown.Thus,theRESTvs.SOAPchoicereallyonlybecomesaquestionwhenweconsumeAPIs,notwhilewewritethem.

UsingSOAPservicesexceedsthescopeofthisbook,whichiswhymovingforward,allofourexampleswilluseRESTAPIs.

UsingexistingwebAPIsTheCRUDandsearchmodelsofwebAPIsareimplementedthroughasetof*RepositoryInterfaceinterfaces,foundinthe<VendorName>/<ModuleName>/Api/<EntityName>RepositoryInterface.phpfiles.

Themajorityoftheserepositoryinterfacesdefineaspecificsetofcommonmethods:

save

get

getById

getList

delete

deleteById

Thedatatypethatflowsthroughthesemethodsfollowsacertainpattern,whereeachentitypassingthroughanAPIhasadatainterfacedefinedina<VendorName>/<ModuleName>/Api/Data/<EntityName>Interface.phpfile.

Let'stakeacloserlookat<MAGENTO_DIR>/module-cms/Api/BlockRepositoryInterface.php:

interfaceBlockRepositoryInterface

{

publicfunctionsave(

\Magento\Cms\Api\Data\BlockInterface$block

);

publicfunctiongetById($blockId);

publicfunctiongetList(

\Magento\Framework\Api\SearchCriteriaInterface$searchCriteria

);

publicfunctiondelete(

\Magento\Cms\Api\Data\BlockInterface$block

);

publicfunctiondeleteById($blockId);

}

Theconcreteimplementationsofrepositoryinterfacescanusuallybefoundinthe<VendorName>/<ModuleName>/Model/<EntityName>Repository.phporthe<VendorName>/<ModuleName>/Model/ResourceModel/<EntityName>Repository.phpfiles.Theexact

locationisnotthatrelevant,aswebapi.xmlshouldalwaysuseaninterfaceforaclassargumentforitsserviceelementdefinition.Themappingbetweentheinterfaceandconcreteimplementationthenhappensinthemodule'sdi.xmlfileviaapreferencedefinition.Fromanintegrator'spointofview,usingAPIsdoesnotrequireanyknowledgeofconcreteimplementations.

ThePHPDoc@returntagisarequirementforeverygettermethodonanAPIinterface,otherwise,Eachgettermusthaveadocblockerroristhrown.

TheSwaggerURL,http://magelicious.loc/swagger,willgenerateaSwaggerUIinterface,thatallowsustovisualizeandinteractwiththeAPI'sresources:

Bydefault,documentationreturnedhereislimitedtoanonymoususersonly.GeneratingavalidAPIkey,viathePOST/V1/integration/customer/tokenorPOST/V1/integration/admin/tokenwillunlockthedocumentationforalltheresourcesavailabletoagivenuser.WhileSwaggercertainlyhasitsplaceindevelopmentworkflows,oftentimesthePostmantoolisamorerobustsolutionforthoseworkingextensivelywithAPIs.

Let'sgoaheadandCRUDourwaythroughthecmsBlockinterface,usingRESTendpoints:

save(createanewblock)POST/V1/cmsBlocksave(updateanexistingblockbyid)PUT/V1/cmsBlock/:idgetById(getanexistingblockbyid)GET/V1/cmsBlock/:blockIddeleteById(deleteanexistingblock)DELETE/V1/cmsBlock/:blockIdgetList(getanarrayofexistingblocks)GET/V1/cmsBlock/search

Wewillbeusingtheintegratortypeofuser.ThiswillbeourMagentoadminuser,assignedeitherfullresources,oratleasttheResources|Content|Elements|BlocksresourceundertheRoleResourcetaboftheSystem|Permissions|UserRoles|Edit|AddNewRolescreen.

Westartwiththeadminloginrequest,inordertoobtainatokenforlaterrequests:

POST/index.php/rest/V1/integration/admin/tokenHTTP/1.1

Host:magelicious.loc

Content-Type:application/json

{

"username":"branko",

"password":"jrdJ%0i9a69n"

}

ThesuccessfulJSONresponseshouldcontainourAPItoken,whichwewillbeusingforanysubsequentAPIcalls.Thetokenitselfisstoredintheoauth_tokentable,underthetokencolumn.Wefurtherhaveconsumer_id,admin_id,andcustomer_idcolumnsinthattable.Thesegetfilleddependingontheusertypeweusedtologin.Bothconsumer_idandadmin_idareoftheintegratortype.Thesecolumnsgetfilledaccordinglydependingontheuserandauthenticationtypesused;asincustomerversusintegrator,andtoken-basedvsOAuth-basedvssession-basedauthentication.

Nowlet'screateanewblockviaPOST/V1/cmsBlock;thistriggersthesavemethod:

POST/rest/V1/cmsBlockHTTP/1.1

Host:magelicious.loc

Content-Type:application/json

Authorization:Bearer8pcvbwrp97l5m1pvcdnis6e3930n4rsj

{

"block":{

"identifier":"x-block",

"title":"TheXBlock",

"content":"<p>The<strong>XBlock</strong>Content...</p>",

"active":true

}

}

ThesuccessfulJSONresponseshouldreturnournewlycreatedblock:

{

"id":1,

"identifier":"x-block",

"title":"TheXBlock",

"content":"<p>The<strong>XBlock</strong>Content...</p>",

"active":true

}

Nowlet'supdatetheexistingcmsBlockviaPUT/V1/cmsBlock/:id;thistriggersthesavemethod:

PUT/rest/V1/cmsBlock/1HTTP/1.1

Host:magelicious.loc

Content-Type:application/json

Authorization:Bearer8pcvbwrp97l5m1pvcdnis6e3930n4rsj

{

"block":{

"identifier":"y-block",

"title":"TheYBlock",

"content":"<p>The<strong>YBlock</strong>Content...</p>",

"active":true

}

}

ThesuccessfulJSONresponseshouldreturntheupdatedblock:

{

"id":1,

"identifier":"y-block",

"title":"TheYBlock",

"content":"<p>The<strong>YBlock</strong>Content...</p>",

"active":true

}

Let'snowfetchoneoftheexistingblocksviaGET/V1/cmsBlock/:blockId;thistriggersthegetByIdmethod:

GET/rest/V1/cmsBlock/1HTTP/1.1

Host:magelicious.loc

Content-Type:application/json

Authorization:Bearer8pcvbwrp97l5m1pvcdnis6e3930n4rsj

ThesuccessfulJSONresponseisstructurallyidenticaltothatofthesavemethod.

Now,let'strydeletingoneoftheblocksviaDELETE/V1/cmsBlock/:blockId;thistriggersthedeleteByIdmethod:

DELETE/rest/V1/cmsBlock/2HTTP/1.1

Host:magelicious.loc

Content-Type:application/json

Authorization:Bearer8pcvbwrp97l5m1pvcdnis6e3930n4rsj

ThesuccessfulJSONresponsereturnsasingletrueorfalse.

Finally,let'stryfetchingthelistofblocksviaGET/V1/cmsBlock/search;thistriggersthegetListmethod:

GET/rest/V1/cmsBlock/search?searchCriteria[filter_groups][0][filters][0][field]=title&amp;searchCriteria[filter_groups][0][filters][0][value]=%Block%&amp;searchCriteria[filter_groups][0][filters][0][condition_type]=likeHTTP/1.1

Host:magelicious.loc

Content-Type:application/json

Authorization:Bearer8pcvbwrp97l5m1pvcdnis6e3930n4rsj

Sadly,theGETrequestdoesnotallowforthebody,so?searchCriteria...hastobepassedviaaURL.

ThesuccessfulJSONresponsereturnsanobjectcomprisedofitems,search_criteria,andtotal_counttop-levelkeys:

{

"items":[

{

"id":4,

"identifier":"x-block",

"title":"TheXBlock",

"content":"The<strong>XBlock</strong>Content...",

"creation_time":"2018-06-2307:30:06",

"update_time":"2018-06-2307:30:06",

"active":true

},

{

"id":5,

"identifier":"y-block",

"title":"TheYBlock",

"content":"The<strong>YBlock</strong>Content...",

"creation_time":"2018-06-2307:30:14",

"update_time":"2018-06-2307:30:14",

"active":true

}

],

"search_criteria":{...},

"total_count":2

}

Wewilladdressthesearch_criteriainmoredetaillateron.

CreatingcustomwebAPIsLet'sgoaheadandcreateaminiature,yetfull-blownMagentomoduleMagelicious_BoxythatdemonstratestheentireflowofcreatingacustomwebAPI.

Westartoffbydefiningamodule<MAGELICIOUS_DIR>/Boxy/registration.phpasfollows:

\Magento\Framework\Component\ComponentRegistrar::register(

\Magento\Framework\Component\ComponentRegistrar::MODULE,

'Magelicious_Boxy',

__DIR__

);

Wethendefinethe<MAGELICIOUS_DIR>/Boxy/etc/module.xmlasfollows:

<config>

<modulename="Magelicious_Boxy"setup_version="2.0.2"/>

</config>

Wethendefinethe<MAGELICIOUS_DIR>/Boxy/Setup/InstallSchema.phpthataddsthefollowingtable:

$table=$setup->getConnection()

->newTable($setup->getTable('magelicious_boxy_box'))

->addColumn(

'entity_id',

\Magento\Framework\DB\Ddl\Table::TYPE_INTEGER,

null,[

'identity'=>true,

'unsigned'=>true,

'nullable'=>false,

'primary'=>true

],'EntityID'

)

->addColumn(

'title',

\Magento\Framework\DB\Ddl\Table::TYPE_TEXT,

32,

['nullable'=>false],'Title'

)

->addColumn(

'content',

\Magento\Framework\DB\Ddl\Table::TYPE_TEXT,

null,

['nullable'=>false],'Content'

)

->setComment('MageliciousBoxyBoxTable');

$setup->getConnection()->createTable($table);

Wethendefine<MAGELICIOUS_DIR>/Boxy/Api/Data/BoxInterface.phpasfollows:

interfaceBoxInterface{

constBOX_ID='box_id';

constTITLE='title';

constCONTENT='content';

publicfunctiongetId();

publicfunctiongetTitle();

publicfunctiongetContent();

publicfunctionsetId($id);

publicfunctionsetTitle($title);

publicfunctionsetContent($content);

}

Wethendefine<MAGELICIOUS_DIR>/Boxy/Api/Data/BoxSearchResultsInterface.phpasfollows:

interfaceBoxSearchResultsInterfaceextends\Magento\Framework\Api\SearchResultsInterface

{

publicfunctiongetItems();

publicfunctionsetItems(array$items);

}

Wethenaddthe<MAGELICIOUS_DIR>/Boxy/Api/BoxRepositoryInterface.phpasfollows:

interfaceBoxRepositoryInterface

{

publicfunctionsave(\Magelicious\Boxy\Api\Data\BoxInterface$box);

publicfunctiongetById($boxId);

publicfunctiongetList(\Magento\Framework\Api\SearchCriteriaInterface$searchCriteria);

publicfunctiondelete(\Magelicious\Boxy\Api\Data\BoxInterface$box);

publicfunctiondeleteById($boxId);

}

Wethendefinethe<MAGELICIOUS_DIR>/Boxy/Model/Box.phpasfollows:

classBoxextends\Magento\Framework\Model\AbstractModelimplements\Magelicious\Boxy\Api\Data\BoxInterface

{

protectedfunction_construct(){

$this->_init(\Magelicious\Boxy\Model\ResourceModel\Box::class);

}

publicfunctiongetId(){

return$this->getData(self::BOX_ID);

}

publicfunctiongetTitle(){

return$this->getData(self::TITLE);

}

publicfunctiongetContent(){

return$this->getData(self::CONTENT);

}

publicfunctionsetId($id){

return$this->setData(self::BOX_ID,$id);

}

publicfunctionsetTitle($title){

return$this->setData(self::TITLE,$title);

}

publicfunctionsetContent($content){

return$this->setData(self::CONTENT,$content);

}

}

Wethendefinethe<MAGELICIOUS_DIR>/Boxy/Model/ResourceModel/Box.phpasfollows:

classBoxextends\Magento\Framework\Model\ResourceModel\Db\AbstractDb

{

protectedfunction_construct(){

$this->_init('magelicious_boxy_box','entity_id');

}

}

Wethendefinethe<MAGELICIOUS_DIR>/Boxy/Model/ResourceModel/Box/Collection.phpasfollows:

classCollection

{

protectedfunction_construct(){

$this->_init(

\Magelicious\Boxy\Model\Box::class,

\Magelicious\Boxy\Model\ResourceModel\Box::class

);

}

}

Wethendefinethe<MAGELICIOUS_DIR>/Boxy/Model/BoxRepository.phpasfollows:

classBoxRepositoryimplements\Magelicious\Boxy\Api\BoxRepositoryInterface

{

protected$boxFactory;

protected$boxResourceModel;

protected$searchResultsFactory;

protected$collectionProcessor;

publicfunction__construct(

\Magelicious\Boxy\Api\Data\BoxInterfaceFactory$boxFactory,

\Magelicious\Boxy\Model\ResourceModel\Box$boxResourceModel,

\Magelicious\Boxy\Api\Data\BoxSearchResultsInterfaceFactory$searchResultsFactory,

\Magento\Framework\Api\SearchCriteria\CollectionProcessorInterface$collectionProcessor

)

{

$this->boxFactory=$boxFactory;

$this->boxResourceModel=$boxResourceModel;

$this->searchResultsFactory=$searchResultsFactory;

$this->collectionProcessor=$collectionProcessor;

}

//Todo...

}

Let'sgoaheadandamendtheBoxRepositorywiththesavemethodasfollows:

publicfunctionsave(\Magelicious\Boxy\Api\Data\BoxInterface$box)

{

try{

$this->boxResourceModel->save($box);

}catch(\Exception$e){

thrownew\Magento\Framework\Exception\CouldNotSaveException(__($e->getMessage()));

}

return$box;

}

Let'sgoaheadandamendtheBoxRepositorywiththegetByIdmethodasfollows:

publicfunctiongetById($boxId){

$box=$this->boxFactory->create();

$this->boxResourceModel->load($box,$boxId);

if(!$box->getId()){

thrownew\Magento\Framework\Exception\NoSuchEntityException(__('Boxwithid"%1"doesnotexist.',$boxId));

}

return$box;

}

Let'sgoaheadandamendtheBoxRepositorywiththegetListmethodasfollows:

publicfunctiongetList(\Magento\Framework\Api\SearchCriteriaInterface$searchCriteria){

$collection=$this->boxCollectionFactory->create();

$this->collectionProcessor->process($searchCriteria,$collection);

$searchResults=$this->searchResultsFactory->create();

$searchResults->setSearchCriteria($searchCriteria);

$searchResults->setItems($collection->getItems());

$searchResults->setTotalCount($collection->getSize());

return$searchResults;

}

Let'sgoaheadandamendtheBoxRepositorywiththedeletemethodasfollows:

publicfunctiondelete(\Magelicious\Boxy\Api\Data\BoxInterface$box){

try{

$this->boxResourceModel->delete($box);

}catch(\Exception$e){

thrownew\Magento\Framework\Exception\CouldNotDeleteException(__($e->getMessage()));

}

returntrue;

}

Let'sgoaheadandamendtheBoxRepositorywiththedeleteByIdmethodasfollows:

publicfunctiondeleteById($boxId){

return$this->delete($this->getById($boxId));

}

Wethendefinethe<MAGELICIOUS_DIR>/Boxy/etc/di.xmlasfollows:

<config>

<preferencefor="Magelicious\Boxy\Api\Data\BoxInterface"type="Magelicious\Boxy\Model\Box"/>

<preferencefor="Magelicious\Boxy\Api\Data\BoxSearchResultsInterface"type="Magento\Framework\Api\SearchResults"/>

<preferencefor="Magelicious\Boxy\Api\BoxRepositoryInterface"type="Magelicious\Boxy\Model\BoxRepository"/>

</config>

Wethendefinethe<MAGELICIOUS_DIR>/Boxy/etc/acl.xmlasfollows:

<config>

<acl>

<resources>

<resourceid="Magento_Backend::admin">

<resourceid="Magento_Sales::sales">

<resourceid="Magento_Sales::sales_operation">

<resourceid="Magento_Sales::shipment">

<resourceid="Magelicious_Boxy::box"title="BoxyBox">

<resourceid="Magelicious_Boxy::box_get"title="Get"/>

<resourceid="Magelicious_Boxy::box_search"title="Search"/>

<resourceid="Magelicious_Boxy::box_save"title="Save"/>

<resourceid="Magelicious_Boxy::box_update"title="Update"/>

<resourceid="Magelicious_Boxy::box_delete"title="Delete"/>

</resource>

</resource>

</resource>

</resource>

</resource>

</resources>

</acl>

</config>

Wethendefinethe<MAGELICIOUS_DIR>/Boxy/etc/webapi.xmlasfollows:

<routes>

<routeurl="/V1/boxyBox/:boxId"method="GET">

<serviceclass="Magelicious\Boxy\Api\BoxRepositoryInterface"method="getById"/>

<resources>

<resourceref="Magelicious_Boxy::box_get"/>

</resources>

</route>

<routeurl="/V1/boxyBox/search"method="GET">

<serviceclass="Magelicious\Boxy\Api\BoxRepositoryInterface"method="getList"/>

<resources>

<resourceref="Magelicious_Boxy::box_search"/>

</resources>

</route>

<routeurl="/V1/boxyBox"method="POST">

<serviceclass="Magelicious\Boxy\Api\BoxRepositoryInterface"method="save"/>

<resources>

<resourceref="Magelicious_Boxy::box_save"/>

</resources>

</route>

<routeurl="/V1/boxyBox/:id"method="PUT">

<serviceclass="Magelicious\Boxy\Api\BoxRepositoryInterface"method="save"/>

<resources>

<resourceref="Magelicious_Boxy::box_update"/>

</resources>

</route>

<routeurl="/V1/boxyBox/:boxId"method="DELETE">

<serviceclass="Magelicious\Boxy\Api\BoxRepositoryInterface"method="deleteById"/>

<resources>

<resourceref="Magelicious_Boxy::box_delete"/>

</resources>

</route>

</routes>

Withallthesebitsinplace,ourAPIisnowready.Weshouldnowbeableto

CRUDourwaythroughBoxyBoxthesamewaywedidwiththeCMSblock.Whiletherecertainlyisagreatdealofboilerplatecodetogoaround,ourAPIisnowbothREST-andSOAP-ready.

UnderstandingsearchcriteriaThesearchCriteriaparameterofaGETrequestallowsforsearchresultsfiltering.Thekeytousingitcomesdowntounderstandingitsstructureandtheavailableconditiontypes.

Observingthe\Magento\Framework\Api\SearchCriteriaInterfaceinterface,andtheMagento\Framework\Api\SearchCriteriaclassasitsconcreteimplementation,wecaneasilyconcludethefollowingsearch_criteriastructure:

"search_criteria":{

"filter_groups":[],

"current_page":1,

"page_size":10,

"sort_orders":[]

}

Whereasthemandatoryfilter_groupsparameteranditsstructureareshownasfollows:

"filter_groups":[

{

"filters":[

{

"field":"fieldOrAttrName",

"value":"fieldOrAttrValue",

"condition_type":"eq"

},

{

//LogicalOR

}

]

},

{

//LogicalAND

}

],

Conditionsnestedundertheindividualfilterskey,correspondtotheLogicalORcondition.

Thelistofcondition_typevaluesincludes:

eq:Equalsfinset:Avaluewithinasetofvaluesfrom:Thebeginningofarange,mustbeusedwithatoconditiontype

gt:Greaterthangteq:Greaterthanorequalin:In,thevaluecancontainacomma-separatedlistofvalueslike:Like,thevaluecancontaintheSQLwildcardcharacterslt:Lessthanlteq:Lessthanorequaltomoreq:Moreorequaltoneq:Notequaltonin:Notin;thevaluecancontainacomma-separatedlistofindividualvaluesnotnull:Notnullnull:Null

Combiningtheseconditiontypeswillallowustofiltersearchresultsprettymuchanywaywewant.

Theoptionalsort_ordersparameteranditsstructureunfoldasfollows:

"sort_orders":[

{

"field":"fieldOrAttrName",

"direction":"ASC"

}

]

ThelistofdirectionvaluesincludesASCforascendingandDESCfordescendingsortorders.

ThesearchCriteriaisseeminglythemostcomplex,yetmostpowerfulaspectofasearchAPI.Understandinghowitworksisessentialforeffectivequerying.

SummaryInthischapter,wehavecoveredvaluablewebAPIelements.WelearnedhowtodifferentiatebetweentypesofwebAPIusers,andtheauthenticationandmethodsprovidedtodoso.WealsolearnedhoweasyitistocreateourownAPIswithjustafewlinesofXML.WesawhowtheroutedefinitionallowsforeasybindingbetweenwhatcomesviaanHTTPrequesttowhatexecutesincode,respectingtheaccesslistpermissionsintheprocess.ThevalueofbuildingAPIsaspartofourdistributablemodulesliesintheirextensibility.APIsforceustoembracetheinterfacewayofthinking,thusallowingotherstouseandextendourcodeeasilyandsecurely.Thepreferencemechanismweintroducedinpreviouschapters,throughdi.xmlfiles,allowsotherstochangethebehaviorbehindtheinterfaceeasily.

Movingforward,wearegoingtotakeamorethoroughandroundedlookatbuildinganddistributingourextensionsviaComposerandPackagist.

BuildingandDistributingExtensionsAttheverystartofourjourney,wementionedMagentosourcefilesbeingdistributedviathreedifferentchannels:asourcefilearchive,aGitrepository,andaComposerrepository.TheComposerapproachisthepreferredway.Whetherwearecodingamodule,library,themeorlanguagecomponent,usingtheComposerallowsforaneasyandautomateddependencymanagement,whichisnotpossibleotherwise.Magento'sbuilt-inComponentManagercanupdate,uninstall,enable,ordisableextensionsinstalledviaComposer.ThisimpliessourcesfromPackagist,MagentoMarketplace,orothercomposersources,aslongastheyhaveacomposer.jsonfile.

Movingforward,wearegoingtotakeacloserlookatthefollowingtopics:

BuildingashippingextensionDistributingviaGitHubDistributingviaPackagist

Thetermsmodule,extension,package,andcomponentareusedsomewhatinterchangeablyinMagento.Whiledeveloping,themodule.xmlimpliesmoduleterminology,andregistration.phpimpliescomponentterminology.However,distributingthemviaPackagistandMagentomarketplaceoftenimpliespackageandextensionterminologies.Magento-wise,toallintentsandpurposes,theyrefertothesamething.

TechnicalrequirementsYouwillneedtohavebasicknowledgeofPHP,OOP,JavaScript,andXML.YouwillalsoneedApache,MySQL,andAMPPSinstalledonyoursystemtoexecutethecodes.

ThecodefilesofthischaptercanbefoundonGitHub:https://github.com/PacktPublishing/Magento-2-Quick-Start-Guide.

CheckoutthefollowingvideotoseetheCodeinAction:

http://bit.ly/2xoS5ms.

BuildingashippingextensionOutofthebox,Magentoprovidesseveralshippingmethodsofitsown.Unlikepaymentmethods,whichtendtobelessdiverseamongdifferentwebshops,shippingmethodsareoftenanareaofcustomizationamongmerchants,whichiswhybuildingacustomizedshippingextensionisanessentialskillforeveryMagentodeveloper.

Therearetwotypesofshippingmethods:

online:Theseshippingmethodsbasetheirshippingcalculationontheshippingservicetheyconnectto.TheMagentoOpenSourceincludesfollowingmodulesthatprovideonlineshippingmethods:Magento_Ups,Magento_Usps,Magento_Fedex,Magento_Dhl.offline:Theseshippingmethodsdotheirownshippingcalculation,withoutconnectingtoanexternalservice.TheMagentoOpenSourceincludesabuilt-inMagento_OfflineShippingmodule,whichprovidesFlatRate,TableRate,Free,andStorePickupshippingmethods.

Let'sgoaheadandcreateaMagentoshippingextensionMagelicious_RoyalTrek.TheextensionassumesanimaginaryRoyalTrekcarrier,withtwoofflineshippingmethods:RoyalTrekStandardandRoyalTrek48h.

Wewillstartoffbydefining<MAGELICIOUS_DIR>/RoyalTrek/registration.phpasfollows:

\Magento\Framework\Component\ComponentRegistrar::register(

\Magento\Framework\Component\ComponentRegistrar::MODULE,

'Magelicious_RoyalTrek',

__DIR__

);

Wecanthendefinethe<MAGELICIOUS_DIR>/RoyalTrek/etc/module.xmlasfollows:

<config>

<modulename="Magelicious_RoyalTrek"setup_version="1.0.0"/>

</config>

Withthesetwofilesinplace,Magentoshouldalreadyseeourmodule,whenenabled.

Wecanthengoaheadanddefinethe<MAGELICIOUS_DIR>/RoyalTrek/composer.jsonasfollows:

{

"name":"magelicious/module-royal-trek",

"description":"TheRoyalTrekshipping",

"require":{

"php":"7.0.2|7.0.4|~7.0.6|~7.1.0"

},

"type":"magento2-module",

"version":"1.0.0",

"license":[

"OSL-3.0",

"AFL-3.0"

],

"autoload":{

"files":[

"registration.php"

],

"psr-4":{

"Magelicious\\RoyalTrek\\":""

}

}

}

Wecanthendefinethe<MAGELICIOUS_DIR>/RoyalTrek/etc/adminhtml/system.xmlasfollows:

<config>

<system>

<sectionid="carriers">

<groupid="royaltrek">

<label>RoyalTrekShipping</label>

<fieldid="active"type="select">

<label>Enabled</label>

<source_model>Magento\Config\Model\Config\Source\Yesno</source_model>

</field>

<fieldid="title"type="text">

<label>Title</label>

</field>

<fieldid="sallowspecific"type="select">

<label>ShiptoApplicableCountries</label>

<frontend_class>shipping-applicable-country</frontend_class>

<source_model>Magento\Shipping\Model\Config\Source\Allspecificcountries</source_model>

</field>

<fieldid="specificcountry"type="multiselect">

<label>ShiptoSpecificCountries</label>

<can_be_empty>1</can_be_empty>

<source_model>Magento\Directory\Model\Config\Source\Country</source_model>

</field>

<fieldid="showmethod"type="select"">

<label>ShowMethodifNotApplicable</label>

<source_model>Magento\Config\Model\Config\Source\Yesno</source_model>

</field>

<fieldid="specificerrmsg"type="textarea">

<label>DisplayedErrorMessage</label>

</field>

<fieldid="sort_order"type="text">

<label>SortOrder</label>

<validate>validate-numbervalidate-zero-or-greater</validate>

</field>

</group>

<!--todo...-->

</section>

</system>

</config>

Thissetsthegeneralconfigurationoptionsforourshippingmethods.Thesallowspecific,specificcountry,showmethod,specificerrmsgand,sort_orderarecommonconfigurationelementsofeachshippingmethod,asseenbyexaminingtheMagento\Shipping\Model\Carrier\AbstractCarrierclass.

Wecanthenextendthe<MAGELICIOUS_DIR>/RoyalTrek/etc/adminhtml/system.xmlwiththefollowinggroup:

<!--The"RoyalTrekStandard"specificoptions-->

<groupid="royaltrekstandard">

<label><![CDATA[The"RoyalTrekStandard"shippingmethod]]></label>

<fieldset_css>complex</fieldset_css>

<fieldid="title"type="text">

<label><![CDATA[Title]]></label>

</field>

<fieldid="shippingcost"type="text">

<label><![CDATA[ShippingCost]]></label>

<validate>validate-numbervalidate-zero-or-greater</validate>

</field>

</group>

Weareintroducinganadditionalsetofconfigurationoptionshere,tobeusedwithourRoyalTrekStandardmethod.

So,wethenextendthe<MAGELICIOUS_DIR>/RoyalTrek/etc/adminhtml/system.xmlwiththefollowinggroup:

<!--The"RoyalTrek48h"specificoptions-->

<groupid="royaltrek48hr">

<label><![CDATA[The"RoyalTrek48h"shippingmethod]]></label>

<fieldset_css>complex</fieldset_css>

<fieldid="title"type="text">

<label><![CDATA[Title]]></label>

</field>

<fieldid="shippingcost"type="text">

<label><![CDATA[ShippingCost]]></label>

<validate>validate-numbervalidate-zero-or-greater</validate>

</field>

</group>

Weareintroducinganadditionalsetofconfigurationoptionshere,tobeusedwithourRoyalTrek48hmethod.

Wethendefinethe<MAGELICIOUS_DIR>/RoyalTrek/etc/config.xmlasfollows:

<config>

<default>

<carriers>

<royaltrek>

<!--DEFAULTSHERE-->

</royaltrek>

</carriers>

</default>

</config>

Theconfig>default>carriers>royaltreknestingpathmatchesthenestingpathofthesystem.xmlelements.Wethenreplacethe<!--DEFAULTSHERE-->withfollowing:

<active>1</active>

<title>RoyalTrekShipping</title>

<sallowspecific>0</sallowspecific>

<showmethod>0</showmethod>

<specificerrmsg>TheRoyalTrekshippingisnotavailable.</specificerrmsg>

<sort_order>10</sort_order>

<model>Magelicious\RoyalTrek\Model\Carrier\RoyalTrek</model>

<royaltrekstandard>

<title><![CDATA[RoyalTrekStandard]]></title>

<shippingcost>4.99</shippingcost>

</royaltrekstandard>

<royaltrek48hr>

<title><![CDATA[RoyalTrek48h]]></title>

<shippingcost>9.99</shippingcost>

</royaltrek48hr>

Withthis,wecansetthedefaultvaluesforeachoftheconfigurationoptionsmadeavailableviasystem.xml.

Wethendefinethe<MAGELICIOUS_DIR>/Model/Carrier/RoyalTrek.phpasfollows:

<?php

namespaceMagelicious\RoyalTrek\Model\Carrier;

classRoyalTrekextends\Magento\Shipping\Model\Carrier\AbstractCarrierimplements

\Magento\Shipping\Model\Carrier\CarrierInterface{

constCARRIER_CODE='royaltrek';

constROYAL_TREK_STANDARD='royaltrekstandard';

constROYAL_TREK_48HR='royaltrek48hr';

protected$_code=self::CARRIER_CODE;

protected$_isFixed=true;

protected$_rateResultFactory;

protected$_rateMethodFactory;

publicfunction__construct(

\Magento\Framework\App\Config\ScopeConfigInterface$scopeConfig,

\Magento\Quote\Model\Quote\Address\RateResult\ErrorFactory$rateErrorFactory,

\Psr\Log\LoggerInterface$logger,

\Magento\Shipping\Model\Rate\ResultFactory$rateResultFactory,

\Magento\Quote\Model\Quote\Address\RateResult\MethodFactory$rateMethodFactory,

array$data=[]

){

$this->_rateResultFactory=$rateResultFactory;

$this->_rateMethodFactory=$rateMethodFactory;

parent::__construct($scopeConfig,$rateErrorFactory,$logger,$data);

}

publicfunctioncollectRates(\Magento\Quote\Model\Quote\Address\RateRequest$request){

if(!$this->getConfigFlag('active')){

returnfalse;

}

$result=$this->_rateResultFactory->create();

//Todo...

return$result;

}

publicfunctiongetAllowedMethods(){

return[

self::ROYAL_TREK_STANDARD=>$this->getConfigData(self::ROYAL_TREK_STANDARD.'/title'),

self::ROYAL_TREK_48HR=>$this->getConfigData(self::ROYAL_TREK_48HR.'/title'),

];

}

privatefunctiongetMethodTitle($method){

return$this->getConfigData($method.'/title');

}

privatefunctiongetMethodPrice($method){

return$this->getMethodCost($method);

}

privatefunctiongetMethodCost($method){

return$this->getConfigData($method.'/shippingcost');

}

}

ThebasicimplementationoftheMagelicious\RoyalTrek\Model\Carrier\RoyalTrekclassishighlydeterminedbytheimplementationofitsunderlyingMagento\Shipping\Model\Carrier\AbstractCarrierparentclassandMagento\Shipping\Model\Carrier\CarrierInterfaceinterface.Thebareminimumimpliessettingupthe$_codevalueandimplementingthecollectRatesmethod.The$_codevalueisanextremelyimportantbitofinformationhere.Weneedtomakesureitisuniqueamongalloftheenabledshippingextensions.ThecollectRatesmethodiswheretheactualshippingcalculationimplementationhappens.

Let'sgoaheadandextendthe<MAGELICIOUS_DIR>/Model/Carrier/RoyalTrek.phpwiththefollowing:

$method=$this->_rateMethodFactory->create();

$method->setCarrier($this->_code);

$method->setCarrierTitle($this->getConfigData('title'));

$method->setMethod(self::ROYAL_TREK_STANDARD);

$method->setMethodTitle($this->getMethodTitle($method->getMethod()));

$method->setPrice($this->getMethodPrice($method->getMethod()));

$method->setCost($this->getMethodCost($method->getMethod()));

$method->setErrorMessage(__('The%1methoderrormessagehere.'));

$result->append($method);

Usingthefactory,wecancreateaninstanceofMagento\Quote\Model\Quote\Address\RateResult\Method.Thisistheindividualshippingmethodthatwewishtomakeavailableasachoiceduringcheckout.Wethensettherequiredvaluesforthecarrier:method,price,cost,andpossibleerrormessage.Withourroyaltrekstandardmethodproperlyset,wefinallypassitontothe$resultobject.

Let'sfurtherextendthe<MAGELICIOUS_DIR>/Model/Carrier/RoyalTrek.phpwiththefollowing:

$method=$this->_rateMethodFactory->create();

$method->setCarrier($this->_code);

$method->setCarrierTitle($this->getConfigData('title'));

$method->setMethod(self::ROYAL_TREK_48HR);

$method->setMethodTitle($this->getMethodTitle($method->getMethod()));

$method->setPrice($this->getMethodPrice($method->getMethod()));

$method->setCost($this->getMethodCost($method->getMethod()));

$method->setErrorMessage(__('The%1methoderrormessagehere.'));

$result->append($method);

Muchlikewiththepreviousexample,hereweshouldaddourroyaltrek48hrtothe$resultobject.

TheendresultshouldbringforthourtwoRoyalTrekshippingmethodstothestorefrontcheckoutShippingstep,asfollows:

TheOrderSummarysectionoftheReview&PaymentsstepshouldalsoreflectonthemethodselectedintheShippingstep,asfollows:

Likewise,theadminCreateNewOrderscreensshouldalsoshowourRoyalTrekshippingmethodsasfollows:

Finally,thesuccessfullymadeordershouldreflecttheRoyalTrek48hshippingmethodselectioninitsneworderemail,andthecustomer'sMyAccountarea,asfollows:

Withourshippingmethodsconfirmedasworking,let'sgoaheadandlookforawayofdistributingit.

DistributingviaGitHubBydefault,thePackagistrepositoryistheonlyregisteredrepositoryinComposer.WecanaddmorerepositoriestoourMagentoprojectbydeclaringthemincomposer.json.Thiswaywegettoregisterourowngitrepositoryasasourceofpackages,asfollows:

composerconfigrepositories.magelicious-royal-trekgitgit@github.com:foggyline/Magelicious_RoyalTrek.git

Thiscommandresultsinthemodifiedcomposer.jsonfile,withtherepositorieskeyamendedasfollows:

"repositories":{

"0":{

"type":"composer",

"url":"https://repo.magento.com/"

},

"magelicious-royal-trek":{

"type":"git",

"url":"git@github.com:foggyline/Magelicious_RoyalTrek.git"

}

},

Wecanseeourmagelicious-royal-trekentryaddedinthere.ThegitvalueusedforthetypekeytellstheComposerweareusingthegitrepository,locatedattheURLprovidedviatheurlkey.Thecomposerandgitarenottheonlytwovaluessupportedforthetype.Theactualtypevaluecouldhaveeasilybeenanyothertypeofsupportedversioncontrolsystem:

Git(git-scm.com)Subversion(subversion.apache.org)Mercurial(mercurial-scm.org)Fossil(fossil-scm.org)

Wecouldalsohavesimplyusedthevcsvalueforthetypekey,andreliedonComposer'sVCSdrivertoautomaticallydetectthetypebasedurlvalue.

Ifwenowexecutecomposerrequiremagelicious/royal-trek:dev-master,Composerwillinstallourshippingmodule.Whilethisnewrepositoriesapproachworkswell,itissomewhatmoresuitedfordistributingprivateMagentoextensions.Wheneverwewishtodistributeourextensionpublicly,aPackagistisamoreconvenient

waytogo.

DistributingviaPackagistPackagistisafreeonlinerepositoryserviceforComposerpackages.WecanuseittoeasilydistributeourfreeMagentomodules.ThefactthatPackagistisadefaultComposerrepository,makesitthedefactorepositoryforanyComposeruser.ThisiswhyhavingourfreeMagentomodulesavailableviaPackagistisapreferredwayofdistribution.

PushingourMagentomoduletoPackagistisquiteeasy.Assumingwehaveouraccountcreated,weshouldstartbyclickingontheSubmitbutton,whichwilllandusonthefollowingscreen:

WeneedtoprovidealinktoourGitrepositoryhere,andclicktheCheckbutton,followedbytheSubmitbutton,ifthevalidrepositorywasfound.Thisshouldcreateourpackage,asperthefollowingscreen:

ThePackagistsaysthatourcreatedpackageisnowavailableforuseviathecomposerrequiremagelicious/module-royal-trekcommand.However,runningthiscommandnowwouldbelikelytogiveusthefollowingerror:

[InvalidArgumentException]

Couldnotfindamatchingversionofpackagemagelicious/module-royal-trek.Checkthepackagespelling,yourversionconstraintandthatthepackageisavailableinastabilitywhichmatchesyourminimum-stability(stable).

Noticethedev-masterlabelonourPackagistscreen.OurbranchesautomaticallyappearasdevversionsinPackagist.Therefore,wecanusethecomposerrequiremagelicious/module-royal-trek:dev-mastercommandtofetchthepackage.Tochangethat,weneedtospecificallytagourgitcommits,asfollows:

gitadd.

gitcommit-a-m'TheRoyalTrekshippingmodule,firstversion.'

gittag1.0.0

gitpushorigin1.0.0

Oncewehavedonethat,wecangobacktothePackagistpackagescreenandhittheUpdatebutton.Thisshouldnowshowour1.0.0version:

Ifwespecifyaversionwhenrequiringthepackage,Composerfetchesthelatesttaggedversionfromthemaster.Forexample,composerrequiremagelicious/module-royal-trek:2.4.xtakesthelatest2.4taggedversionfromthemasterbranch.

Whenitcomestoversioning,itisworthnotingthatsetup_versionfoundinmodule.xml,andversionfoundincomposer.jsonaretwodifferenttypesofversioning.Magentoreferstothemasmarketingversionandcomposerversion.Marketingversionmightbethoughtofassomethingthemerchantinteractswith,whileComposerversionissomethingthatdevelopersinteractwith.TheMagento_Catalogmodule,forexample,usesthe2.2.4marketingversionformarketing,whereasitsComposerversionis102.0.4.Thisisnottosaythatwecannotusethesameversioningforboth,aslongaswerememberthatthesetup_version,foundinmodule.xml,iswhatdrivesoursetupscripts.

DistributingfuturenewversionsofourMagelicious_RoyalTrekmodulewould,therefore,comedownto:

1. Bumpingupthesetup_versionfoundinmodule.xml2. Bumpinguptheversionfoundincomposer.json

3. AddressinganynecessaryMagentosetupscripts4. CommittingourchangestoGit,withproperversiontagging5. MakingsuretheUpdateistriggeredonthePackagistscreenofourmodule

editscreen

UsingthePackagist'sservicehookwecanensurethatourpackagewillalwaysbeupdatedautomatically.Seehttps://packagist.org/about#how-to-update-packagesformoreinformation.

SummaryInthischapter,welearnedhowtocreateasimpleshippingmodule.Wesawhoweasyitistoaddspecificshippingcalculationsaspartofofflineshippingmethods.WethenpackagedthismoduleanddistributeditviaPackagist.Thismadeiteasyfortheendconsumertouseourmodule,withjustafewsimpleconsolecommands.Likewise,anyfutureupdatestoourmoduleshouldbefrictionlessfortheendconsumer,ascomposercaneasilyhandlethoseviasimplecomposerupdatecommands.

Movingforward,wearegoingtotakealookatsomeofthespecificsofMagentoadminareadevelopment.

DevelopingforAdminAttheverybeginningofourjourney,backinChapter1,UnderstandingMagentoArchitecture,wementionedhowMagentoconsistsofdifferentareas.DevelopingforMagentoadminimpliesdevelopingfortheadminhtmlarea.Whilethemajorityofcodeisapplicableacrossdifferentareas,therearecertainsubtledifferences.UnlikefrontendwhichismostlybuiltviaHTML(.phtml,.html),theMagentoadminhtmlareaismostlybuiltviaUIcomponentswhicharereferenced,stacked,andconfiguredthrough.xmlfiles.Thisisnottosaythatthesamecomponentscannotbeusedbothforfrontendandadmin,becauseallUIcomponentscanbeconfiguredforbothoftheseareas;wejustneedtoconfigurestylesmanuallyforcomponentsonthefrontend.

TherearetwobasicUIcomponentsinMagento:listingandform.Therestaresecondarycomponents,whichserveasextensionsofbasiccomponents:listingToolbar,columns,filters,column,form,andfield.

Togetabetterunderstandingoftheadminhtmlarea,wearegoingtobuildaMagelicious_Minventorymodule,usingsomeofthesecomponents.Theideabehindthemoduleistoprovideacustomlistinginterfaceforalimitedsetofusers,wheretheycaneasilybumpuptheproductstockincertainincrementswithoutevergettingaccesstootherareasoftheMagentoadmin.

Ourworkherewillconsistoftwomajorparts:

UsingthelistingcomponentUsingtheformcomponent

Tokeepthingscompact,wewillusethe<MODULE_DIR>toreferencetheMAGELICIOUS_DIR>/Minventorydirectory.

TechnicalrequirementsYouwillneedtohavebasicknowledgeofPHP,OOP,JavaScript,andXML.YouwillalsoneedApache,MySQL,andAMPPSinstalledonyoursystemtoexecutethecodes.

ThecodefilesofthischaptercanbefoundonGitHub:https://github.com/PacktPublishing/Magento-2-Quick-Start-Guide.

CheckoutthefollowingvideotoseetheCodeinAction:

http://bit.ly/2xuoFDL.

UsingthelistingcomponentThelistingisabasiccomponentresponsibleforrenderinggrids,lists,andtiles,providingfiltering,pagination,sorting,andotherfeatures.ThelistingElementsgroupreferencedinthevendor/magento/module-ui/etc/ui_configuration.xsdfileprovidesanicelistofbothprimaryandsecondarylistingcomponents:

actions component file massaction select

actionsColumn container filters modal selectionsColumn

bookmark dataSource form multiline tab

boolean dataProvider hidden multiselect text

button date htmlContent nav textarea

checkbox dynamicRows input number wysiwyg

checkboxset email insertForm paging

column exportButton insertListing price

columns field listing range

columnsControls fieldset listingToolbar radioset

Thekeytousingallofthesecomponentsistounderstand:

Whatparametersindividualcomponentsaccept—furtherrevealedbydefinitionsfoundinthevendor/magento/moduleui/view/base/ui_component/etc/definitiondirectoryWhatchildcomponentsindividualcomponentsaccept—forexample,theemailcomponentcannotbenestedwithinthedataProvidercomponent

Movingforward,wewillusethelistingcomponent,andafewofitssecondarycomponentstocreatetheMicroInventoryscreenasshown:

ThegriditselfistoconsistofID,SKU,Status,Quantity,andActioncolumns.TheResupplyactionwilltriggerredirectiontoacustomStockResupplyscreen,whichwewilladdressinthenextsection.TheActionsselectorintheupperleftcorneristoconsistoftwocustomactions,allowingforfixedproductstockincreases.

Assumingwehavedefinedourbasicregistration.php,composer.json,andetc/module.xmlfiles,wecanstartdealingwiththespecificsofourmodule.

Let'sstartbydefiningthe<MODULE_DIR>/etc/acl.xmlasfollows:

<config>

<acl>

<resources>

<resourceid="Magento_Backend::admin">

<resourceid="Magento_Catalog::catalog">

<resourceid="Magento_Catalog::catalog_inventory">

<resourceid="Magelicious_Minventory::minventory"title="MicroInventory"/>

</resource>

</resource>

</resource>

</resources>

</acl>

</config>

Therequirementofourmodulewastoprovideacustomlistinginterfaceforalimitedsetofusers.Theaccesslistentry,laterreferencedbyouradmincontroller,ensuresjustthat.ThechoicetonestourMagelicious_Minventory::minventoryasachildofMagento_Catalog::catalog_inventoryisbasedmerelyonlogicalgrouping,asourmoduledealswithinventorystock.We

shouldnowbeabletoseeMicroInventoryunderRolesResourcesasshown:

Wethendefinethe<MODULE_DIR>/etc/adminhtml/routes.xmlasfollows:

<config>

<routerid="admin">

<routeid="minventory"frontName="minventory">

<modulename="Magelicious_Minventory"/>

</route>

</router>

</config>

Thiswillallowustoaccessourcontrolleractionslateronviahttp://magelicious.loc/index.php/<admin>/minventory/<controller>/<action>links.

Wethendefinethe<MODULE_DIR>/etc/adminhtml/menu.xmlasfollows:

<config>

<menu>

<addid="Magelicious_Minventory::minventory"

title="MicroInventory"translate="title"

module="Magelicious_Minventory"sortOrder="100"

parent="Magento_Catalog::inventory"

action="minventory/product/index"

resource="Magelicious_Minventory::minventory"/>

</menu>

</config>

ThispositionsourMicroInventorymenurightunderthemainCatalog|CATALOGUEmenu,asshown:

Whenclicked,themenu'sminventory/product/indexactionwillthrowusat<MODULE_DIR>/Controller/Adminhtml/Product/Index.php,whichwillbeaddressedlateron.

Wethendefinethe<MODULE_DIR>/Model/Resupply.phpasfollows:

namespaceMagelicious\Minventory\Model;

classResupply

{

protected$productRepository;

protected$collectionFactory;

protected$stockRegistry;

publicfunction__construct(

\Magento\Catalog\Api\ProductRepositoryInterface$productRepository,

\Magento\Catalog\Model\ResourceModel\Product\CollectionFactory$collectionFactory,

\Magento\CatalogInventory\Api\StockRegistryInterface$stockRegistry

)

{

$this->productRepository=$productRepository;

$this->collectionFactory=$collectionFactory;

$this->stockRegistry=$stockRegistry;

}

publicfunctionresupply($productId,$qty)

{

$product=$this->productRepository->getById($productId);

$stockItem=$this->stockRegistry->getStockItemBySku($product->getSku());

$stockItem->setQty($stockItem->getQty()+$qty);

$stockItem->setIsInStock((bool)$stockItem->getQty());

$this->stockRegistry->updateStockItemBySku($product->getSku(),$stockItem);

}}

Thisclasswillserveasacentralizedstockupdaterforourmodule,whichwillbeupdatingstockfromtheActionsselectorfoundontheMicroInventoryscreen,aswellasfromtheSavebuttonactiontriggeredontheStockResupplyscreen.

Wethendefinethe<MODULE_DIR>/Controller/Adminhtml/Product.phpasfollows:

namespaceMagelicious\Minventory\Controller\Adminhtml;

abstractclassProductextends\Magento\Backend\App\Action

{

constADMIN_RESOURCE='Magelicious_Minventory::minventory';

}

Thisisourcontrollerfile,theparentofthecontrolleractionsthatwewillsoondefine.WesetthevalueofitsADMIN_RESOURCEconstanttothatdefinedinouracl.xmlfile.Thiswillempowerourcontrollertoonlyallowaccesstouserswithproperresourceroles.

Wethendefinethe<MODULE_DIR>/Controller/Adminhtml/Product/Index.phpasfollows:

namespaceMagelicious\Minventory\Controller\Adminhtml\Product;

use\Magento\Framework\Controller\ResultFactory;

classIndexextends\Magelicious\Minventory\Controller\Adminhtml\Product

{

publicfunctionexecute()

{

$resultPage=$this->resultFactory->create(ResultFactory::TYPE_PAGE);

$resultPage->getConfig()->getTitle()->prepend((__('MicroInventory')));

return$resultPage;

}

}

Thiscontrolleractiondoesnotreallydoanythingspecial.Asidefromsettingupthescreentitle,itmerelyprovidesamechanismforloadingtheminventory_product_index.xmlthatwewilladdresslateron.

Wethendefinethe<MODULE_DIR>/Controller/Adminhtml/Product/MassResupply.phpasfollows:

namespaceMagelicious\Minventory\Controller\Adminhtml\Product;

use\Magento\Framework\Controller\ResultFactory;

classMassResupplyextends\Magelicious\Minventory\Controller\Adminhtml\Product

{

protected$filter;

protected$collectionFactory;

protected$resupply;

publicfunction__construct(

\Magento\Backend\App\Action\Context$context,

\Magento\Ui\Component\MassAction\Filter$filter,

\Magento\Catalog\Model\ResourceModel\Product\CollectionFactory$collectionFactory,

\Magelicious\Minventory\Model\Resupply$resupply

)

{

parent::__construct($context);

$this->filter=$filter;

$this->collectionFactory=$collectionFactory;

$this->resupply=$resupply;

}

publicfunctionexecute()

{

$redirectResult=$this->resultFactory->create(ResultFactory::TYPE_REDIRECT);

$qty=$this->getRequest()->getParam('qty');

$collection=$this->filter->getCollection($this->collectionFactory->create());

$productResupplied=0;

foreach($collection->getItems()as$product){

$this->resupply->resupply($product->getId(),$qty);

$productResupplied++;

}

$this->messageManager->addSuccessMessage(__('Atotalof%1record(s)havebeenresupplied.',$productResupplied));

return$redirectResult->setPath('minventory/product/index');

}

}

ThiscontrolleractionwillbetriggeredbytheResupply+10andResupply+50actionsfromtheMicroInventoryscreen.WecanseeitusingtheMagento\Ui\Component\MassAction\Filtertoprocessthemassselectoptions,bindingtheminternallytoproductcollectioninordertofilterproductswehaveselectedproperly.

Wethendefinethe<MODULE_DIR>/view/adminhtml/layout/minventory_product_index.xmlasfollows:

<page>

<updatehandle="styles"/>

<body>

<referenceContainername="content">

<uiComponentname="minventory_listing"/>

</referenceContainer>

</body>

</page>

Thisisthelayoutfilethatgetstriggeredwhenwelandon<MODULE_DIR>/Controller/Adminhtml/Product/Index.php.Thenameofthefilematchesthe<routeName>/<controllerName>/<controllerActionName>path.Theactuallayoutheremerelyreferencesthecontentcontainer,towhichitaddstheminventory_listingcomponentusingtheuiComponentelement.

Wethendefinethe<MODULE_DIR>/view/adminhtml/ui_component/minventory_listing.xmlasfollows:

<listing>

<argumentname="data"xsi:type="array">

<itemname="js_config"xsi:type="array">

<itemname="provider"xsi:type="string">minventory_listing.minventory_listing_data_source</item>

</item>

</argument>

<settings>

<spinner>minventory_columns</spinner>

<deps>

<dep>minventory_listing.minventory_listing_data_source</dep>

</deps>

</settings>

<!--dataSource-->

<!--listingToolbar-->

<!--columns-->

</listing>

Thisisourlistingcomponent.Theminventory_listing.minventory_listing_data_sourceisourdatasourcedefinedunderthedataSourceelement.

Wethenmodifytheminventory_listing.xmlbyreplacingthe<!--dataSource-->withthefollowing:

<dataSourcename="minventory_listing_data_source"component="Magento_Ui/js/grid/provider">

<settings>

<storageConfig>

<paramname="indexField"xsi:type="string">entity_id</param>

</storageConfig>

<updateUrlpath="mui/index/render"/>

</settings>

<dataProviderclass="Magelicious\Minventory\Ui\DataProvider\Product\ProductDataProvider"name="minventory_listing_data_source">

<settings>

<requestFieldName>id</requestFieldName>

<primaryFieldName>entity_id</primaryFieldName>

</settings>

</dataProvider>

</dataSource>

ThemostimportantpartofthedataSourcecomponentisitsdataProvider.WesetitsvaluetoMagelicious\Minventory\Ui\DataProvider\Product\ProductDataProvider.TherequestFieldNameandprimaryFieldNamearenotreallythatimportantinourcase,aswearenotreallyoperatingwithfullCRUDontheproductentity,sincewearemerelyfocusingonupdatingthequantitythroughafewlinesofcustomcode.Still,thecomponentitselfrequiresacertainminimalconfiguration,soweusewhatwewouldnormallyuseforaproductentity,butthesecanreallybeanyvaluesfoundonanentity.

Wethendefinethe<MODULE_DIR>/Ui/DataProvider/Product/ProductDataProvider.phpasfollows:

classProductDataProviderextends\Magento\Ui\DataProvider\AbstractDataProvider{

protected$collection;

publicfunction__construct(

string$name,

string$primaryFieldName,

string$requestFieldName,

\Magento\Catalog\Model\ResourceModel\Product\CollectionFactory$collectionFactory,

array$meta=[],

array$data=[]

){

parent::__construct(

$name,

$primaryFieldName,

$requestFieldName,

$meta,

$data

);

$this->collection=$collectionFactory->create();

}

publicfunctiongetData(){

if(!$this->getCollection()->isLoaded()){

$this->getCollection()->load();

}

$items=$this->getCollection()->toArray();

return[

'totalRecords'=>$this->getCollection()->getSize(),

'items'=>array_values($items),

];

}

}

ThecollectionpropertyissetmandatorilybytheparentMagento\Ui\DataProvider\AbstractDataProvider,sowehavetosetitsvaluetosomekindofcollection.Sinceweareworkingwithproducts,itonlymakessensetosetittoanexistingMagento\Catalog\Model\ResourceModel\Product\Collection,thusavoidingcreatingourowncollection.ThekeymethodforourlistingcomponentisgetData.Thismethodfeedsthelistingcomponentwiththenumberofrecordsinthedatacollection,aswellasthedatacollectionitself.

WethenextendtheProductDataProvider.phpwiththefollowing:

protectedfunctionjoinQty(){

if($this->getCollection()){

$this->getCollection()->joinField(

'qty',

'cataloginventory_stock_item',

'qty',

'product_id=entity_id'

);

}

}

Theqtyfieldisnotpartofthedefaultproductscollection,sowehavetojointheqtyinformationfromthecataloginventory_stock_itemtabletoit.Wemustmakesuretocallthismethodbeforeourcollectionisloaded.

Wethenmodifytheminventory_listing.xmlbyreplacingthe<!--listingToolbar-->

withthefollowing:

<listingToolbarname="listing_top">

<bookmarkname="bookmarks"/>

<columnsControlsname="columns_controls"/>

<filtersname="listing_filters"/>

<pagingname="listing_paging"/>

<--massaction-->

</listingToolbar>

ThelistingToolbarcomponentisessentiallyacontainerforthelisting-relatedelementslikepaging,massactions,filters,andbookmarks.Thebookmarkcomponentstorestheactiveandchangedstatesofdatagrids.Thepagingcomponentprovidesnavigationthroughthepagesofthecollection,otherwise,wewouldbeforcedtoviewtheentirecollectionatonce,whichwouldnotreallybeaperformance-efficientapproach.Thefilterscomponentisresponsibleforrenderingfilters'interfacesandapplyingtheactualfiltering.Thisincludesthestatesoffilters,columns'positions,appliedsorting,pagination,andsoon.

ThecolumnsControlscomponentallowsustomodifythevisibilityofthelistingcolumns,shownasfollows:

ThepossibilityoffilteringbyStoreView,asshownintheprecedingscreenshot,iseasilyaddedbymodifyingtheminventory_listing.xmlasfollows:

<filtersname="listing_filters">

<filterSelectname="store_id"provider="${$.parentName}">

<settings>

<optionsclass="Magento\Store\Ui\Component\Listing\Column\Store\Options"/>

<captiontranslate="true">AllStoreViews</caption>

<labeltranslate="true">StoreView</label>

<dataScope>store_id</dataScope>

</settings>

</filterSelect>

</filters>

HereweusedthefilterSelectcomponent,withtheMagento\Store\Ui\Component\Listing\Column\Store\Optionsclasspassedasanoptionsparameter.ThisshowshoweasyitistocombinevariouscomponentsandtopulldatafromPHPclasses.

Let'smodifytheminventory_listing.xmlfurtherbyreplacingthe<--massaction-->withthefollowing:

<massactionname="listing_massaction"component="Magento_Ui/js/grid/tree-massactions">

<actionname="resupply">

<settings>

<type>resupply</type>

<labeltranslate="true">Resupply</label>

<actions>

<actionname="0">

<type>resupply_10</type>

<labeltranslate="true">Resupply+10</label>

<urlpath="minventory/product/massResupply">

<paramname="qty">10</param>

</url>

</action>

<actionname="1">

<type>resupply_50</type>

<labeltranslate="true">Resupply+50</label>

<urlpath="minventory/product/massResupply">

<paramname="qty">50</param>

</url>

</action>

</actions>

</settings>

</action>

</massaction>

Usingtheactioncomponent,wedefinetheResupply+10andResupply+50actionsusedinthescopeofthemassactioncomponent.

Wethenmodifytheminventory_listing.xmlbyreplacingthe<!--columns-->withthefollowing:

<columnsname="minventory_columns"class="Magento\Catalog\Ui\Component\Listing\Columns">

<settings>

<childDefaults>

<paramname="fieldAction"xsi:type="array">

<itemname="provider"xsi:type="string">minventory_listing.minventory_listing.minventory_columns.actions</item>

<itemname="target"xsi:type="string">applyAction</item>

<itemname="params"xsi:type="array">

<itemname="0"xsi:type="string">resupply</item>

<itemname="1"xsi:type="string">${$.$data.rowIndex}</item>

</item>

</param>

</childDefaults>

</settings>

<!--columns#2-->

</columns>

Thecolumnscomponentdefinition,alongwithitschildcomponents,islikelytotakethebiggestchunkofourlistingconfiguration.Thisiswhereweaddourselectioncolumns,regularcolumns,andactioncolumns.

Todemonstratethatfurther,wereplacethe<!--columns#2-->withthefollowing:

<selectionsColumnname="ids"sortOrder="0">

<settings>

<indexField>entity_id</indexField>

</settings>

</selectionsColumn>

<columnname="entity_id"sortOrder="10">

<settings>

<filter>textRange</filter>

<labeltranslate="true">ID</label>

<sorting>asc</sorting>

</settings>

</column>

<columnname="sku"sortOrder="20">

<settings>

<filter>text</filter>

<labeltranslate="true">SKU</label>

</settings>

</column>

<columnname="qty"sortOrder="30">

<settings>

<addField>true</addField>

<filter>textRange</filter>

<labeltranslate="true">Quantity</label>

</settings>

</column>

<actionsColumnname="resupply"class="Magelicious\Minventory\Ui\Component\Listing\Columns\Resupply"sortOrder="40">

<settings>

<indexField>entity_id</indexField>

</settings>

</actionsColumn>

TheactionsColumnpointstoacustomMagelicious\Minventory\Ui\Component\Listing\Columns\Resupplyclass,whichwedefineunder<MODULE_DIR>/Ui/Component/Listing/Columns/Resupply.phpasfollows:

classResupplyextends\Magento\Ui\Component\Listing\Columns\Column{

protected$urlBuilder;

publicfunction__construct(

\Magento\Framework\View\Element\UiComponent\ContextInterface$context,

\Magento\Framework\View\Element\UiComponentFactory$uiComponentFactory,

\Magento\Framework\UrlInterface$urlBuilder,

array$components=[],

array$data=[]

){

$this->urlBuilder=$urlBuilder;

parent::__construct($context,$uiComponentFactory,$components,$data);

}

publicfunctionprepareDataSource(array$dataSource){

if(isset($dataSource['data']['items'])){

$storeId=$this->context->getFilterParam('store_id');

foreach($dataSource['data']['items']as&$item){

$item[$this->getData('name')]['resupply']=[

'href'=>$this->urlBuilder->getUrl(

'minventory/product/resupply',

['id'=>$item['entity_id'],'store'=>$storeId]

),

'label'=>__('Resupply'),

'hidden'=>false,

];

}

}

return$dataSource;

}

}

TheprepareDataSourcemethodiswhereweinjectourmodifications.Wetraversethe$dataSource['data']['items']structureuntilwecomeacrossourcolumn,andthenmodifyitaccordinglywithaproperhrefvalue.This,inturn,rendersourresupplyactionscolumnaspertheMicroInventoryscreen.

WiththeMicroInventoryscreennowsortedviathelistingcomponent,let'sshiftourfocusontotheStockResupplyscreenbuiltviatheformcomponent.

UsingtheformcomponentTheformisabasiccomponentresponsibleforperformingCRUDoperationsonanentity.ThelistingElementsgroupreferencedundervendor/magento/module-ui/etc/ui_configuration.xsdfileprovidesanicelistofbothprimaryandsecondaryformcomponents:

bookmark dataProvider fileUploader massaction range

boolean date form modal radioset

button dynamicRows hidden multiline select

checkbox email htmlContent multiselect tab

checkboxset exportButton input nav text

component field insertForm number textarea

container fieldset insertListing paging wysiwyg

dataSource file listing price

Movingforward,wewillusetheformcomponent,andafewofitssecondarycomponentstocreatetheStockResupplyscreenasshown:

TheformitselfistoconsistofStockand+Qtyfields.TheStockfieldwillbearead-onlyfieldconsistingofanSKU+currentqtystring.TheBackbuttonwilltakeusbacktotheMicroInventorylisting,whereastheSavebuttonwillposttheformtoaspecialResupplycontrolleraction,whichwillthenincreasethestockbyagiven+Qtyamount.TheActionsselectorintheupperleftcorneristoconsistoftwocustomactions,allowingforfixedproductstockincreases.

Westartoffbydefiningthe<MODULE_DIR>/Controller/Adminhtml/Product/Resupply.phpasfollows:

use\Magento\Framework\Controller\ResultFactory;

classResupplyextends\Magelicious\Minventory\Controller\Adminhtml\Product{

protected$stockRegistry;

protected$productRepository;

protected$resupply;

publicfunction__construct(

\Magento\Backend\App\Action\Context$context,

\Magento\Catalog\Api\ProductRepositoryInterface$productRepository,

\Magento\CatalogInventory\Api\StockRegistryInterface$stockRegistry,

\Magelicious\Minventory\Model\Resupply$resupply

){

parent::__construct($context);

$this->productRepository=$productRepository;

$this->stockRegistry=$stockRegistry;

$this->resupply=$resupply;

}

publicfunctionexecute(){

if($this->getRequest()->isPost()){

$this->resupply->resupply(

$this->getRequest()->getParam('id'),

$_POST['minventory_product']['qty']

);

$this->messageManager->addSuccessMessage(__('Successfullyresupplied'));

$redirectResult=$this->resultFactory->create(ResultFactory::TYPE_REDIRECT);

return$redirectResult->setPath('minventory/product/index');

}else{

$resultPage=$this->resultFactory->create(ResultFactory::TYPE_PAGE);

$resultPage->getConfig()->getTitle()->prepend((__('StockResupply')));

return$resultPage;

}

}

}

Giventhesimplicityofourform,usingtheisPost()checkontherequestobject,weallowourselvestousethesamecontrolleractionforrenderingtheStockResupplyscreen,aswellassubmittingthesaveactiontoit.

Withcontrolleractioninplace,wethendefinethe<MODULE_DIR>/view/adminhtml/layout/minventory_product_resupply.xmlasfollows:

<page>

<updatehandle="styles"/>

<body>

<referenceContainername="content">

<uiComponentname="minventory_resupply_form"/>

</referenceContainer>

</body>

</page>

Muchlikewiththeformlisting,thislayoutfilemerelycallstheminventory_resupply_formcomponent,whichiswhereallourvisualelementsoftheStockResupplyscreenreside.

Wethendefinethe<MODULE_DIR>/view/adminhtml/ui_component/minventory_resupply_form.xmlasfollows:

<form>

<argumentname="data"xsi:type="array">

<itemname="js_config"xsi:type="array">

<itemname="provider"xsi:type="string">minventory_resupply_form.minventory_resupply_form_data_source</item>

<itemname="deps"xsi:type="string">minventory_resupply_form.minventory_resupply_form_data_source</item>

</item>

<itemname="layout"xsi:type="array">

<itemname="type"xsi:type="string">tabs</item>

</item>

</argument>

<settings>

<buttons>

<buttonname="save"class="Magelicious\Minventory\Block\Adminhtml\Product\Edit\Button\Save"/>

<buttonname="back"class="Magelicious\Minventory\Block\Adminhtml\Product\Edit\Button\Back"/>

</buttons>

</settings>

<!--dataSource-->

<!--fieldset-->

</form>

Muchlikethelistingcomponent,theformcomponentalsorequiresadataprovider.

Wethenmodifytheminventory_resupply_form.xmlbyreplacingthe<!--dataSource-->withfollowing:

<dataSourcename="minventory_resupply_form_data_source">

<argumentname="data"xsi:type="array">

<itemname="js_config"xsi:type="array">

<itemname="component"xsi:type="string">Magento_Ui/js/form/provider</item>

</item>

</argument>

<dataProviderclass="Magelicious\Minventory\Ui\DataProvider\Product\Form\ProductDataProvider"name="minventory_resupply_form_data_source">

<settings>

<requestFieldName>id</requestFieldName>

<primaryFieldName>entity_id</primaryFieldName>

</settings>

</dataProvider>

</dataSource>

Herewesetthedataprovider,whichpointstoourcustomclass,Magelicious\Minventory\Ui\DataProvider\Product\Form\ProductDataProvider.

Wefurthermodifytheminventory_resupply_form.xmlbyreplacingthe<!--fieldset-->withthefollowing:

<fieldsetname="minventory_product">

<argumentname="data"xsi:type="array">

<itemname="config"xsi:type="array">

<itemname="label"xsi:type="string"translate="true">General</item>

</item>

</argument>

<fieldname="stock">

<argumentname="data"xsi:type="array">

<itemname="config"xsi:type="array">

<itemname="label"xsi:type="string">Stock</item>

<itemname="visible"xsi:type="boolean">true</item>

<itemname="dataType"xsi:type="string">text</item>

<itemname="formElement"xsi:type="string">input</item>

<itemname="disabled"xsi:type="string">true</item>

</item>

</argument>

</field>

<fieldname="qty">

<argumentname="data"xsi:type="array">

<itemname="config"xsi:type="array">

<itemname="label"xsi:type="string">+Qty</item>

<itemname="visible"xsi:type="boolean">true</item>

<itemname="dataType"xsi:type="string">text</item>

<itemname="formElement"xsi:type="string">input</item>

<itemname="focused"xsi:type="string">true</item>

<itemname="validation"xsi:type="array">

<itemname="required-entry"xsi:type="boolean">true</item>

<itemname="validate-zero-or-greater"xsi:type="boolean">true</item>

</item>

</item>

</argument>

</field>

</fieldset>

HerewedefinedfieldsetwithaGeneraltitle,andtwofields:stockandqty.Thestockfieldwasdefinedasdisabled,asitspurposewillbemerelytomergethe<SKU>|<qty>valuesforinformationalpurposes.Thestructureoftheindividualfielddefinitionmightseemoverwhelmingatfirst,butwecaneasilydetermineavailableargumentsbyobservingthe<componentname="column"definitionunderthe<MAGENTO_DIR>/module-ui/view/base/ui_component/etc/definition.map.xml.

Wethendefine<MODULE_DIR>/Ui/DataProvider/Product/Form/ProductDataProvider.phpasfollows:

classProductDataProviderextends\Magento\Ui\DataProvider\AbstractDataProvider{

protected$loadedData;

protected$productRepository;

protected$stockRegistry;

protected$request;

publicfunction__construct(

string$name,

string$primaryFieldName,

string$requestFieldName,

\Magento\Catalog\Model\ResourceModel\Product\CollectionFactory$collectionFactory,

\Magento\Catalog\Api\ProductRepositoryInterface$productRepository,

\Magento\CatalogInventory\Api\StockRegistryInterface$stockRegistry,

\Magento\Framework\App\RequestInterface$request,

array$meta=[],array$data=[]

){

parent::__construct($name,$primaryFieldName,$requestFieldName,$meta,$data);

$this->collection=$collectionFactory->create();

$this->productRepository=$productRepository;

$this->stockRegistry=$stockRegistry;

$this->request=$request;

}

publicfunctiongetData(){

if(isset($this->loadedData)){

return$this->loadedData;

}

$id=$this->request->getParam('id');

$product=$this->productRepository->getById($id);

$stockItem=$this->stockRegistry->getStockItemBySku($product->getSku());

$this->loadedData[$product->getId()]['minventory_product']=[

'stock'=>__('%1|%2',$product->getSku(),$stockItem->getQty()),

'qty'=>10

];

return$this->loadedData;

}

}

OurdataproviderisexpectedtoimplementthegetDatamethod.Thisreturnsanarrayofdatathatfeedstheformwithpropervalues.Thestructureofthearraymightbedifficulttograspatfirst,soithelpstoglossoversomeofMagento'sdataproviders.Thestockandqtyentriesherewillprovidevaluesforthefieldsdefinedviaminventory_resupply_form.xml.

Wethendefine<MODULE_DIR>/Block/Adminhtml/Product/Edit/Button/Back.phpasfollows:

classBackextends\Magento\Backend\Block\Templateimplements\Magento\Framework\View\Element\UiComponent\Control\ButtonProviderInterface

{

publicfunctiongetButtonData(){

return[

'label'=>__('Back'),

'on_click'=>sprintf("location.href='%s';",$this->getBackUrl()),

'class'=>'back',

'sort_order'=>10

];

}

publicfunctiongetBackUrl(){

return$this->getUrl('*/*/');

}

}

TheButtonProviderInterfacerequiresthegetButtonDatamethodimplementation.ThestructureofthereturnarrayissomewhatblurryuntilweglossoversomeoftheotherbuttonsthataredefinedacrossMagento.ThisrendersourBackbuttonasfollows:

<buttonid="back"title="Back"type="button"class="action-scalableback"onclick="location.href='...strippedaway...';"data-ui-id="back-button">

<span>Back</span>

</button>

TheBackbuttonprovidesagobacktopreviouspagefunctionality,whichinourcaseisdeterminedbythevalueofthegetBackUrlmethodresponse.

Wethendefine<MODULE_DIR>/Block/Adminhtml/Product/Edit/Button/Save.phpasfollows:

classSaveextends\Magento\Backend\Block\Templateimplements\Magento\Framework\View\Element\UiComponent\Control\ButtonProviderInterface

{

publicfunctiongetButtonData(){

return[

'label'=>__('Save'),

'class'=>'saveprimary',

'data_attribute'=>[

'mage-init'=>['button'=>['event'=>'save']],

'form-role'=>'save',

],

'sort_order'=>20,

];

}

}

Muchlikewiththepreviousbutton,weuseasimilararraystructureforourbuttonhere.Thedifferenceisthatthistimewearepassingthedata_attributeaswell.ThisrendersourSavebuttonasfollows:

<buttonid="save"title="Save"type="button"class="action-scalablesaveprimaryui-buttonui-widgetui-state-defaultui-corner-allui-button-text-only"onclick="location.href='...strippedaway...';"data-form-role="save"data-ui-id="save-button"role="button"aria-disabled="false"><spanclass="ui-button-text">

<span>Save</span>

</span></button>

Themage-initpartmightseemconfusingatthemoment.Sufficeittosaythatit'sawayofinitializingaJScomponent,whichissomethingwewilladdressinmoredetailinthenextchapter.OurSaveessentiallytriggerstheform'ssubmission.

Withthiswehavefinishedourformcomponentdefinition,makingthewholeStockResupplyscreenfunctional.

SummaryInthischapter,webuilttwoverydifferentscreensintheMagentoadminarea.Oneutilizedthelistingcomponent,whereastheotherutilizedtheformcomponent.Agreatdealofourworkinvolvedconfigurationratherthancoding,whichstandstoprovehowpowerfulMagentoUIcomponentscanbe.Whiletheamountofconfigurationmightseemoverwhelmingatfirst,gettingagriponindividualcomponentconfigurationsallowsustobuildcomplexinterfacesquickly.

Movingforward,wearegoingtotakealookatsomeofthespecificsbehinddevelopingforthestorefrontarea.

DevelopingforStorefrontTheMagentostorefrontisthecustomer-facingviewofaMagentoe-commerceplatform.Developingforstorefrontimpliesdevelopingforthefrontendarea.WhereastheadminhtmlareaisprimarilybuiltviameansofUIcomponents,thefrontendareamakesheavyuseofJavaScript(JS)componentsthatcomeinformofjQuerywidgetsandUI/KnockoutJScomponents.AsidefromJScomponents,therearelotsofotherbitsandpiecesinvolvedinstorefrontdevelopment,suchasthemes,layouts,templates,languagepackages,andCSS/LESS.Ourfocus,however,throughoutthischapterwillbeonJScomponents,astheyseemtobethemostconfusingandchallengingpartoftheMagentofrontendtoovercome.

Movingforward,wearegoingtolookintothefollowingsections:

SettinguptheplaygroundInitializingJScomponentsMeetRequireJSReplacingjQuerywidgetcomponentsExtendingjQuerywidgetscomponentsCreatingjQuerywidgetscomponentsExtendingUI/KnockoutJScomponentsCreatingUI/KnockoutJScomponents

TechnicalrequirementsYouwillneedtohavebasicknowledgeofPHP,OOP,JavaScript,andXML.YouwillalsoneedApache,MySQL,andAMPPSinstalledonyoursystemtoexecutethecodes.

ThecodefilesofthischaptercanbefoundonGitHub:https://github.com/PacktPublishing/Magento-2-Quick-Start-Guide.

CheckoutthefollowingvideotoseetheCodeinAction:

http://bit.ly/2D6oMLz.

SettinguptheplaygroundTogetabetterunderstandingofthefrontendarea,wearegoingtobuildaverylightweightMagelicious_Jscomodule,toserveasaplaygroundforourJScomponentexploration.

Tothispoint,weshouldalreadybeprettyfamiliarwiththeflowofcreatinganewmodule.Assumingwehavedefinedourbasicregistration.php,composer.json,andetc/module.xmlfiles,wecanstartdealingwiththespecificsofourMagelicious_Jscomodule.

Let'sstartbydefining<MODULE_DIR>/etc/frontend/routes.xml,asfollows:

<config>

<routerid="standard">

<routeid="jsco"frontName="jsco">

<modulename="Magelicious_Jsco"/>

</route>

</router>

</config>

Wethencreate<MODULE_DIR>/Controller/Playground.php,asfollows:

namespaceMagelicious\Jsco\Controller;

abstractclassPlaygroundextends\Magento\Framework\App\Action\Action

{

}

Wethencreate<MODULE_DIR>/Controller/Playground/Index.php,asfollows:

namespaceMagelicious\Jsco\Controller\Playground;

useMagento\Framework\Controller\ResultFactory;

classIndexextends\Magelicious\Jsco\Controller\Playground

{

publicfunctionexecute(){

$resultPage=$this->resultFactory->create(ResultFactory::TYPE_PAGE);

$resultPage->getConfig()->getTitle()->set(__('Playground'));

return$resultPage;

}

}

There'snothingreallynewtothispoint.Wehavemerelycreatedaroute,controller,andcontrolleractiontosupportapagethatwecanaccessviatheURL,suchashttp://magelicious.loc/jsco/playground.ButthepageitselfisdefinedviaXMLlayout,andwefurthercreate

<MODULE_DIR>/view/frontend/layout/jsco_playground_index.xml,asfollows:

<pagexmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"layout="empty"

xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">

<body>

<referenceContainername="content">

<blockclass="Magelicious\Jsco\Block\Test"

name="jsco_test"

template="Magelicious_Jsco::playground.phtml">

</block>

</referenceContainer>

</body>

</page>

Notelayout="empty"he

re;thisistolimitourselvestoanearlyemptypagetoworkwith.

Finally,wecreateanempty<MODULE_DIR>view/frontend/templates/playground.phtmlpage.Ifweweretonowopenalink,suchashttp://magelicious.loc/jsco/playground,thatwouldopenapagewiththePlaygroundtitleshown.playground.phtmliswhereallofoursamplecodewillgoin,aswecontinueexploringthischapter.

CallingandinitializingJScomponentsCallingandinitializingJScomponentsmightseemabitchallengingatfirst.TherearetwotypesofsyntaxnotationsusedwithMagentoJScomponents:

Declarative:Usingthedata-mage-initattributeUsingthe<scripttype="text/x-magento-init"/>tag

Imperative:Usingthe<script>tag,withoutthetype="text/x-magento-init"attribute

Tobetterunderstandthedata-mage-initnotation,let'stakealookatapartial<PROJECT_DIR>/lib/web/mage/redirect-url.jsfileextract:

define([

'jquery',

'jquery/ui'

],function($){

'usestrict';

$.widget('mage.redirectUrl',{

options:{

event:'click',

url:undefined

},

_bind:function(){/*...*/},

_create:function(){/*...*/},

_onEvent:function(){/*...*/}

});

return$.mage.redirectUrl;

});

ThishereisajQuerywidgetwrappedasanAMDmodule;moreonthatlateron.data-mage-initknowshowtointerpretmage.redirectUrlasaredirectUrlcomponent.BystudyingtheredirectUrlwidgetcode,wecanseeitcanbeusednotonlywiththebuttonandthelinktypeofelementsbutwiththeselecttypeaswell.Let'sgoaheadandappendourplayground.phtmlfilewiththefollowing:

<adata-mage-init='{"redirectUrl":{"url":"http://test.url"}}'>

<span><?=__('Test')?></span>

</a>

<buttontype="button"

data-mage-init='{"redirectUrl":{"url":"http://test.url"}}'>

<span><?=__('Test')?></span>

</button>

<selectdata-mage-init='{"redirectUrl":{"event":"change"}}'>

<optionvalue="http://test.url/1">Test#1</option>

<optionvalue="http://test.url/2">Test#2</option>

<optionvalue="http://test.url/3">Test#3</option>

</select>

Whiletheclickeventworksperfectlyforlinkandbuttonelements,theselectelementreliesonamorespecificchangeevent.Therefore,ourselectelementexploitsthefactthattheredirectUrlcomponentacceptstheeventconfigurationoption.Thismakesforaniceandcleanlittleexampleofreusingasinglecomponentmultipletime.

Tobetterunderstandthe<scripttype="text/x-magento-init"/>notation,let'stakealookatapartial<MAGENTO_DIR>/module-cookie/view/frontend/web/js/notices.jsfileextract:

define([

'jquery',

'jquery/ui',

'mage/cookies'

],function($){

'usestrict';

$.widget('mage.cookieNotices',{

_create:function(){

//...

}

});

return$.mage.cookieNotices;

});

Justlikeinourfirstexample,thisisjustanotherjQuerywidgetessentially.WhatthecookieNoticeswidgetdoesistakethegivencontentanddisplayitascookienoticealerttotheuser,doingsountiltheuserfinallyhitstheAllowCookiesbutton.Wecaneasilyreusethiswidgettoinjectourowncontent.WhilebothcookieNoticesandredirectUrlarejQuerywidgets,thewaytheyareusedinMagentodiffers.

Let'sgoaheadandappendourplayground.phtmlfilewiththefollowingHTMLbits:

<divid="playgroundCookieBlock"class="messageglobalcookie"

style="display:none;">

<p>

<strong><?=$block->escapeHtml(__('Weusecookiestomakeyourexperiencebetter.'))?></strong>

<span><?=$block->escapeHtml(__('Tocomplywiththenewe-Privacydirective,weneedtoaskforyourconsenttosetthecookies.'))?></span>

<?=$block->escapeHtml(__('<ahref="%1">Learnmore</a>.','http://magelicious.loc/privacy'),['a'])?>

</p>

<divclass="actions">

<buttonid="btn-cookie-allow"class="actionallowprimary">

<span><?=$block->escapeHtml(__('AllowCookies'))?></span>

</button>

</div>

</div>

Thisistosimulateourintentforacustomcookiewidget,withspecialcontentandacookiename.Let'sfurtherappendtheplayground.phtmlfilewithadeclarativecalltocookieNoticesJScomponent:

<scripttype="text/x-magento-init">

{

"#playgroundCookieBlock":{

"cookieNotices":{

"cookieAllowButtonSelector":"#btn-cookie-allow",

"cookieName":"playgroundCookie",

"cookieValue":"playgroundCookieValue",

"cookieLifetime":"300",

"noCookiesUrl":"http://magelicious.loc/no-cookies"

}

}

}

</script>

UnliketheredirectUrlwidget,whichhadanicelistofoptionsdefinedattheverystartofthewidgetdefinition,thecookieNoticeswidgetdoesnothavethose.Itmerelyreferencesthoseoptionsthroughoutthecode,viathis.options.<optionPushedViaMagentoInit>calls.ThisisreallyadefaultjQuerywidgetoptionsobject.Thereasonwearebringingitupismerelytounderstandhow,mostofthetime,oneneedstotakeamoreinvolvedapproachtowardinspectingexistingJavaScriptcomponentscode,insteadofjustfocusingonthesetofpossibledefaultoptions.

Tobetterunderstandthe<script>tagnotation,let'stakealookatapartial<MAGENTO_DIR>/module-ui/view/base/web/js/modal/modal.jsfileextract:

define([

/*...*/

],function(/*...*/){

'usestrict';

//...

$.widget('mage.modal',{

//...

});

return$.mage.modal;

});

Asintheprevioustwoexamples,thisagainisjustajQuerywidget.Nowlet'sgoaheadandappendourplayground.phtmlfilewiththefollowingHTMLbits:

<div>

<ahref="#"id="playgroundModalLink">Showmodal!</a>

</div>

<divid="playgroundModal">

<p>Content...</p>

</div>

Thisistosimulateourintentofcreatingamodalbox,withspecialcontent.Now,let'susethemodalwidgettoturnthisintoanactualmodal.Wefurtherappendourplayground.phtmlfile,asfollows:

<script>

require([

'jquery',

'mage/translate',

'Magento_Ui/js/modal/modal'

],function($,$t,modal){

varoptions={

title:'PlaygroundModal',

buttons:[{

text:$t('Continue'),

click:function(){

this.closeModal();

}

}]

};

modal(options,$('#playgroundModal'));

$('#playgroundModalLink').on('click',function(){

$('#playgroundModal').modal('openModal');

});

}

);

</script>

Thistimeweareusingthe<script>tagapproachtoutilizetheJScomponent.

Toensureourcodeevaluatesonpageload,wecanfurtherwrapourmodalwidgetrelatedcodeintoafunction,asfollows:

<script>

require([

/*libraries...*/

],function(/*params...*/){

$(function(){

//RawJScode...

});

}

);

</script>

Likewise,wecanuseaRequireJSdomReadymoduletoexecuteourJScodeonDOM:

<script>

require([

'jquery',

'mage/translate',

'domReady!'

],function($,$t){

//RawJScode...

});

</script>

The!characterusedindomReady!isasyntaxreservedforplugins.Whilethereismoretoit,sufficetosaythatinacaseofdomReady!thepluginexistssimplyasawayofwaitinguntilDOMgetsloadedbeforeinvokingourfunction.

ThechoiceofcallingandinitializingJScomponentsdependsonhowtheyarewrittenandhowtheyareintendedtobeused.Weusethedeclarativenotationwhenourcomponentrequiresinitialization.Theconfigurationispreparedonthebackendandsimplyoutputtedtothepage.WeusetheimperativenotationonthepagesthatuserawJScode;thisallowsustoexecuteparticularbusinesslogic.

MeetRequireJSTothispoint,wehavebeenusingthingslikeredirectUrlandcookieNoticesoutofthinair,buthowexactlydothesecomponentsbecomeavailabletoourcode?Theansweris,viaRequireJS,alibrarythatunderliesnearlyeveryotherJSfeaturebuiltintoMagento.TheoverallroleofRequireJSissimple;itisaJSmodulesystemthatimplementstheAsynchronousModuleDefinition(AMD)standard,whichservesasanimprovementovertheweb'scurrentglobalsandscripttags.

WehavealreadyseentheformatoftheseAMDmodulesintheprecedingexamples,whichcomesdownthefollowing:

define(['dep1','dep2'],function(dep1,dep2){

returnfunction(){

//Modulevaluetoreturn

};

});

ThegistofAMDmodulesfunctionalitycomesdowntoeachmodulebeingableto:

RegisterthefactoryfunctionviadefineInjectdependencies,insteadofusingglobalsExecutethefactoryfunctionwhenalldependenciesbecomeaccessiblePassdependentmodulesasargumentstothefactoryfunction

Thisstrategysolvesmanyoftheconventionaldependencyissues,wheredependenciesareassumedtobeimmediatelyavailablewhenthefunctionexecutes,whichisnotalwaysthecase.

IfweweretodoaViewPageSourceonourPlaygroundpageinabrowser,wewouldseethree<scripttype="text/javascript"src="...">tagswiththeirsrcattributespointingtothefollowingJSfiles:

frontend/Magento/luma/en_US/requirejs/require.js

frontend/Magento/luma/en_US/mage/requirejs/mixins.js

frontend/Magento/luma/en_US/requirejs-config.js

Aquicklookatthepartialrequirejs-config.jsfilerevealshowthesegetloaded:

(function(require){

/*...*/

(function(){

varconfig={

map:{

'*':{

'redirectUrl':'mage/redirect-url',

}

}

};

require.config(config);

})();

/*...*/

(function(){

varconfig={

map:{

'*':{

cookieNotices:'Magento_Cookie/js/notices'

}

}

};

require.config(config);

})();

/*...*/

})(require);

Thesetwomappingsbreakdownasfollows:

Theleft-handsidepointstothefreelygivennameofourJScomponent,whichessentiallytellsconsumershowtoreferenceit.ThisiswhywewereabletousethesetwocomponentssimplybyreferencingthemviaredirectUrlandcookieNotices.Theright-handsidepointstothelocationofourJScomponent:

mage/redirect-url,wheremagepointstothe<PROJECT_DIR>/lib/web/magedirectory,andredirect-urlfurtherpointstotheredirect-url.jsfilewithinthatdirectoryMagento_Cookie/js/notices,whereMagento_Cookiepointstothe<MAGENTO_DIR>/module-cookie/view/frontend/webdirectory,andjs/noticesfurtherpointstothejs/notices.jsfilewithinthatdirectory

Furtherobservingtherequirejs-config.jsfile,asidefrommap,thereareafewotherimportantkeyswhoserolesareworthknowing:

varconfig={

map:{

'*':{

/*...*/

}

},

paths:{

/*...*/

},

shim:{

/*...*/

},

deps:[

/*...*/

],

config:{

mixins:{

/*...*/

}

}

};

Thesebreakdownasfollows:

map:Forthegivenmoduleprefix;insteadofloadingthemodulewiththegivenID,substituteadifferentmoduleIDpaths:PathmappingsformodulenamesnotfounddirectlyunderbaseUrlshim:Configurethedependencies,exports,andcustominitializationforolderbrowserglobalsscriptsthatdonotusedefinefordeclaringthedependenciesandsettingthemodulevaluedeps:Anarrayofdependenciestoloadconfig/mixins:ListofJSclassmappings,forclasseswhosemethodsareaddedto,ormixedin,withotherJSclasses

Seehttps://requirejs.org/docs/api.htmlformoreinformationontheRequireJSAPI.

Thetakeawayhereisthatourownmodulescandefinetherequirejs-config.jsfileontheirown,underthe<MODULE_DIR>/view/frontenddirectory,allowingustohookintothefinalMagentorequirejs-config.jsfilethatgetsgeneratedforthebrowser.This,inturn,allowsustoeasilyregisterourowncomponents,overrideexistingmappings,paths,andotherthings.

ReplacingjQuerywidgetcomponentsWhilethemajorityofthetime,wewouldwanttoleavetheexistingJScomponentstoworktheirmagicasis,therearetimeswhenbusinessrequirementsaredrasticenoughtomakethewholecomponentunusable.ThinkingintermsofPHPclasses,wecanimaginethatclassAimplementsX,whereaswewanttohaveacompletelydifferentimplementationofX,let'scallitB,thatsharesverylittlewithA.ThisisacasewheresimplyhavingBextendsAwouldnotsuffice,soweoptfordirectlyBimplementsX.WhiletherearenointerfacesinpureJS,thisdoesnotmeanwecannotcompletelyreplaceoneconcreteclasswithanother,aslongasweensurethosefewcrucialmethodsareavailableviathenewclass.

ReplacingJSclassesiseasywithMagento.Let'simaginewewanttofullyreplacetheredirectUrlcomponent.

Westartbycreatingthe<MODULE_DIR>/view/frontend/requirejs-config.jsfile,asfollows:

varconfig={

map:{

'*':{

redirectUrl:'Magelicious_Jsco/js/redirect-url'

}

}

};

WethenimplementtheactualMagelicious_Jsco/js/redirect-urlaspartofthe<MODULE_DIR>/view/frontend/web/js/redirect-url.jsfile,asfollows.

define([

'jquery',

],function($){

'usestrict';

$.widget('magelicious.redirectUrl',{

_create:function(){

//Newimplementation

console.log('magelicious.redirectUrl');

}

});

return$.magelicious.redirectUrl;

});

magelicious.redirectUrlmatchesthenewnameofourwidget,whereasmageliciousis

ournamespaceandredirectUrlistheactualnameofthewidgetwithinournamespace.

Oncewerefreshthestaticcontentviathephpbin/magentosetup:static-content:deploycommand,weshouldnowbeabletoseemagelicious.redirectUrlshowupinthebrowserconsolewindow.Clearly,thecurrentimplementationofredirectUrlwouldbreakthefunctionalitywehadwiththeoriginalcomponent,butitgoestoshowhoweasilywecanfullyreplacethecomponentwithanewone.

ExtendingjQuerywidgetcomponentsAssumingwewishtoextendtheredirectUrlcomponentinsteadofreplacingitcompletely,wecandosoinasimilarfashion.Theentryinourrequirejs-config.jsremainsthesame,whereasthedifferenceliesinhowweeditourredirect-url.jsfile:

define([

'jquery',

'jquery/ui',

'mage/redirect-url'

],function($){

'usestrict';

$.widget('magelicious.redirectUrl',$.mage.redirectUrl,{

/*Overrideofparent_onEventmethod*/

_onEvent:function(){

//Callparent's_onEvent()methodifneeded

returnthis._super();

}

});

return$.magelicious.redirectUrl;

});

Usingthe_superor_superApplyisajQuerywidgetwayofinvokingmethodsofthesamenameintheparentwidget.Whilethisapproachworks,thereisamoreelegantsolutioncalledmixins.

TheMagentomixinsforJSaremuchlikeitspluginsforPHP.Toconverttothemixinapproach,wereplaceourrequirejs-config.jswithcontent,asfollows.

varconfig={

config:{

mixins:{

'mage/redirect-url':{

'Magelicious_Jsco/js/redirect-url-mixin':true

}

}

}

};

Note,thatthistimeweareusingthefullpath'mage/redirect-url'insteadoftheredirectUrlaliasontheleftsideofthemapping,whereastherightsideofmappingpointstoourmixin.Theconventionistousethe-mixingsuffixontopoftheoriginalJSfilename.

Wethencreate<MODULE_DIR>/view/frontend/web/js/redirect-url-mixin.jswithcontent,as

follows:

define([

'jquery'

],function($){

returnfunction(originalWidget){

$.widget(

'magelicious.redirectUrl',

originalWidget,{

/*Redefined_onEventmethod*/

_onEvent:function(){

console.log('_onEventviamixin');

//Callparent's_onEvent()methodifneeded

returnthis._super();

}

}

);

return$.magelicious.redirectUrl;

};

});

Theexampleheremightnotdojustice,asitmerelylooksmorecomplexthanthepreviousexampleofdirectlyextendingthewidget.ThisisbecausewecannotsimplydooriginalWidget._onEvent=function(){/*...*/};ororiginalWidget._proto._onEvent=function(){/*...*/};andthusoverridethewidgetmethod.Widgetmethodsneedtobeoverriddenontheprototype,which,inourcase,essentiallymeanscreatinganewwidgetfromtheoriginal.

Ifwewereaddingamixinforanon-widgettypeofJS,suchasMagento_Checkout/js/action/place-order,thentheapproachwouldbedifferent,asshowninMagento_CheckoutAgreements/js/model/place-order-mixin.

CreatingjQuerywidgetscomponentsCreatingsimplejQuerywidgetscomponentsisprettystraightforwardfromaMagentopointofview.TheactualknowledgeofbuildingrobustjQuerywidgetsdependsonourknowledgeofjQueryitself.

Let'sassumeourwidgetwillbecalledwelcome,anditspurposeistosimplyoutputWelcome%name%totheelement,providedwepassedonthenameoptionduringwidgetinitialization.

Westartbyaddingthemappingunderour<MODULE_DIR>/view/frontend/requirejs-config.jsfile,asfollows:

varconfig={

map:{

'*':{

welcome:'Magelicious_Jsco/js/welcome'

}

}

};

Wethendefinethewidgetitself,aspartofthe<MODULE_DIR>/view/frontend/web/js/welcome.jsfile,asfollows:

define([

'jquery',

'mage/translate'

],function($,$t){

'usestrict';

$.widget('magelicious.welcome',{

_create:function(){

this.element.text($t('Welcome'+this.options.name));

}

});

return$.magelicious.welcome;

});

Wecanseethatourwidgetisquitesimple.IfwenowrunMagento'ssetup:static-content:deploycommand,ourwidgetshouldalreadybereadyforuse,aswecannowinitializeitfromtemplatefiles.

Finally,let'sinitializeourwelcomewidgetbyamendingplayground.phtml,asfollows:

<?php$helper=$this->helper('Magento\Framework\Json\Helper\Data')?>

<spandata-mage-init='<?=$helper->jsonEncode(

['welcome'=>['name'=>'JohnDoe']]

)?>'></span>

Withthisinplace,weshouldnowbeabletoseetheWelcomeJohnDoemessageinourbrowser.Whilethislittlecomponentseemsquiteanoverkillforwhatitdoes,theconceptsbehinditarewhatmatters.

Seehttps://api.jqueryui.com/jquery.widget/formoreinformationoncreatingjQuerywidgets.

CreatingUI/KnockoutJScomponentsTothispoint,wehaveonlybeendealingwithjQuerywidgetsascomponents.Whileextremelypowerful,jQuerywidgetsarenotbestsuitedforrenderingrobustcomponentswithcomplexHTMLstructures.TheothertypeofJScomponentsiswhatwerefertoasUI/KnockoutJScomponents.BuiltontheshouldersoftheKnockoutJSlibrary,thesecomponentsallowpowerfultemplatingofourdata,amongotherthings.Withoutgettingtoodeepintotheinsandoutsofthesetypeofcomponents,sufficetosaythatthemainconstructwearereferringtowhenwespeakofUI/KnockoutJScomponentsisuiComponent.

Asper<MAGENTO_DIR>/module-ui/view/base/requirejs-config.js,theuiComponentmapstotheMagento_Ui/js/lib/core/collectionJSfile.Inspectingthecollection.jsfile,wecanseethatuiComponentextendsuiElement,whichmapstotheMagento_Ui/js/lib/core/element/elementJSfile.TheuiComponentanduiElementmakeuseoftheko,underscore,mageUtils,uiRegistry,uiEvents,anduiClasslibraries,amongotherthings,soit'sworthgettingourselvesfamiliarwiththose.

CreatingnewUI/KnockoutJScomponentsisaslightlymoreinvolvedprocessthancreatingajQuerywidget.

Westartbycreatingthepropermappingunderour<MODULE_DIR>/view/frontend/requirejs-config.jsfile,asfollows:

varconfig={

map:{

'*':{

popularProducts:'Magelicious_Jsco/js/popular-products'

}

}

};

ThispartisthesameaswithjQuerywidgets.Herewesimplyregister,oraliasifyouwill,ourcomponentnametoitsfilelocation.

Wethendefinethecomponentitself,underthe<MODULE_DIR>/view/frontend/web/js/popular-products.jsfile,asfollows:

define([

'jquery',

'uiComponent',

'ko',

'mage/translate'

],function($,Component,ko,$t){

'usestrict';

returnComponent.extend({

defaults:{

template:'Magelicious_Jsco/popular-products',

title:$t('PopularProducts'),

products:[],

},

getTitle:function(){

returnthis.title;

}

});

}

);

ThebasisofallUIcomponentsisuiComponent.WepassontheinstanceofuiComponentasaComponentparameter.WethenimplementthespecificsofourcomponentaspartoftheJSONobjectpassedontotheComponent.extendmethod.

WithourcomponentJSfilenowinplace,wefurthercreatethetemplatefilereferencedbythecomponent.Wedosounderthe<MODULE_DIR>/view/frontend/web/template/popular-products.htmlfile,asfollows:

<h4data-bind="text:getTitle()"></h4>

<uldata-bind="foreach:products">

<li>

<span>

<spandata-bind="text:title"></span>

(<spandata-bind="text:sku"></span>)

</span>

</li>

</ul>

WhathappensintheHTMLtemplatefilesisallaboutKnockoutJS,whichmeansacertainpartoftheKnockoutJSlibraryisrequiredinordertobuiltUI/KnockoutJScomponents.

Seehttp://knockoutjs.comformoreinformationontheKnockoutJSlibrary.

Wethenamendourjsco_playground_index.xmlbyaddingthefollowinglineunder<referenceContainername="content">:

<blockname="popular_products"

template="Magelicious_Jsco::popular-products.phtml"/>

popular-products.phtmliswherewewillinstantiateourUI/KnockoutJScomponent.

Finally,wecreate<MODULE_DIR>/view/frontend/templates/popular-products.phtmlwithcontent,asfollows:

<?php$jsonHelper=$this->helper('Magento\Framework\Json\Helper\Data');?>

<divclass="popular-products"data-bind="scope:'popular-products-scope'">

<!--kotemplate:getTemplate()--><!--/ko-->

</div>

<scripttype="text/x-magento-init">

{

".popular-products":{

"Magento_Ui/js/core/app":{

"components":{

"popular-products-scope":{

"component":"popularProducts",

"products":<?=/*@escapeNotVerified*/$jsonHelper->jsonEncode([

['sku'=>'sku1','title'=>'Title1'],

['sku'=>'sku2','title'=>'Title2']

])?>

}

}

}

}

}

</script>

Hereweareusingthedeclarativeapproachtoinitializeourcomponent.ThestructureoftheJSONobjectunderthescripttagmightseemabitconfusingatfirst.The.popular-productskeyisessentiallyaselector,targetingwhateverHTMLelementitmightfind.Magento_Ui/js/core/appisanaliasfortheapp.jsfile,whichcreatestheUIcomponentsinstancesaccordingtotheconfigurationoftheJSONusingtheuiLayoutcomponent.componentsisakeyunderwhichwenestoneormorecomponentswewishtoinitialize.popular-products-scopeissortofascopekeyassignedtoourcomponent,whichweusetodata-bindthescopevaluetotheHTMLelement.

Clearingthecacheandredeployingthestaticfiles,weshouldnowbeabletoseeournewlycreatedcomponent.

ExtendingUI/KnockoutJScomponentsExtendingUI/KnockoutJScomponentsisaprocesssimilartoextendingthejQuerywidgets.Let'sforamomentassumewehavetheMagelicious_Jsco2modulethatwantstooverrideourpopularProductscomponent.

Thewaytodoitwouldbetoaddthepropermappingunderthemapkeyofour<MODULE2_DIR>/view/frontend/requirejs-config.jsfile:

varconfig={

map:{

'*':{

popularProducts:'Magelicious_Jsco2/js/new-popular-products'

}

}

};

Wethencreatethepropernew-popular-products.jsfile,asfollows:

define([

'jquery',

'Magelicious_Jsco/js/popular-products',

'ko',

'mage/translate',

],function($,popularProductsComponent,ko,$t){

'usestrict';

returnpopularProductsComponent.extend({

getTitle:function(){

return'NEW|'+this._super();

}

});

}

);

TheexamplehereshowsthatwearenolongerpassingintheinstanceofuiComponent,rathertheinstanceoftheoriginalMagelicious_Jsco/js/popular-productsthatwewishtoextend.SimplyusingtheextendmethodonourpopularProductsComponentobjectallowsustoextenditeasily.Byredefiningthemethodsofthesamename,suchasgetTitle,weeffectivelyoverridethesamemethodonthecomponentwearerunningtheextendon.

SummaryThoughtherearelotsofotherbitsandpiecesinvolvedinstorefrontdevelopment,JScomponentsmakeforthemostchallengingpartofit.Understandinghowtowritenewcomponents,aswellashowtooverrideorbypassexistingonesisanessentialskillforanyMagentodeveloper,beitbackendorfrontend.Admittedly,thischaptertookmoreofabackend/module-developertypeofanapproachonthesubject.

Wheneverthereisaneedtochangethebehavioroftheunderlyingcomponent,whetheritispureJS,ajQuerywidget,orUI/KnockoutJS,weshouldconsiderthescopeofchangesinordertodecidewhetherweshouldapproachitbyreplacing,overriding,orusingmixin.

Movingforward,wearegoingtotakealookatsomeoftheneatthingswecandoaroundcustomizingthestorefrontcatalogbehavior,mostofwhichcomedowntopluginsandJScomponents.

CustomizingCatalogBehaviorRightoutofthebox,Magentoprovidesaprettyrobustcatalogfunctionality.Managingcategoriesandproductsonamulti-store,multi-currency,multi-languagelevelwithasupportforcustomattributes,catalogsearch,catalogrules,andalikearefeaturesthatarelikelytosufficeformostcustomers.Sometimes,however,certainintegrationsorlargerandsmallerfeaturesarerequested,thatbuildontopoftheexistingfunctionality.Whethertoimproveuserexperienceoraccommodateessentialbusinessrequirements,catalogcustomization'splayamajorroleineverydayMagentodevelopment.

Wearegoingtocustomizeourcatalogbehaviorby:

CreatingthesizeguideCreatingthesamedaydeliveryFlaggingnewproducts

Thesestandonlyasasmallfragmentofwhat'spossiblewithMagentocatalogcustomizations.

Movingforward,ourworkistobedoneaspartoftheMagelicious_Catalogmodule,whichwewilldevelopthroughoutthechapter.

TechnicalrequirementsYouwillneedtohavebasicknowledgeofPHP,OOP,JavaScript,andXML.YouwillalsoneedApache,MySQL,andAMPPSinstalledonyoursystemtoexecutethecodes.

ThecodefilesofthischaptercanbefoundonGitHub:https://github.com/PacktPublishing/Magento-2-Quick-Start-Guide.

CheckoutthefollowingvideotoseetheCodeinAction:

http://bit.ly/2MFJaCN.

CreatingthesizeguideWehavebeenaskedtoaddafunctionalitythatshowsthesizeguideonaproductviewpage.ThisistoappearasanewtabnexttotheexistingDetails,MoreInformation,andReviewstabs.Thecontentofthesizeguidetabistobethesameforallproductscontainingthesizeattribute.WealsoneedittobeeditablefromMagentoadmin.

Let'stakeamomenttothinkaboutourapproachhere:

TobethesameforallproductsandeditablefromMagentoadminneedstheCMSblockTheCMSblockneedssetupscriptforcreatingthesizeguideblockToAppearasanewtabnexttotheexistingtabsrequiresacatalog_product_view.xmllayoutupdate

Assumingwehavedefinedregistration.php,composer.json,andetc/module.xmlasbasicmodulefiles,wecandealwiththemorespecificdetailsofourMagelicious_Catalogmodule.

Westartbydefining<MODULE_DIR>/Setup/InstallData.phpwithcontent,asfollows:

namespaceMagelicious\Catalog\Setup;

classInstallDataimplements\Magento\Framework\Setup\InstallDataInterface{

protected$searchCriteriaBuilder;

protected$blockRepository;

protected$blockFactory;

publicfunction__construct(

\Magento\Framework\Api\SearchCriteriaBuilder$searchCriteriaBuilder,

\Magento\Cms\Api\BlockRepositoryInterface$blockRepository,

\Magento\Cms\Api\Data\BlockInterfaceFactory$blockFactory

){

$this->searchCriteriaBuilder=$searchCriteriaBuilder;

$this->blockRepository=$blockRepository;

$this->blockFactory=$blockFactory;

}

publicfunctioninstall(

\Magento\Framework\Setup\ModuleDataSetupInterface$setup,

\Magento\Framework\Setup\ModuleContextInterface$context

){

$setup->startSetup();

$searchCriteria=$this->searchCriteriaBuilder

->addFilter('identifier','size-guide','eq')

->create();

$blocks=$this->blockRepository->getList($searchCriteria)->getItems();

if(empty($blocks)){

/*@var\Magento\Cms\Api\Data\BlockInterface$block*/

$block=$this->blockFactory->create();

$block->setIdentifier('size-guide');

$block->setTitle('SizeGuide');

$block->setContent('Sizeguide!');

$this->blockRepository->save($block);

}

$setup->endSetup();

}

}

TheInstallDatascriptensuresthatthesize-guideCMSblockiscreatedduringmoduleinstallationifitdoesnotalreadyexist.Withthisinplace,wecanalreadyrunthesetup:upgradecommand.Thisshouldinstallourmoduleandcreatethesize-guideCMSblock.

Wethendefine<MODULE_DIR>/Block/SizeGuide.phpwithcontent,asfollows:

namespaceMagelicious\Catalog\Block;

classSizeGuideextends\Magento\Cms\Block\Blockimplements\Magento\Framework\DataObject\IdentityInterface{

protected$product;

protected$coreRegistry;

publicfunction__construct(

\Magento\Framework\View\Element\Context$context,

\Magento\Cms\Model\Template\FilterProvider$filterProvider,

\Magento\Store\Model\StoreManagerInterface$storeManager,

\Magento\Cms\Model\BlockFactory$blockFactory,

\Magento\Framework\Registry$coreRegistry,

array$data=[]

){

$this->coreRegistry=$coreRegistry;

parent::__construct($context,$filterProvider,$storeManager,$blockFactory,$data);

}

publicfunction_toHtml(){/*...*/}

publicfunctiongetProduct(){

if(!$this->product){

$this->product=$this->coreRegistry->registry('product');

}

return$this->product;

}

}

Thisistheactualblockclassthatwewilloutputontheproductviewpage.Theregistry'sobjectproductkeyisalreadysetbytheparentclassupthelayouttree.Thisallowsustoeasilyfetchtheinstanceofthecurrentproduct.

The_toHtmlmethodisfurtherimplemented,asfollows:

protectedfunction_toHtml()

{

if($this->getProduct()->getTypeId()==\Magento\ConfigurableProduct\Model\Product\Type\Configurable::TYPE_CODE){

$configurableAttributes=$this->getProduct()->getTypeInstance()->getConfigurableAttributesAsArray($this->getProduct());

foreach($configurableAttributesas$attribute){

if(isset($attribute['attribute_code'])&&$attribute['attribute_code']=='size'){

returnparent::_toHtml();

}

}

}

return'';

}

Thisisthegistofoursizeguidefunctionality.Theconfigurabletypeandsizeattributecodechecksensurethattheoutputof_toHtmlrendersthesize-guideblockonlyforcertaingroupsofproducts.

Wefinallydefine<MODULE_DIR>/view/frontend/layout/catalog_product_view.xmlwithcontent,asfollows:

<page>

<body>

<referenceBlockname="product.info.details">

<blockclass="Magelicious\Catalog\Block\SizeGuide"name="size-guide"after="-"group="detailed_info">

<arguments>

<argumentname="block_id"xsi:type="string">size-guide</argument>

<argumentname="css_class"xsi:type="string">description</argument>

<argumentname="at_label"xsi:type="string">none</argument>

<argumentname="title"translate="true"xsi:type="string">SizeGuide</argument>

</arguments>

</block>

</referenceBlock>

</body>

</page>

ThisisthegluethatbindsourSizeGuideblocktoaproductviewpage,and,morespecifically,theproduct.info.detailsblockthatneatlycontainstheDetails,MoreInformation,andReviewstabs.

Thefinalproductviewpageresultshouldlooklikethis:

CreatingthesamedaydeliveryWehavebeenaskedtoaddafunctionalitythatshowsanactivecountdownwithaYouhave%h%min%sectocatchoursamedaydeliveryoffermessageonaproductviewpage,whereasthecountdownisbasedonanoptionallyassigneddailycutoffAttime,setforeveryproductindividually,foreverydayofaweekindependently.

Let'stakeamomenttothinkaboutourapproachhere:

EveryproductandeverydayofaweekimplyMondaytoSunday_[Cutoff_At]productattributesProductattributesimplysetupscriptActivecountdownimpliesJScomponents

Westartbybumpingupthesetup_versionvalueofour<MODULE_DIR>/etc/module.xmlfilefrom1.0.0to1.0.1.Thisallowsustointroducethe<MODULE_DIR>/Setup/UpgradeData.phpfilewithanupgrade,asfollows:

protectedfunctionupgradeToVersionOneZeroOne(

\Magento\Framework\Setup\ModuleDataSetupInterface$setup

){

$eavSetup=$this->eavSetupFactory->create(['setup'=>$setup]);

$days=[

'monday','tuesday','wednesday','thursday',

'friday','saturday','sunday'

];

$sortOrder=100;

foreach($daysas$day){

$eavSetup->addAttribute(

\Magento\Catalog\Model\Product::ENTITY,

$day.'_cutoff_at',

[

'type'=>'varchar',

'label'=>ucfirst($day).'CutoffAt',

'input'=>'text',

'required'=>false,

'sort_order'=>$sortOrder++,

'global'=>\Magento\Eav\Model\Entity\Attribute\ScopedAttributeInterface::SCOPE_STORE,

'group'=>'Cutoff',

]

);

}

}

TheaddAttributemethodhereisrunforeachdayoftheweek,thuscreatingmonday_cutoff_attosunday_cutoff_atproductattributes.If,atthispoint,weweretoruntheMagento'ssetup:upgradecommand,ourUpgradeDatascriptwouldgetexecutedandschema_versionanddata_versionnumbersfromwithinthesetup_moduletablewouldgetbumpedtothe1.0.1version.Likewise,goingintotheMagentoadminareaandeditingorcreatinganewproduct,wouldshowthefollowingscreen.Thisiswhereweenabletheusertoenterthetimeofthedayinan<hour>:<minute>format,suchas15:30.Thistime,ifentered,willlaterbeusedbytheJScomponenttorenderthecountdownfunctionalityonthestorefrontproductviewpage:

Wethencreate<MODULE_DIR>/Block/Product/View/Cutoff.php,asfollows:

namespaceMagelicious\Catalog\Block\Product\View;

classCutoffextends\Magento\Framework\View\Element\Templateimplements\Magento\Framework\DataObject\IdentityInterface

{

private$product;

protected$coreRegistry;

protected$localeDate;

publicfunction__construct(

\Magento\Framework\View\Element\Template\Context$context,

\Magento\Framework\Registry$coreRegistry,

\Magento\Framework\Stdlib\DateTime\TimezoneInterface$localeDate,

array$data=[]

){

$this->coreRegistry=$coreRegistry;

$this->localeDate=$localeDate;

parent::__construct($context,$data);

}

publicfunctiongetProduct(){/*...*/}

publicfunctiongetCutoffAt(){/*...*/}

publicfunctiongetIdentities(){/*...*/}

}

Wewillusethisclasswhenwereachourlayoutupdate.

ThegetProductmethodisfurtherimplemented,asfollows:

publicfunctiongetProduct()

{

if(!$this->product){

$this->product=$this->coreRegistry->registry('product');

}

return$this->product;

}

Asmentionedpreviously,theregistry'sproductkeyisalreadysetbytheparentclassupthelayouttree,soweexploitthatfacttofetchthecurrentproduct.

ThegetCutoffAtmethodisfurtherimplemented,asfollows:

publicfunctiongetCutoffAt()

{

$timezone=new\DateTimeZone($this->localeDate->getConfigTimezone());

$now=new\DateTime('now',$timezone);

$day=strtolower($now->format('l'));

$cutoffAt=$this->getProduct()->getData($day.'_cutoff_at');

if($cutoffAt){

$timeForDay=\DateTime::createFromFormat(

'Y-m-dH:i',

$now->format('Y-m-d').''.$cutoffAt,

$timezone

);

if($timeForDayinstanceof\DateTime){

return$timeForDay->format(DATE_ISO8601);

}

}

return0;

}

ThisisthegistofoursamedaydeliveryfunctionalityfromthePHPsideofthings.Weensureweproperlyreturnthefulldateandtimebasedontheproduct's$day.'_cutoff_at'attributevalue;thiswilllaterbepassedontotheJScomponent.

Finally,thegetIdentitiesmethodisfurtherimplemented,asfollows:

publicfunctiongetIdentities()

{

$identities=$this->getProduct()->getIdentities();

$timezone=new\DateTimeZone($this->localeDate->getConfigTimezone());

$now=new\DateTime('now',$timezone);

$day=strtolower($now->format('l'));

returnarray_push($identities,$day);

}

ThegetIdentitiesmethodhasbeenimplementedinawaytoensurecachingofthisblockisconsideredinarelationtoproductidentityaswellasthedayoftheweek.

Wethencreatethe<MODULE_DIR>/view/frontend/requirejs-config.jsfile,asfollows:

varconfig={

map:{

'*':{

cutoffAt:'Magelicious_Catalog/js/cutoff'

}

}

};

ThisregistersthecutoffAtcomponentwithMagento,whichpointstoourmodule'scutoff.jsfile.

Wethencreatethe<MODULE_DIR>/view/frontend/web/js/cutoff.jsfile,asfollows:

define([

'jquery',

'uiComponent',

'ko',

'moment'

],function($,Component,ko,moment){

'usestrict';

returnComponent.extend({

defaults:{

template:'Magelicious_Catalog/cutoff',

expiresAt:null,

timerHide:false,

timerHours:null,

timerMinutes:null,

timerSeconds:null,

},

initialize:function(){

this._super();

this.countdown(this);

returnthis;

},

initObservable:function(){

this._super()

.observe('timerHidetimerHourstimerMinutestimerSeconds');

returnthis;

},

countdown:function(self){/*...*/}

});

}

);

OurJScomponenttemplatevaluepointsto<MODULE_DIR>/view/frontend/web/template/cutoff.html,whichwewillsoonaddress.expiresAtistheonlyrealoptionthatisexpectedtobepassedonwhenthecomponentisinitialized.Theobservabletimer*optionswillbeusedinternallytocontrolthefunctionalityofourcomponent.

Thecountdownfunctionisfurtherimplemented,asfollows:

countdown:function(self){

vartoday=moment(newDate());

setInterval(function(){

self.expiresAt=moment(self.expiresAt).subtract(1,'seconds');

varmilliseconds=moment(self.expiresAt,'DD/MM/YYYYHH:mm:ss').diff(moment(today,'DD/MM/YYYYHH:mm:ss'));

varduration=moment.duration(milliseconds);

self.timerHours(duration.hours()>=0?duration.hours():0);

self.timerMinutes(duration.minutes()>=0?duration.minutes():0);

self.timerSeconds(duration.seconds()>=0?duration.seconds():0);

if(self.timerHours()==0

&&self.timerMinutes()==0

&&self.timerSeconds()==0

){

self.timerHide(true);

}

},1000);

}

Thishereisthegistofoursamedaydeliveryfunctionality.UsingthecoreJSsetIntervalmethod,wesetupasimpleper-secondcounter.WiththefewlinesofcodewrappedwithinsetInterval,wecontrolourobservabletimer*optionsboundtoourcutoff.htmltemplate.This,inturn,resultsinthevisualcountdowneffect.

Wethencreatethe<MODULE_DIR>/view/frontend/web/template/cutoff.htmlfile,asfollows:

<spanclass="cutoff-component"data-bind="ifnot:timerHide">

<spantranslate="'Youhave'"></span>

<spanclass="timer">

<spanclass="timer-parttimer-part-hours">

<spanclass="numeric"data-bind="text:timerHours"></span>

<spanclass="label"data-bind="i18n:'hours'"></span>

</span>

<spanclass="timer-parttimer-part-minutes">

<spanclass="numeric"data-bind="text:timerMinutes"></span>

<spanclass="label"data-bind="i18n:'minutes'"></span>

</span>

<spanclass="timer-parttimer-part-seconds">

<spanclass="numeric"data-bind="text:timerSeconds"></span>

<spanclass="label"data-bind="i18n:'seconds'"></span>

</span>

</span>

<spantranslate="'tocatchoursamedaydeliveryoffer.'"></span>

</span>

ThisisthetemplatefilebehindourJScomponent.Weseeallthosetimer*optionsbeingboundedtoproperspanelements.Wrappingeverytimer*optioninitsownspanallowsforpotentialflexibilityaroundstylinglateron.

Seehttps://devdocs.magento.com/guides/v2.2/ui_comp_guide/concepts/knockout-bindings.htmlforalistofMagentocustomKnockout.jsbindings.

Wethencreatethe<MODULE_DIR>/view/frontend/templates/product/view/cutoff.phtmlfile,asfollows:

<?php/*@var\Magelicious\Catalog\Block\Product\View\Cutoff$block*/?>

<?php$jsonHelper=$this->helper('Magento\Framework\Json\Helper\Data');?>

<divclass="cutoff"data-bind="scope:'cutoff-scope'">

<!--kotemplate:getTemplate()--><!--/ko-->

</div>

<scripttype="text/x-magento-init">

{

".cutoff":{

"Magento_Ui/js/core/app":{

"components":{

"cutoff-scope":{

"component":"cutoffAt",

"expiresAt":<?=/*@escapeNotVerified*/$jsonHelper->jsonEncode($block->getCutoffAt())?>

}

}

}

}

}

</script>

ThisisthetemplatefilethatinitializesourJScomponent.Withthisfileinplace,wecanfinallygluethingstogetherbyamendingthebodyelementofthe<MODULE_DIR>/view/frontend/layout/catalog_product_view.xmlfile,asfollows:

<referenceBlockname="product.info.extrahint">

<blockname="cutoff"

class="Magelicious\Catalog\Block\Product\View\Cutoff"

template="Magelicious_Catalog::product/view/cutoff.phtml">

</block>

</referenceBlock>

Thefinalproductviewpageresultshouldlooklikethis:

Oncethetimerreaches0hours0minutes0seconds,itshoulddisappear.

FlaggingnewproductsWehavebeenaskedtoaddafunctionalitythatflagseverynewproductshownonthestorefrontcategoryviewandproductviewpageswitha[NEW]prefixinfrontofitsname.Newimpliesanythingwithinthe5daysoftheproduct'screated_atvalue.

Luckilyforus,wecaneasilycontrolaproduct'snameviaanafterpluginonaproduct'sgetNamemethod.AllittakesistodefineanafterGetNamepluginwithacategoryviewandproductviewpagesconstraint,furtherfilteredbyacreated_atconstraint.

Toregistertheplugin,westartbycreatingthe<MODULE_DIR>/etc/frontend/di.xmlfilewithcontent,asfollows:

<config>

<typename="Magento\Catalog\Api\Data\ProductInterface">

<pluginname="newProductFlag"type="Magelicious\Catalog\Plugin\NewProductFlag"/>

</type>

</config>

Wethencreatethe<MODULE_DIR>/Plugin/NewProductFlag.phpfilewithcontent,asfollows:

namespaceMagelicious\Catalog\Plugin;

classNewProductFlag

{

protected$request;

protected$localeDate;

publicfunction__construct(

\Magento\Framework\App\RequestInterface$request,

\Magento\Framework\Stdlib\DateTime\TimezoneInterface$localeDate

)

{

$this->request=$request;

$this->localeDate=$localeDate;

}

publicfunctionafterGetName(\Magento\Catalog\Api\Data\ProductInterface$subject,$result)

{

$pages=['catalog_product_view','catalog_category_view'];

if(in_array($this->request->getFullActionName(),$pages)){

$timezone=new\DateTimeZone($this->localeDate->getConfigTimezone());

$now=new\DateTime('now',$timezone);

$createdAt=\DateTime::createFromFormat('Y-m-dH:i:s',$subject->getCreatedAt(),$timezone);

if($now->diff($createdAt)->days<5){

return__('[NEW]').$result;

}

}

return$result;

}

}

TheafterGetNameisourafterplugintargetingtheproduct'sgetNamemethod.Usingtherequest'sgetFullActionNamemethod,wemakesureourpluginisconstrainedtoonlycatalog_product_viewandcatalog_category_viewpages,orelsetheoriginalproductnameisreturned.Theuseofthepropertimezoneanddiffmethodassuresthatwefurtherfilterdowntoonlythoseproductsthatweconsidernew.Clearingthecacheatthispointshouldallowourfunctionalitytokickin.

Thefinalresultshouldlooklikethis:

SummaryInthischapter,wehavebuiltthreedistinctivefunctionalities,allofwhichrelatetothecatalogpartofMagento.Thoughverylightweight,theystandtoshowhoweasilyMagentocanbeextendedwithnewfeatureswithoutreallyoverridinganyofthecorefiles.UsingpluginsandJScomponentsaremerelysomeoftheapproacheswemighttake.Quiteoften,wewillfindthatasinglerequirementmightbedeliveredwithmorethanoneapproach.Themainguidingruleforourcodeshouldalwaysbe:usetheleastintrusive.Catalogfunctionalityplaysamajorroleinthecustomerconversionprocess,soourpriorityshouldalwaysbefailsafewhenpossible.

Movingforward,wearegoingtotakealookatsomeofthethingswecandotocustomizethecheckout.

CustomizingCheckoutExperiencesWhilethedefaultMagentocheckoutprovideseverythingashopneedstocompleteatransactionsuccessfully,therearedetailsspecifictotheindividualbusinessesthatoftenneedtobeaddressed.Agreatdealofthesedetailsoftenrelatetocheckoutcustomizationsthatallowforthecapturingofadditionalinformationorengagingcustomersinagreementsandsubscriptionactivities.

Movingforward,wearegoingtotakealookatthefollowing:

PassingdatatothecheckoutAddingordernotestothecheckout

TechnicalrequirementsYouwillneedtohavebasicknowledgeofPHP,OOP,JavaScript,andXML.YouwillalsoneedApache,MySQL,andAMPPSinstalledonyoursystemtoexecutethecodes.

ThecodefilesofthischaptercanbefoundonGitHub:https://github.com/PacktPublishing/Magento-2-Quick-Start-Guide.

CheckoutthefollowingvideotoseetheCodeinAction:

http://bit.ly/2PHMwqX.

PassingdatatothecheckoutUnlikethemostlystaticCMS,category,andproductpages,thecheckoutpagehasamoredynamicnature.Itisanapplicationonitsown,primarilyconstructedoutofJScomponents,whichfurtherutilizeMagento'sAPIendpointstomoveusthroughthecheckoutsteps.Magento'sMagento\Checkout\Model\CompositeConfigProvidertypeallowsustopushthenecessaryserver-sideinformationeasilytotheuiComponentofthestorefronts.

Aquicklookupforthename="configProviders"stringacrossthecontentofdi.xmlinthe<MAGENTO_DIR>directoryrevealsdozenofdefinitions.Acloserlookatthe<MAGENTO_DIR>/module-tax/etc/frontend/di.xmlrevealsthefollowing:

<typename="Magento\Checkout\Model\CompositeConfigProvider">

<arguments>

<argumentname="configProviders"xsi:type="array">

<itemname="tax_config_provider"xsi:type="object">Magento\Tax\Model\TaxConfigProvider</item>

</argument>

</arguments>

</type>

WeareessentiallyinjectingnewitemsundertheconfigProvidersargumentoftheMagento\Checkout\Model\CompositeConfigProvidertype.Theimplementationofacustomconfigprovider,suchastheMagento\Tax\Model\TaxConfigProvider,mustimplementtheMagento\Checkout\Model\ConfigProviderInterface.TheunderlyinggetConfigmethodreturnsanarrayofkey-valuemappings,suchas:

return[

'isDisplayShippingPriceExclTax'=>$this->isDisplayShippingPriceExclTax(),

'isDisplayShippingBothPrices'=>$this->isDisplayShippingBothPrices(),

'reviewShippingDisplayMode'=>$this->getDisplayShippingMode(),

/*...*/

];

These,inturn,becomeavailabletotheuiComponent,asobservedin<MAGENTO_DIR>/module-tax/view/frontend/web/js/view/checkout/shipping_method/price.js:

isDisplayShippingPriceExclTax:window.checkoutConfig.isDisplayShippingPriceExclTax,

isDisplayShippingBothPrices:window.checkoutConfig.isDisplayShippingBothPrices,

WecanseethevaluesreturnedbythegetConfigmethodnowavailableundertheJavaScriptwindow.checkoutConfigobject.Thisisasimplemechanismbywhichwe

canpushourserver-sidedatatoourstorefrontwhenapageloads.

Tounderstandcheckoutmodificationsbetter,weshouldfamiliarizeourselveswiththecontentofthewindow.checkoutConfigobject.

AddingordernotestothecheckoutNowthatweunderstandthemechanismbehindthewindow.checkoutConfigobject,let'sputittousebycreatingasmallmodulethataddsordernotesfunctionalitytothecheckout.OurworkistobedoneaspartoftheMagelicious_OrderNotesmodule,withthefinalvisualoutcome,asfollows:

Theideabehindthemoduleistoprovideacustomerwithanoptionofputtinganoteagainsttheirorder.Ontopofthat,wealsoprovideastandardrangeofpossiblenotestochoosefrom.

Assumingwehavedefinedregistration.php,composer.json,andetc/module.xmlasbasicmodulefiles,wecandealwiththemorespecificdetailsofourMagelicious_OrderNotesmodule.

Westartbydefiningthe<MODULE_DIR>/Setup/InstallSchema.phpwithcontent,asfollows:

namespaceMagelicious\OrderNotes\Setup;

classInstallSchemaimplements\Magento\Framework\Setup\InstallSchemaInterface

{

publicfunctioninstall(

\Magento\Framework\Setup\SchemaSetupInterface$setup,

\Magento\Framework\Setup\ModuleContextInterface$context

){

$connection=$setup->getConnection();

$connection->addColumn(

$setup->getTable('quote'),

'order_notes',

[

'type'=>\Magento\Framework\DB\Ddl\Table::TYPE_TEXT,

'nullable'=>true,

'comment'=>'OrderNotes'

]

);

$connection->addColumn(

$setup->getTable('sales_order'),

'order_notes',

[

'type'=>\Magento\Framework\DB\Ddl\Table::TYPE_TEXT,

'nullable'=>true,

'comment'=>'OrderNotes'

]

);

}

}

OurInstallSchemascriptcreatesthenecessaryorder_notescolumninboththequoteandsales_ordertables.Thisiswherewewillstorethevalueofthecustomer'scheckoutnote,ifthereisany.

Wethendefinethe<MODULE_DIR>/etc/frontend/routes.xmlwithcontent,asfollows:

<config>

<routerid="standard">

<routeid="ordernotes"frontName="ordernotes">

<modulename="Magelicious_OrderNotes"/>

</route>

</router>

</config>

TheroutedefinitionhereensuresthatMagentowillrecognizeHTTPrequestsstartingwithordernotes,andlookforcontrolleractionswithinourmodule.

Wethendefinethe<MODULE_DIR>/Controller/Index.phpwithcontent,asfollows:

namespaceMagelicious\OrderNotes\Controller;

abstractclassIndexextends\Magento\Framework\App\Action\Action

{

}

Thisismerelyanemptybaseclass,foroursoon-to-followcontrolleraction.

Wethendefinethe<MODULE_DIR>/Controller/Index/Process.phpwithcontent,asfollows:

namespaceMagelicious\OrderNotes\Controller\Index;

classProcessextends\Magelicious\OrderNotes\Controller\Index

{

protected$checkoutSession;

protected$logger;

publicfunction__construct(

\Magento\Framework\App\Action\Context$context,

\Magento\Checkout\Model\Session$checkoutSession,

\Psr\Log\LoggerInterface$logger

)

{

$this->checkoutSession=$checkoutSession;

$this->logger=$logger;

parent::__construct($context);

}

publicfunctionexecute()

{

//implement...

}

}

ThiscontrolleractionshouldcatchanyHTTPordernotes/index/processrequests.Wethenextendtheexecutemethod,asfollows:

publicfunctionexecute()

{

$result=[];

try{

if($notes=$this->getRequest()->getParam('order_notes',null)){

$quote=$this->checkoutSession->getQuote();

$quote->setOrderNotes($notes);

$quote->save();

$result[$quote->getId()];

}

}catch(\Exception$e){

$this->logger->critical($e);

$result=[

'error'=>__('Somethingwentwrong.'),

'errorcode'=>$e->getCode(),

];

}

$resultJson=$this->resultFactory->create(\Magento\Framework\Controller\ResultFactory::TYPE_JSON);

$resultJson->setData($result);

return$resultJson;

}

Thisiswherewearestoringtheordernotesonourquoteobject.Lateron,wewillpullthisontooursalesorderobject.Wefurtherdefinethe<MODULE_DIR>/etc/frontend/di.xmlwithcontent,asfollows:

<config>

<typename="Magento\Checkout\Model\CompositeConfigProvider">

<arguments>

<argumentname="configProviders"xsi:type="array">

<itemname="order_notes_config_provider"xsi:type="object">

Magelicious\OrderNotes\Model\ConfigProvider

</item>

</argument>

</arguments>

</type>

</config>

Weareregisteringourconfigurationproviderhere.Theorder_notes_config_providermustbeunique.Wethendefinethe<MODULE_DIR>/Model/ConfigProvider.phpwithcontent,asfollows:

namespaceMagelicious\OrderNotes\Model;

classConfigProviderimplements\Magento\Checkout\Model\ConfigProviderInterface

{

publicfunctiongetConfig()

{

return[

'orderNotes'=>[

'title'=>__('OrderNotes'),

'header'=>__('Headercontent.'),

'footer'=>__('Footercontent.'),

'options'=>[

['code'=>'ring','value'=>__('Ringlonger')],

['code'=>'backyard','value'=>__('Trybackyard')],

['code'=>'neighbour','value'=>__('Pingneighbour')],

['code'=>'other','value'=>__('Other')],

]

]

];

}

}

Thisistheimplementationofourorder_notes_config_providerconfigurationprovider.Wecanprettymuchreturnanyarraystructurewewish.Thetop-levelorderNoteswillbeaccessiblelaterviaJScomponentsaswindow.checkoutConfig.orderNotes.Wefurtherdefinethe<MODULE_DIR>/view/frontend/layout/checkout_index_index.xmlwithcontent,asfollows:

<page>

<body>

<referenceBlockname="checkout.root">

<arguments>

<argumentname="jsLayout"xsi:type="array">

<itemname="components"xsi:type="array">

<itemname="checkout"xsi:type="array">

<itemname="children"xsi:type="array">

<itemname="steps"xsi:type="array">

<itemname="children"xsi:type="array">

<itemname="order-notes"xsi:type="array">

<itemname="component"xsi:type="string">

Magelicious_OrderNotes/js/view/order-notes

</item>

<itemname="sortOrder"xsi:type="string">2</item>

<!--closingtags-->

Thereisquiteanestingstructurehere.Ourordernotescomponentisbeinginjectedunderthechildrencomponentofthecheckout'sstepscomponent.

Wethendefinethe<MODULE_DIR>/view/frontend/web/js/view/order-notes.jswithcontent,asfollows:

define([

'ko',

'uiComponent',

'underscore',

'Magento_Checkout/js/model/step-navigator',

'jquery',

'mage/translate',

'mage/url'

],function(ko,Component,_,stepNavigator,$,$t,url){

'usestrict';

letcheckoutConfigOrderNotes=window.checkoutConfig.orderNotes;

returnComponent.extend({

defaults:{

template:'Magelicious_OrderNotes/order/notes'

},

isVisible:ko.observable(true),

initialize:function(){

//TODO

},

navigate:function(){

//TODO

},

navigateToNextStep:function(){

//TODO

}

});

});

ThisisouruiComponent,poweredbyKnockout.Thetemplateconfigurationpointstothephysicallocationofthe.htmlfilethatisusedasacomponent'stemplate.ThenavigateandnavigateToNextStepareresponsiblefornavigationbetweenthecheckoutstepsduringcheckout.Let'sextendtheinitializefunctionfurther,asfollows:

initialize:function(){

this._super();

stepNavigator.registerStep(

'order_notes',

null,

$t('OrderNotes'),

this.isVisible,

_.bind(this.navigate,this),

15

);

returnthis;

}

Weusetheinitializemethodtoregisterourorder_notesstepwiththestepNavigator.

Let'sextendthenavigateToNextStepfunctionfurther,asfollows:

navigateToNextStep:function(){

if($(arguments[0]).is('form')){

$.ajax({

type:'POST',

url:url.build('ordernotes/index/process'),

data:$(arguments[0]).serialize(),

showLoader:true,

complete:function(response){

stepNavigator.next();

}

});

}

}

WeusethenavigateToNextStepmethodtopersistourdata.TheAJAXPOSTordernotes/index/processactionshouldgrabtheentireformandpassitsdataalong.

Finally,let'saddthehelpermethodsforour.htmltemplate,asfollows:

getTitle:function(){

returncheckoutConfigOrderNotes.title;

},

getHeader:function(){

returncheckoutConfigOrderNotes.header;

},

getFooter:function(){

returncheckoutConfigOrderNotes.footer;

},

getNotesOptions:function(){

returncheckoutConfigOrderNotes.options;

},

getCheckoutConfigOrderNotesTime:function(){

returncheckoutConfigOrderNotes.time;

},

setOrderNotes:function(valObj,event){

if(valObj.code=='other'){

$('[name="order_notes"]').val('');

}else{

$('[name="order_notes"]').val(valObj.value);

}

returntrue;

},

Thesearejustsomeofthehelpermethodswewillbindtowithinour.htmltemplate.Theymerelypullthedataoutfromthewindow.checkoutConfig.orderNotesobject.

Wethendefinethe<MODULE_DIR>/view/frontend/web/template/order/notes.htmlwithcontent,asfollows:

<liid="order_notes"data-bind="fadeVisible:isVisible">

<divdata-bind="text:getTitle()"data-role="title"></div>

<divid="step-content"data-role="content">

<divdata-bind="text:getHeader()"data-role="header"></div>

<!--form-->

<divdata-bind="text:getFooter()"data-role="footer"></div>

</div>

</li>

Thisisourcomponenttemplate,whichgivesitavisualstructure.Weexpanditfurtherbyreplacingthe<!--form-->withthefollowing:

<formdata-bind="submit:navigateToNextStep"novalidate="novalidate">

<divdata-bind="foreach:getNotesOptions()"class="fieldchoice">

<inputtype="radio"name="order[notes]"class="radio"

data-bind="value:code,click:$parent.setOrderNotes"/>

<labeldata-bind="attr:{'for':code}"class="label">

<spandata-bind="text:value"></span>

</label>

</div>

<textareaname="order_notes"></textarea>

<divclass="actions-toolbar">

<divclass="primary">

<buttondata-role="opc-continue"type="submit"class="buttonactioncontinueprimary">

<span><!--koi18n:'Next'--><!--/ko--></span>

</button>

</div>

</div>

</form>

Theformitselfisrelativelysimple,thoughitrequiressomeknowledgeofKnockout.Understandingthedatabindingisquiteimportant.ItallowsustobindnotjusttextandtheHTMLvaluesofHTMLelements,butotherattributesaswell,suchastheclick.

Wethendefinethe<MODULE_DIR>/etc/webapi_rest/events.xmlwithcontent,asfollows:

<config>

<eventname="sales_model_service_quote_submit_before">

<observername="orderNotesToOrder"

instance="Magelicious\OrderNotes\Observer\SaveOrderNotesToOrder"

shared="false"/>

</event>

</config>

Thesales_model_service_quote_submit_beforeeventischosenbecauseitallowsustogainaccesstobothquoteandorderobjectseasilyattherighttimeintheordercreationprocess.

Wethendefinethe<MODULE_DIR>/Observer/SaveOrderNotesToOrder.phpwithcontent,asfollows:

namespaceMagelicious\OrderNotes\Observer;

classSaveOrderNotesToOrderimplements\Magento\Framework\Event\ObserverInterface

{

publicfunctionexecute(\Magento\Framework\Event\Observer$observer)

{

$event=$observer->getEvent();

if($notes=$event->getQuote()->getOrderNotes()){

$event->getOrder()

->setOrderNotes($notes)

->addStatusHistoryComment('Customernote:'.$notes);

}

return$this;

}

}

Here,wearegrabbingtheinstanceofanorderobjectandsettingtheordernotestothevaluefetchedfromtheordernotesvalueofapreviouslystoredquote.ThismakesthecustomernoteappearundertheCommentsHistorytaboftheMagentoadminorderViewscreen,asfollows:

Withthis,wehavefinalizedourlittlemodule.Eventhoughthemodule'sfunctionalityisquitesimple,thestepsforgettingitupandrunningweresomewhatinvolved.

SummaryInthischapter,wehavebuiltasmall,butfunctional,ordernotesmodule.Thisallowedustofamiliarizeourselveswithanimportantaspectofcustomizingthecheckoutexperience.Thegistofthisliesinunderstandingthecheckout_index_indexlayouthandle,theJavaScriptwindow.checkoutConfigobject,andtheuiComponent.

Failuretodeliverconsistentandstablecheckoutexperiencesisboundtoresultinalossofconversions.Giventhenumberandcomplexityofthecomponentsinvolved,itisbesttokeepthenumberofcheckoutcustomizationstoaminimum.

Movingforward,wearegoingtotakealookatsomeofthethingswecandoregardingthecustomizationofcustomerinteractions.

CustomizingCustomerInteractionsAlongwiththecatalogandcheckout,customer-relatedfunctionalityiscentraltoMagento.Thecustomer'sMyAccountareaallowscontroloveraddresses,orders,billingagreements,productwishlists,productreviews,newslettersubscriptions,andmore.CustomizingcustomerfunctionalityoftenincludeschangestotheSignInandCreateanAccountprocesses,aswellasmodifyingexisting,oraddingnewfunctionalityundertheMyAccountarea.

Dependingonthedynamicsandintricacyofourfunctionality,JScomponentsareoftenfriendliersolutionsthanserver-sidePHTMLtemplates.Theyallowustoengagethecustomerwithoutnecessarilyreloadingentirepages,thusimprovingtheoverallcustomerexperience.Aswithanyclienttoserver-sidecommunication,thequestionofpassingandupdatingthedataremainstobeaddressed.ThisiswhereweturnourfocustoMagento'ssectionmechanism.

Movingforwardwearegoingtotakealookatthefollowing:

UnderstandingthesectionmechanismAddingcontactpreferencestocustomeraccountsAddingcontactpreferencestothecheckout

TechnicalrequirementsYouwillneedtohavebasicknowledgeofPHP,OOP,JavaScript,andXML.YouwillalsoneedApache,MySQL,andAMPPSinstalledonyoursystemtoexecutethecodes.

ThecodefilesofthischaptercanbefoundonGitHub:https://github.com/PacktPublishing/Magento-2-Quick-Start-Guide.

CheckoutthefollowingvideotoseetheCodeinAction:

http://bit.ly/2NQFB1f.

UnderstandingthesectionmechanismOurpreviouschaptertoucheduponconfigprovidersandthewindow.checkoutConfigobject;amechanismbywhichwecanpushourserver-sidedatatoourstorefrontwhenapageloads.ThesectionmechanismallowsustopushdatatoabrowserpageuponanynamedHTTPPOSTrequest.

Let'stakeaquicklookatthe<MAGENTO_DIR>/module-review/etc/frontend/sections.xmlfile:

<actionname="review/product/post">

<sectionname="review"/>

</action>

Thedefinitionprovidedhereistobeinterpretedas:"anystorefrontHTTPPOSTreview/product/postrequestistotriggerareviewsectionload,"wherereviewsectionloadmeansMagentotriggeringanadditionalAJAXrequestfollowingthecompletionofanobservedHTTPPOST.Theresultofthissectionloadaction,inthiscase,istherefreshofsectiondata,retrievableviacustomerData.get('review'),aswewillsoonsee.

Nowlet'stakealookatthe<MAGENTO_DIR>/module-review/etc/frontend/di.xmlfile:

<typename="Magento\Customer\CustomerData\SectionPoolInterface">

<arguments>

<argumentname="sectionSourceMap"xsi:type="array">

<itemname="review"xsi:type="string">Magento\Review\CustomerData\Review</item>

</argument>

</arguments>

</type>

WeareessentiallyinjectingnewitemsunderthesectionSourceMapargumentoftheMagento\Customer\CustomerData\SectionPoolInterfacetype.Theimplementationofacustomsection,suchastheMagento\Review\CustomerData\Review,mustimplementtheMagento\Customer\CustomerData\SectionSourceInterface.TheunderlyinggetSectionDatamethodreturnsanarrayofkey-valuemappings,suchas:

return[

'nickname'=>'',

'title'=>'',

'detail'=>''

]

These,inturn,becomeavailabletotheuiComponent,asobservedinthepartial<MAGENTO_DIR>/module-review/view/frontend/web/js/view/review.jsfile:

define([

'uiComponent',

'Magento_Customer/js/customer-data',

'Magento_Customer/js/view/customer'

],function(Component,customerData){

'usestrict';

returnComponent.extend({

initialize:function(){

this.review=customerData.get('review')...

},

nickname:function(){

returnthis.review().nickname...

}

});

});

ThegetmethodofthecustomerDataobjectcanbeusedtofetchthesectionSourceMapdata,suchascustomerData.get('review').ThisdataisrefreshedeverytimeanHTTPPOSTismadetothereview/product/postroute.ThisisbecausefollowinganyHTTPPOSTreview/product/post,MagentowilltriggeranHTTPGETcustomer/section/load/?sections=review&update_section_id=true&_=1533836467415,whichinturnupdatescustomerDataaccordingly.

AddingcontactpreferencestocustomeraccountsNowthatweunderstandthemechanismbehindthecustomerDataobjectandthesectionload,let'sputittousebycreatingasmallmodulethataddscontactpreferencesfunctionalityunderthecustomer'sMyAccountarea,aswellasunderthecheckout.OurworkistobedoneaspartoftheMagelicious_ContactPreferencesmodule,withthefinalvisualoutcomeasfollows:

Bycontrast,thecustomer'scheckoutareawouldshowcontactpreferences,asfollows:

Theideabehindthemoduleistoprovideacustomerwithanoptionofchoosingpreferredcontactpreferences,sothatamerchantmayfollowupwiththedeliveryprocessaccordingly.

Assumingwehavedefinedregistration.php,composer.json,andetc/module.xmlasbasicmodulefiles,wecandealwiththemorespecificdetailsofourMagelicious_ContactPreferencesmodule.

Westartbydefiningthe<MODULE_DIR>/Setup/InstallData.php,asfollows:

$customerSetup=$this->customerSetupFactory->create(['setup'=>$setup]);

$customerSetup->addAttribute(

\Magento\Customer\Model\Customer::ENTITY,

'contact_preferences',

[

'type'=>'varchar',

'label'=>'ContactPreferences',

'input'=>'multiselect',

'source'=>\Magelicious\ContactPreferences\Model\Entity\Attribute\Source\Contact\Preferences::class,

'required'=>0,

'sort_order'=>99,

'position'=>99,

'system'=>0,

'visible'=>1,

'global'=>\Magento\Catalog\Model\ResourceModel\Eav\Attribute::SCOPE_GLOBAL,

]

);

$contactPreferencesAttr=$customerSetup

->getEavConfig()

->getAttribute(

\Magento\Customer\Model\Customer::ENTITY,

'contact_preferences'

);

$contactPreferencesAttr->setData('used_in_forms',['adminhtml_customer']);

$contactPreferencesAttr->save();

WeareinstructingMagentotocreateamultiselecttypeofattribute.TheattributebecomesvisibleundertheMagentoadminarea,withacustomereditingscreenasfollows:

Wethendefinethe<MODULE_DIR>/Model/Entity/Attribute/Source/Contact/Preferences.php,asfollows:

namespaceMagelicious\ContactPreferences\Model\Entity\Attribute\Source\Contact;

classPreferencesextends\Magento\Eav\Model\Entity\Attribute\Source\AbstractSource

{

constVALUE_EMAIL='email';

constVALUE_PHONE='phone';

constVALUE_POST='post';

constVALUE_SMS='sms';

publicfunctiongetAllOptions()

{

return[

['label'=>__('Email'),'value'=>self::VALUE_EMAIL],

['label'=>__('Phone'),'value'=>self::VALUE_PHONE],

['label'=>__('Post'),'value'=>self::VALUE_POST],

['label'=>__('SMS'),'value'=>self::VALUE_SMS],

];

}

}

Thesearethecontactpreferenceoptionswewanttoprovideasourattributesource.Wewillusethisclassnotjustforinstallation,butlateronaswell.

Wethendefinethe<MODULE_DIR>/etc/frontend/routes.xml,asfollows:

<config>

<routerid="standard">

<routeid="customer"frontName="customer">

<modulename="Magelicious_ContactPreferences"before="Magento_Customer"/>

</route>

</router>

</config>

Unlikeourroutedefinitionsinpreviouschapters,hereweareusinganalreadyexistingroutenamecustomer.TheattributebeforeitallowsustoinsertourmodulebeforetheMagento_Customermodule,allowingustorespondtothesamecustomer/*routes.Weshouldbeverycarefulwiththisapproach,nottodetachsomeoftheexistingcontrolleractions.Inourcase,weareonlydoingthissothatwemightusethecustomer/contact/preferencesURLlateron.

Wethendefinethe<MODULE_DIR>/Controller/Contact/Preferences.php,asfollows:

namespaceMagelicious\ContactPreferences\Controller\Contact;

classPreferencesextends\Magento\Customer\Controller\AbstractAccount

{

publicfunctionexecute()

{

if($this->getRequest()->isPost()){

$resultJson=$this->resultFactory->create(\Magento\Framework\Controller\ResultFactory::TYPE_JSON);

if($this->getRequest()->getParam('load')){

//Merelyfortriggering"contact_preferences"section

}else{

//SAVEPREFERENCES

}

return$resultJson;

}else{

$resultPage=$this->resultFactory->create(\Magento\Framework\Controller\ResultFactory::TYPE_PAGE);

$resultPage->getConfig()->getTitle()->set(__('MyContactPreferences'));

return$resultPage;

}

}

}

Thisistheonlycontrolleractionwewillhave.Wewillusethesameactionforhandlingthreedifferentintents.Thisisnotanidealexampleofhowoneshouldwritecodeinthisscenario,butitisacompactone.Thefirstintentwewillhandleisthesectionloadtrigger,thesecondistheactualpreferencesave,and

thethirdisthepageload.Thesewillbecomeclearaswemoveforward.

WethenreplacetheSAVEPREFERENCEScommentwiththefollowing:

//\Magento\Framework\App\Action\Context$context

//\Magento\Customer\Model\Session$customerSession

//\Magento\Customer\Api\CustomerRepositoryInterface$customerRepository

//\Psr\Log\LoggerInterface$logger

try{

$preferences=implode(',',

array_keys(

array_filter($this->getRequest()->getParams(),function($_checked,$_preference){

returnfilter_var($_checked,FILTER_VALIDATE_BOOLEAN);

},ARRAY_FILTER_USE_BOTH)

)

);

$customer=$this->customerRepository->getById($this->customerSession->getCustomerId());

$customer->setCustomAttribute('contact_preferences',$preferences);

$this->customerRepository->save($customer);

$this->messageManager->addSuccessMessage(__('Successfullysavedcontactpreferences.'));

}catch(\Exception$e){

$this->logger->critical($e);

$this->messageManager->addErrorMessage(__('Errorsavingcontactpreferences.'));

}

Herewearehandlingtheactualsavingofthechosencontactpreferences.Therequestparametersareexpectedtobeinthe<preference_name>=<true|false>format.Weusetheimplodetoturntheincomingrequestandpassitontotherepository'ssetCustomAttributemethod.Thisisbecause,bydefault,Magentostoresthemultiselectattributeasacomma-separatedstringinthedatabase.TheaddSuccessMessageandaddErrorMessagecallsareinterestinghere.OnemightexpectthatwewouldreturnthesemessagesaspartofaJSONresponse.But,wedon'treallyneedaJSONresponsebodyhere.ThisisbecauseMagentohasthemessagessectiondefinedunder<MAGENTO_DIR>/module-theme/etc/frontend/sections.xmlas<actionname="*">.Whatthismeansisthatmessagesgetrefresheduponeverysectionloadand,sinceourcontrolleractionismappedinourownsections.xml,theloadofoursectionwillalsoloadmessages.

Wethendefinethe<MODULE_DIR>/view/frontend/layout/customer_account.xml,asfollows:

<page>

<body>

<referenceBlockname="customer_account_navigation">

<blockclass="Magento\Customer\Block\Account\SortLinkInterface"name="customer-account-navigation-contact-preferences-link">

<arguments>

<argumentname="path"xsi:type="string">customer/contact/preferences</argument>

<argumentname="label"xsi:type="string"translate="true">MyContactPreferences</argument>

<argumentname="sortOrder"xsi:type="number">230</argument>

</arguments>

</block>

</referenceBlock>

</body>

</page>

Thedefinitionshereinjectanewmenuitemunderthecustomer'sMyAccountscreen.Thecustomer_account_navigationblock,originallydefinedunder<MAGENTO_DIR>/module-customer/view/frontend/layout/customer_account.xml,isinchargeofrenderingthesidebarmenu.ByinjectingthenewblockofMagento\Customer\Block\Account\SortLinkInterfacetype,wecaneasilyaddnewmenuitems.

Wethendefinethe<MODULE_DIR>/view/frontend/layout/customer_contact_preferences.xml,asfollows:

<page>

<updatehandle="customer_account"/>

<body>

<referenceContainername="content">

<blockname="contact_preferences"

template="Magelicious_ContactPreferences::customer/contact/preferences.phtml"cacheable="false"/>

</referenceContainer>

</body>

</page>

Thisistheblockthatwillgetloadedintothecontentareaofapage,onceweclickonournewlyaddedMyContactPreferenceslink.Sincetheonlyroleofthecontact_preferencesblockwillbetoloadtheJScomponent,weomittheclassdefinitionthatwewouldnormallyhaveoncustomblocks.

Wethendefinethe<MODULE_DIR>/view/frontend/templates/customer/contact/preferences.phtml,asfollows:

<divclass="contact-preferences"data-bind="scope:'contact-preferences-scope'">

<!--kotemplate:getTemplate()--><!--/ko-->

</div>

<scripttype="text/x-magento-init">

{

".contact-preferences":{

"Magento_Ui/js/core/app":{

"components":{

"contact-preferences-scope":{

"component":"contactPreferences"

}

}

}

}

}

</script>

TheonlypurposeofthetemplatehereistoloadtheJScontactPreferencescomponent.Wecanseethatnodataispassedfromtheserver-side.phtmltemplatetotheJScomponent.WewillusethesectionandcustomerDatamechanismslateronforthat.

Wethendefinethe<MODULE_DIR>/view/frontend/requirejs-config.js,asfollows:

varconfig={

map:{

'*':{

contactPreferences:'Magelicious_ContactPreferences/js/view/contact-preferences'

}

}

};

Herewemapthecomponentname,contactPreferences,toitsphysicallocationinourmoduledirectory.

Wethendefinethe<MODULE_DIR>/view/frontend/web/js/view/contact-preferences.js,asfollows:

define([

'uiComponent',

'jquery',

'mage/url',

'Magento_Customer/js/customer-data'

],function(Component,$,url,customerData){

'usestrict';

letcontactPreferences=customerData.get('contact_preferences');

returnComponent.extend({

defaults:{

template:'Magelicious_ContactPreferences/contact-preferences'

},

initialize:function(){/*...*/},

isCustomerLoggedIn:function(){

returncontactPreferences().isCustomerLoggedIn;

},

getSelectOptions:function(){

returncontactPreferences().selectOptions;

},

saveContactPreferences:function(){/*...*/}

});

});

ThisisourJScomponent,thecoreofourclient-sidefunctionality.WeinjecttheMagento_Customer/js/customer-datacomponentasacustomerDataobject.ThisgivesusaccesstodatawearepushingfromtheserversideviathegetSectionDatamethodoftheMagelicious\ContactPreferences\CustomerData\Preferencesclass.Thestringvaluecontact_preferencespassedtothegetmethodofthecustomerDataobjectmustmatchtheitemnameunderthesectionSourceMapofourdi.xmldefinition.

Let'sextendtheinitializefunctionfurther,asfollows:

initialize:function(){

this._super();

$.ajax({

type:'POST',

url:url.build('customer/contact/preferences'),

data:{'load':true},

showLoader:true

});

}

TheadditionofanAJAXrequestcallwithinthecomponent'sinitializemethodismoreofatricktotriggerthecontact_preferencessectionloadinourcase.WearedoingitsimplybecausesectionsdonotloadonHTTPGETrequests,asthatmightloadthesamecustomer/contact/preferencespage.Rather,theyloadonHTTPPOSTevents.Thiswayweensurethatthecontact_preferencessectionwillloadwhenourcomponentisinitialized,thusprovidingitwiththenecessarydata.WearefarfromsayingthatthisisarecommendedapproachforgeneralJScomponentdevelopment,though.

Let'sextendthesaveContactPreferencesfunctionfurther,asfollows:

saveContactPreferences:function(){

letpreferences={};

$('.contact_preference').children(':checkbox').each(function(){

preferences[$(this).attr('name')]=$(this).attr('checked')?true:false;

});

$.ajax({

type:'POST',

url:url.build('customer/contact/preferences'),

data:preferences,

showLoader:true,

complete:function(response){

//someactions...

}

});

returntrue;

}

ThesaveContactPreferencesmethodwillbetriggeredeverytimeacustomerclicksonthecontactpreferenceonthestorefront,whetheritisanactofcheckingoruncheckingindividualcontactpreferences.

Wethendefinethe<MODULE_DIR>/view/frontend/web/template/contact-preferences.html,asfollows:

<divdata-bind="if:isCustomerLoggedIn()">

<divdata-role="title"data-bind="i18n:'ContactPreferences'"></div>

<divdata-role="content">

<divclass="contact_preference"repeat="foreach:getSelectOptions(),item:'$option'">

<inputtype="checkbox"

click="saveContactPreferences"

ko-checked="$option().checked"

attr="name:$option().value"/>

<labeltext="$option().label"attr="for:$option().value"/>

</div>

</div>

</div>

TheHTMLdefinedherevisuallysetsourcomponent.AbasicknowledgeofKnockoutJSisrequiredinordertoutilizetherepeatdirective,fedwiththearrayofdatacomingfromthegetSelectOptionsmethod,whichbynowweknoworiginatesfromtheserverside.

Wethendefinethe<MODULE_DIR>/etc/frontend/sections.xml,asfollows:

<config>

<actionname="customer/contact/preferences">

<sectionname="contact_preferences"/>

</action>

</config>

Withthis,wemakethenecessarymappingbetweenHTTPPOSTcustomer/contact/preferencesrequestsandthecontact_preferencessectionweexpecttoload.

Wethendefinethe<MODULE_DIR>/etc/frontend/di.xml,asfollows:

<config>

<typename="Magento\Customer\CustomerData\SectionPoolInterface">

<arguments>

<argumentname="sectionSourceMap"xsi:type="array">

<itemname="contact_preferences"xsi:type="string">Magelicious\ContactPreferences\CustomerData\Preferences</item>

</argument>

</arguments>

</type>

</config>

Hereweinjectourcontact_preferencessection,instructingMagentowheretoreaditsdatafrom.Withthisinplace,anyHTTPPOSTcustomer/contact/preferencesrequestisexpectedtotriggerafollow-upAJAXPOSTcustomer/section/load/?sections=contact_preferences%2Cmessages&update_section_id=true&_=1533887023603requestthat,inturn,returnsdatamuchlikethefollowing:

{

"contact_preferences":{

"selectOptions":[

{

"label":"Email",

"value":"email",

"checked":true

},

{...}

],

"isCustomerLoggedIn":true,

"data_id":1533875246

},

"messages":{

"messages":[

{

"type":"success",

"text":"Successfullysavedcontactpreferences."

}

],

"data_id":1533875246

}

}

Ifweweretoenableourmoduleatthispoint,weshouldbeabletoseeitworkingunderthecustomer'sMyAccountscreen.Thoughsimple,thestepsofgettingeverythinglinkedweresomewhatinvolved.Thebenefitofthisapproach,wheredataissentviathesectionsmechanism,isthatourcomponentplaysnicelywithfull-pagecaching.Theneededcustomer-relateddataissimplyfetchedbyadditionalAJAXcalls,insteadofcachingitonaper-customerbasis,andthusthisbypassesthepurposeoffull-pagecaching.

AddingcontactpreferencestothecheckoutWithourcomponentnowworkingonthecustomer'sMyAccountpage,let'sgoaheadandaddittothecheckout'sReview&Paymentsstepaswell.

Bytappingintothecheckout_index_indexlayouthandle,andnestingourcomponentunderthedesiredchildrenelement,wecaneasilyaddittothecheckoutpage.Wedosowiththe<MODULE_DIR>/view/frontend/layout/checkout_index_index.xmlfile,asfollows:

<page>

<body>

<referenceBlockname="checkout.root">

<arguments>

<argumentname="jsLayout"xsi:type="array">

<itemname="components"xsi:type="array">

<itemname="checkout"xsi:type="array">

<itemname="children"xsi:type="array">

<itemname="steps"xsi:type="array">

<itemname="children"xsi:type="array">

<itemname="billing-step"xsi:type="array">

<itemname="children"xsi:type="array">

<itemname="payment"xsi:type="array">

<itemname="children"xsi:type="array">

<itemname="afterMethods"xsi:type="array">

<itemname="children"xsi:type="array">

<itemname="contact-preferences"xsi:type="array">

<itemname="component"xsi:type="string">Magelicious_ContactPreferences/js/view/contact-preferences</item>

<!--closingtags-->

Thenestingstructureofcheckout_index_index.xmlisquiterobust.Thereareseveralplaceswherewecanactuallyinsertourowncomponent.Mostofthetime,thismightbetrialanderror.Inthiscase,weoptedforthechildrenareaofafterMethods.Thisshouldpositionitunderthecheckout'sReview&Paymentsstep,rightafterthepaymentsmethodlist.

SummaryInthischapter,wehavebuiltasmallmodulethatallowedustogetagreaterinsightintoMagento'scustomerDataandsectionsmechanisms.Wemanagedtobuildasinglecomponent,thatgotusedbothonthecustomer'sMyAccountpage,aswellasonthecheckout.

Withthis,wehavereachedtheendofourbook.ThetopicswehavecoveredshouldbeenoughtogetusgoingwithMagentodevelopment,butthesheersizeoftheplatformandtheintricatespecificsofitsindividualmodulesleaveplentymoretoexplorefurtheron.Itgoeswithoutsayingthatourjourneyhasmerelybegun.

OtherBooksYouMayEnjoyIfyouenjoyedthisbook,youmaybeinterestedintheseotherbooksbyPackt:

Magento2BeginnersGuideGabrielGuarino

ISBN:9781785880766

BuildyourfirstwebstoreinMagento2MigrateyourdevelopmentenvironmenttoalivestoreConfigureyourMagento2webstoretherightway,sothatyourtaxesarehandledproperlyCreatepageswitharbitrarycontentCreateandmanagecustomercontactsandaccountsProtectMagentoinstanceadminfromunexpectedintrusionsSetupnewsletterandtransactionalemailssothatcommunicationfromyourwebsitecorrespondstothewebsite'slookandfeelMakethestorelookgoodintermsofPCIcompliance

Magento2Developer'sGuide

BrankoAjzele

ISBN:9781785886584

SetupthedevelopmentandproductionenvironmentofMagento2UnderstandthenewmajorconceptsandconventionsusedinMagento2Buildaminiatureyetfully-functionalmodulefromscratchtomanageyoure-commerceplatformefficientlyWritemodelsandcollectionstomanageandsearchyourentitydataDiveintobackenddevelopmentsuchascreatingevents,observers,cronjobs,logging,profiling,andmessagingfeaturesGettothecoreoffrontenddevelopmentsuchasblocks,templates,layouts,andthethemesofMagento2Usetoken,session,andOauthtoken-basedauthenticationviavariousflavorsofAPIcalls,aswellascreatingyourownAPIsGettogripswithtestingMagentomodulesandcustomMagentothemes,whichformsanintegralpartofdevelopment

Leaveareview-letotherreadersknowwhatyouthinkPleaseshareyourthoughtsonthisbookwithothersbyleavingareviewonthesitethatyouboughtitfrom.IfyoupurchasedthebookfromAmazon,pleaseleaveusanhonestreviewonthisbook'sAmazonpage.Thisisvitalsothatotherpotentialreaderscanseeanduseyourunbiasedopiniontomakepurchasingdecisions,wecanunderstandwhatourcustomersthinkaboutourproducts,andourauthorscanseeyourfeedbackonthetitlethattheyhaveworkedwithPackttocreate.Itwillonlytakeafewminutesofyourtime,butisvaluabletootherpotentialcustomers,ourauthors,andPackt.Thankyou!