ConfigBox 3.0 for Magento · Each selection in the list gives you additional text fields for...

ShopManagerManual

ConfigBox3.0forMagento

www.rovexo.com

_________________________________________________________________________________________

ConfigBox–ShopManagerManual

ConfigBoxforMagento,Rovexo-Version3.0–Lastupdate:Oktober19,2015 Page2

TableofContents

1 INTRODUCTION..................................................................................................................4

2 INSTALLATION....................................................................................................................5

2.1 HowtocheckifionCubeLoaderisinstalled.........................................................................................................52.1.1 WhattodoifionCubeLoaderisnotinstalled.......................................................................................................................52.1.2 InwhichfoldersdoIneedionCubeloadertobeactive?..................................................................................................5

2.2 Installationprocedure.................................................................................................................................................5

2.3 Stepsafterinstallation.................................................................................................................................................62.3.1 Enablethelanguagesyouwanttouseinthesettings.......................................................................................................62.3.2 ConnectMagentoproductswithConfigBoxproducts.......................................................................................................6

3 CONFIGURATOR..................................................................................................................6

3.1 Basics.................................................................................................................................................................................63.1.1 Languages.............................................................................................................................................................................................63.1.2 Products.................................................................................................................................................................................................73.1.3 ConfiguratorPages............................................................................................................................................................................93.1.4 Elements................................................................................................................................................................................................93.1.5 Optionsandtheirassignmenttoelements...........................................................................................................................10

3.2 CompatibilityRules....................................................................................................................................................12

3.3 Calculations..................................................................................................................................................................133.3.1 CalculationusingMatrices...........................................................................................................................................................133.3.2 CalculationusingCode..................................................................................................................................................................153.3.3 CalculationFormulas.....................................................................................................................................................................16

3.4 One-timePricesandRecurringPrices.................................................................................................................16

3.5 ProductVisualization................................................................................................................................................18

4 ORDERMANAGEMENT......................................................................................................19

5 CUSTOMIZINGCONFIGBOX................................................................................................19

5.1 CustomQuotationPDFs............................................................................................................................................20

5.2 CustomWordingandTranslations.......................................................................................................................205.2.1 Understandingtheconceptoflanguagefiles.......................................................................................................................205.2.2 Workflowtofindandcustomizeaphrase............................................................................................................................21

5.3 CustomBehaviorofElements.................................................................................................................................21

5.4 CustomFields...............................................................................................................................................................22

_________________________________________________________________________________________



5.5 CustomCSSstyling......................................................................................................................................................22

5.6 CustomJavaScript.......................................................................................................................................................23

5.7 CustomTemplates......................................................................................................................................................23

5.8 CustomTemplatesforProducts,PagesandElements...................................................................................25

5.9 CustomRuleConditions...........................................................................................................................................265.9.1 Howtodevelopacustomrulecondition...............................................................................................................................265.9.2 WhatisConditionData?...............................................................................................................................................................28

6 NOTESFORCONFIGBOXUPGRADES...................................................................................28

7 TROUBLESHOOTING...........................................................................................................28

_________________________________________________________________________________________



1 Introduction

ConfigBoxisamulti-functionalProductConfiguratorintegratedinMagento.

ConfigBoxisaflexiblesystemcapableofconfiguringawidescopeofproductsandservicesandisdesignedforcompaniesseekingawaytopresentcomplexproductswithauser-friendlyandtransparentexperience.

TypesofproductsthatarehandledwithConfigBox(non-exhaustive)

• Carsandcarequipment• Printingproducts• Phonecarriercontracts• Blindsandshades• Computersystems• Furniture• Promotionequipment• Analyticalinstruments• Poolroofing• Boats• Homeappliances

Support

RovexoandanetworkofSolutionPartnersprovidesupportforthesetupoftheapplicationanddevelopmentofextensions,customizationandindividualgraphicdesign.

Shopadministrationanddataentry

Productdataentryisimplementedforquicklearning,user-friendlinessandintuitivehandling.Thisenablesstaffwithminimaltechnicalbackgroundknowledgetomanagetheapplication.

_________________________________________________________________________________________



2 Installation

ThissectioncoverstheinstallationofConfigBox.ForthisyouunziptheinstallationfileyoureceivedanduploadthecontentstoyourMagentomaindirectory.

IMPORTANTNOTE:PLEASEMAKESURETHATTHEPHPEXTENSIONIONCUBELOADERISINSTALLEDONYOURSERVERBEFOREYOUINSTALLCONFIGBOX.

2.1 HowtocheckifionCubeLoaderisinstalled

YouaskyourhostingprovideraboutionCubePHPloader.

Ifyouseetheline‘withtheionCubePHPLoader[…]’,yourwebserverhasionCubeloaderinstalled.

2.1.1 WhattodoifionCubeLoaderisnotinstalled

PleaserefertoyourhostingproviderinordertogetionCubeLoaderinstalled.

2.1.2 InwhichfoldersdoIneedionCubeloadertobeactive?

Inmostserversetups,ionCubeLoaderisactiveforanyfolderonyourwebspace,butinsomeyouneedtoenableitforspecificfolders(usuallybyplacingaphp.inifilewithloadinginstructionsintherespectivefolders).Ifso,enableionCubeLoaderforthesefolders:

/(Magentobasefolder)/app/code/local/andallsubfolders

2.2 Installationprocedure

BeforeyouinstallorupgradeConfigBoxyoumustcreateabackupofyourwebsitetopreventdatalossordowntimesofyourstore.Thisisasafetymeasureincaseofaninterruptedupgradeprocess.

1. YoucheckyourdownloadedzipfilefromRovexo2. Youunzipthefile3. Youshouldhaveafolderwithsubfolderslike‘app’,‘js’,‘media’andsoon4. UploadthesefoldersintoyourMagentomaindirectory(youshouldseethesefoldersandmorein

thatdirectory)5. RefreshallMagentocaches.Whenindoubt,alsodeletethecachefolderin/var/cache6. Gototheadminarea.Youshouldseeamenuitemcalled‘ConfigBox’there.

_________________________________________________________________________________________



2.3 Stepsafterinstallation

2.3.1 Enablethelanguagesyouwanttouseinthesettings

AtConfigBox->Settings->Languageyouselectthelanguagesyouwanttouse.Eachselectioninthelistgivesyouadditionaltextfieldsfortranslatableproductdata.See3.1.1Languagesfordetails.

2.3.2 ConnectMagentoproductswithConfigBoxproducts

ConfigBoxproductsaresimplycontainingtheconfigurationfunctionalityforyourMagentoproducts.YousetupanyMagentoproductandoneConfigBoxproduct.See3.1.2‘Products’fordetails.

3 Configurator

3.1 Basics

3.1.1 Languages

Tousemultiplelanguagesintheconfigurator,youneedtohavesetupthelanguagesinMagento.YouthenchoosethelanguagestouseintheconfiguratoratConfigBox->Settings->Languages.

Stepbystep:

_________________________________________________________________________________________



• InstallthelanguagepackintheMagentoconfiguration(SeeMagentodocumentation)• ActivatethelanguageinConfigBox(ConfigBox->Settings->ActiveLanguages).

Important:YouneedtoconfigureMagentotohavealanguageswitchforvisitorsyourself.Thereisdocumentationonthisontheweb.

ConfigBoxhasthetranslationsforsystemtextsinGermanandEnglishbuiltin.Youcanaddtranslationsyourself;youfinddetailedinformationonhowtodoitinthechapter6.2.3‘Addingalanguage’.

3.1.2 Products

Youaddoreditproductsintheproducttreeviewonthelefthandsideoftheadminarea.Youcanexpandeachentryandyouseelinkstoaddproducts,pages,elementsandoptions.

Youcandragpagesandelementstoadjustordering.

3.1.2.1 MagentoProductID

HereyouentertheproductIDofyourMagentoproduct.ThisishowMagentowillloadtherightconfiguratorwhenthevisitornavigatestotheMagentoproduct.YoufindtheIDofanyMagentoproductinCatalog->ManageProducts.

3.1.2.2 ConnectConfigBoxproductswithMagentoproducts

InMagento,youneedtosetupasinglecustomoption.AfterinstallationofConfigBox,thereisanInputTypecalledConfigBoxConfiguration.

1. Youaddonecustomoptionofthistype,2. thenentertheproductIDofyourMagentoproductintheMagentoProductIDfieldofyour

product.

_________________________________________________________________________________________



3.1.2.3 ProductVisualization

Ifyouliketoshowaproductvisualizationinconfiguratorpages,setupthedimensionsofthevisualization.Visualizationimagesofoneproductshouldhavethesamedimensions.

Displayofthevisualizationinconfiguratorpages:

Youhaveablockavailablefordisplayingthevisualization.ThisblockneedstobeinsertedintherightspotforyourMagentotheme.Wecannotmakethisout-of-the-boxasthemeshavenostandardsonpositioningblocks.SeetheConfigBoxlayoutXMLfileinthefrontend.

ImportantNote:Youneedtosetthedimensionsoftheproductvisualizationintheproducteditscreen(sectionProductVisualization).Otherwiseitwillnotbevisible.

3.1.2.4 Selectionoverviewonconfiguratorpages

Theselectionoverviewisthepricemodulethatyoucanshowonconfiguratorpages.Itsummarizestheconfiguration,showspricingandtaxesandcanhavecartandquotationrequestbuttons.

Theoverviewisconfigurable.Youhaveglobalsettingsinthesettingspage,andsettingsspecifictoaproductintheproducteditscreen.

Displayoftheselectionoverviewinconfiguratorpages:

Youhaveablockavailablefordisplayingtheoverview.ThisblockneedstobeinsertedintherightspotforyourMagentotheme.Wecannotmakethisout-of-the-boxasthemeshavenostandardsonpositioningblocks.SeetheConfigBoxlayoutXMLfileinthefrontend.

_________________________________________________________________________________________



3.1.3 ConfiguratorPages

Configurationpagesenableyoutocreateaconfiguratorwithmultiplesteps.Ifyouonlyneedonestep,youjustcreateonepage.

3.1.3.1 VisualizationViewKeyword

InVisualizationViewKeywordyouenterakeyword,thesamefieldispresentattheoptionassignmentandenablesyoutoshowdifferentproductvisualizationsoneachpage.Onlyvisualizationimagesthatmatchthevisualizationviewtextoftheconfiguratorpageareshown.

Ifthefieldisempty,onlythevisualizationimageswithemptyfieldsareshown.InpageslikethecartorPDFquotation,theimageswithanemptyvisualizationviewareused.

3.1.3.2 Othersettings

Ifyouliketoblockthecustomerfromgoingtothenextstepifmandatoryelementshavenoselection,check‘Blockcontinuingifmissingelements’.Yousetelementstobemandatoryattheelementscreenlater.

3.1.4 Elements

Yousetupanelementforeachchoicethecustomershallmakeintheconfigurator.

Ifthecustomershouldmakeachoicefromasetofpredefinedoptions,youassignoptionstotheelement(seebottomoftheeditscreenforreference).

Ifthecustomerissupposedtomakeayes/nochoice,youcanassignasingleoptiontodisplayacheckboxorsimplyhave2optionswithyesandnoasyouseefit.

Otherwiseyoucanletthecustomermakeafreeentry.Youcanchooseabetweenvariouswidgetstomakecustomerentriesmorepractical(seeSettingsforCustomEntriesfordetails)andsetvalidationrulestorestrictentries.

3.1.4.1 Settingsforcustomentries

Thesesettingsonlyapplyifyourelementhasnoassignedoptions.Youcanthenuseawidgetforeasiercustomerentryandsetrestrictionsonwhatcanbeenteredforthiselement.

Ifyouliketoallownumbersonly(e.g.formeasuremententries),set‘Allowintegervaluesonly’andoptionallysetaminimumandmaximumvalueanddefaultvalue.

CalculatedMinimumandMaximumValuesallowyoutomaketherestrictionsdynamic,basedonthecurrentconfiguration.CalculationsaredescribedindetailinthemanualsectionCalculations.

3.1.4.2 Widgetsforcustomentries

Therearemultiplewidgetsthatreplacetheregulartextfieldwithamorepracticalinput,dependingonyouruseoftheelement:

_________________________________________________________________________________________



• Regulartextfieldortextarea• Calendarfordateentries• Sliderfornumberentries• Fileuploadfieldwithfilevalidation• PopupPicker

ThePopupPickerisadvanced–YouenteranHTMLtableandInthecellsyouputinatextinsideaElement,whenthecustomerclicksonthetablecell,thevalueinthewillbeenteredinthetextfield

3.1.4.3 PriceCalculationonElements

Importantnote:Youcannotassignoptionstoanelementwithassignedpricecalculations.

Ifyouneedanelementthatonlycalculatesapricewithoutactingasachoiceforthecustomer,thenyoudisable‘Displayelementinconfigurator’.Theelementwillnotbedisplayedasatypicalchoice,butit’stitleandpricewillbedisplayedinoverviews.

Settingupcalculationmodelsisdescribedinthemanualsection‘Calculations.Thepricemultiplicatorisusedtomultiplytheresultofthepricecalculation.

Usingelementpricecalculationisonlyonewaytocalculatepricing.Youcanalsosetpricecalculationsforeachtheassignedoptionifitismorepracticalforyourapplication.

3.1.5 Optionsandtheirassignmenttoelements

Optionsarethechoicesthatthecustomerhasinanelement.

Anoptioncanbeassignedtomultipleelementsinordertoaccommodatestoreswhereoptionsstandforspecificstockitemsandredundantdataentryshouldbeavoided.

Thereforewhenyouassignanoptiontoanelement,youseeacombinededitformforthedataspecifictothisassignment(leftside)andtheoptionitself(rightside).

_________________________________________________________________________________________



Aboutusingpricecalculationsinoptionassignments

Withoutapricecalculation,thepricesetintheoptionisused.Ifyouassignapricecalculation,theoption´spricewillbeignored.

AboutVisualizationsettingsintheoptionassignment

TheimageyouuploadatVisualization->VisualizationImagewillbeaddedtotheproductvisualizationifthecustomerselectstheoption.Tocontrolthepositioninthevisualizationstack,enteranumberatthefieldVisualizationStackingOrder(highernumbersmaketheimagestackedhigherup).SeesectionProductVisualizationforreference

WithVisualizationViewKeywordyoudefinewhichvisualizationimagesshouldbeshownonaconfiguratorpage.Thisenablesyoutodisplaymultipleviewsintheconfigurator.Thefieldispresentintheconfiguratorpageandtheoptionassignmentdata.Onlyimageswithmatchingkeywordswillbeshowninthevisualization.Inthecart,PDFquotationandorderpagestheimageswithnokeywordareshown.

CompatibilityRules

_________________________________________________________________________________________



Compatibilityrulesenableyoutosetconditionsthathavetobemettoshowtheoption.SeesectionCompatibilityRulesforreference.

3.2 CompatibilityRules

Compatibilityrulesenableyoutosetconditionsforelementsandoptionstobevisibletothecustomer.Thesystemevaluatestheconditionseachtimethecustomermakesaselectionandshows/hidesimmediately.

YousetoreditruleforanelementoroptionbyclickingonthebuttonOpenRuleEditorinRuleintheirrespectiveeditscreens.

YoucanchooseiftheelementsandoptionsshouldbecomehiddenorjustgreyedoutwiththeelementsettingRule->Hideifnotapplying.

Standardoptionscanbeauto-selectedoncetheelementbecomesactiveifyouactivateRule->AutomaticPre-selectionand/orRule->PreselectanyOption.

Youcanchooseifautomaticchanges(becauseofelements/options)needtobeconfirmedbythecustomerwiththesettingRule->Confirmautomaticchanges.

Yousettheconditionsofyourrulewithavisualdraganddropeditor.

Ruleeditor:

_________________________________________________________________________________________



1)Pickanelementonthelowerleftsidetoseeallavailableconditionsregardingit.2)Dragtheconditionyouneeduptotheruleareaontop3)Mostconditionshavesettings.Youcanclickonthetext“is”tochangeittoIsnotorenteravalue4)DragcombinatorslikeANDorORtocombineconditions5)Shift-SelectconditionsintheruleareaandclickPutinBracketstocombinethemasonecondition(inordertoimproveclaritywhenconditionsarecombinedwithamixofORsandANDs).

3.3 Calculations

Withcalculationmodelsyoucanimplementcomplexpricingstructureswithnoneedforprogramming.Dependingonthepricinglogicofyourproductsyouseeifpricematrices,formulas,staticoptionpricesoracombinationofallofthemismostsuitable.

Calculationsarealsousedfordynamicweightcalculationofoptionsandfordynamicvalidationofcustomerentriesinelements.

YoucanaddandsetcalculationforeachelementoroptionassignmentinthesectionCalculationsandyoucandisplayalistofallcalculationswiththelinkCalculationsinthesidemenu.

Therearedifferenttypesofcalculationsthatyoucanuseasyouseefitforyourapplication:

• Matrix• FormulaEditor• Formula

Matricesisaclassicpricetableandusefulforcalculatingapricewhenitdependsonthecombinationoftwocustomerchoicesorentries.

TheFormulaEditorenablesyoutocreateformulaswithcustomerentriescustomfielddataofselectedoptions.Italsoenablesyoutoincorporateresultsofothercalculations.

Formulaisatext-basedtoolthatenablesyoutocreateformulasthattheeditorcannotcreate.Itisatoolthatistoughtolearnandmanage,butmayhelpyoutopushtheenvelopewhenyouneedit.

3.3.1 CalculationusingMatrices

Withacalculationmatrix,youchoose2elementsorcalculationsastheaxisparameters.Thecustomer’sselectionforeachoftheelements(ortheresultofthecalculations)willbeusedtolookupthevaluesinthematrixandreturnedastheresultofthecalculation.

_________________________________________________________________________________________



Typicalworkflow:

• Addacalculation• ChooseMatrixastype• Chooseanelementforcolumnsandoneforrows(orcalculations)• Pickthevaluesforcolumnandrowsinthegreyfields• Enterthedesiredprices• Addrowsorcolumnsifneeded• Savethemodelandassignittotheoptionassignmentorelementofyourchoice

Advancedsettings:

LookupValue:Typicallyyouwon’thaveapriceforeachpossiblecustomerinput,butscaledprices.ForthisyoucanchangethesettingLookupValue.Usenexthigherornextlowertolookuptheappropriatepriceinthetable.

RoundValues:Ifyouliketohavetheuserinputvaluesroundedyoucandoitwiththissetting.Roundto1meansroundtointegers.Roundto10wouldmeanroundingtofull10s(e.g.15->20).

Multiplicator:Youcanprovideafactortomultiplytheresultofthecalculation.Thisisusefultoaddmarginstosupplierpricesorsimilar.

ElementValueMultiplicator:Hereyoucanchooseanelementwhosevalue(thevalueprovidedbythecustomer)multipliestheresultofthecalculation.

CalculatedMultiplicator:Thisisthesameastheothermultiplicator,buttheresultofanothercalculationisused.

Note:Ifyousetuptextfieldelementsmeantfornumbers,makesureyousetupvalidationoftheuserinputattheelementundersection‘Textfieldsettings’.Thismakessurethepricecalculationwon’tbreakwhencustomersenternon-numericvalues.ConfigBoxautomaticallydealswithdecimalsymbolsfromdifferentlanguages.

_________________________________________________________________________________________



3.3.2 CalculationusingCode

Calculationformulasfollowasimilarpatternlikethematrices,buthereyoucanuseaPHPcodewithplaceholdersforcustomerinputandspecifickeywordstoincludemanysettingsfromelementsandoptionsinthecode.

Afteraddinganewcalculationmodel,selectthetype‘Codetotoggle.Youcanaddupto4placeholdersthatwillbeusedintheformulawiththelettersAtoD.Theplaceholdersgetreplacedwiththevalueenteredbythecustomerforthatelement(orzeroifnoinputisthere).

Importantnote:Alwayspadaplaceholderwithaspace(beforeandafter),sothattheformulacanbeparsedproperly.

Exampleformulas:

(A*B)+C

ElementAttribute(95.selectedOption.assignment_custom_1,0)

3.3.2.1 FormulaKeywords

Youcanusekeywordstousevaluesotherthanuserinputforyourformula(e.g.Totalforthepricetotalofthecurrentproduct).Alistofkeywordsisfoundintheon-screennotesattheformulaeditor.

_________________________________________________________________________________________



WiththekeywordElementAttributeyoucanusemetadataofanelementanditsassignedoptions.E.g.useElementAttribute(10.selectionPrice)togetthecurrentpricefortheelementwithID10.YoucanlookupelementIDsattheelementlistscreenorattheplaceholderdropdowns.

YoucanalsoenterPHPcodetomakemorecomplexcalculationshere.AlsothereisanelementclassAPIthatletsyouwriteyourownelementPHPclassesthatoverridethebuilt-inpriceenginetomakeevenmoresophisticatedpricecalculation.Seechapter‘CustomizingConfigBoxandOrderManagement’formoreinfo.

3.3.3 CalculationFormulas

Settingupaformulasworkssimilartotheruleeditor.

Youhaveoperators,numbers,elementvalues,calculationsandassortedfunctionstodragintothecalculationarea.Theentriesinthetextfieldsafteror(e.g.EntryinHeightor..)arefall-backvaluesthatareusedifnoentrywasprovided.Makesureyouusethefall-backwheneveradivisionbyzerocouldoccur.

3.4 One-timePricesandRecurringPrices

ConfigBoxsupportstwosetsofpricesenablingyoutoofferproductsthathaveaone-timefeeandarecurringfee(oreitheroneofthem).Thisenablesyoutoofferproductsthatforinstancehaveamonthlypriceandasetupprice.

Typicalusecases

• Rentaloffers• Webhostingproducts• Phonecontracts

_________________________________________________________________________________________



Settingsforone-timepricingandrecurringpricing

Youcanlabeleachpricetypeindividuallyonaper-productbasisanddefineanintervalfortherecurringpayments.

Configuratorpagedisplayexample

_________________________________________________________________________________________



Selectionoverviewusingone-timeandrecurringpricesandsettings

YoucanconfiguretheselectionoverviewforeachproductindividuallyandsetglobaldefaultsintheConfigBoxconfiguration.

Cartpageshowingone-timeandrecurringprices

3.5 ProductVisualization

ConfigBoxenablesyoutopresentyourproductvisuallyandhaverealtimeupdatesofthevisualizationduringacustomer’sconfiguration.Insteadofprovidingimagesforeachcombinationoftheproduct,you

_________________________________________________________________________________________



canuploadouttakesofthepartswithtransparentbackground,ConfigBoxstacksthoseimagestoproducetheproductvisualization.

Displayofthevisualizationinconfiguratorpages:

Youhaveablockavailablefordisplayingthevisualization.ThisblockneedstobeinsertedintherightspotforyourMagentotheme.Wecannotmakethisout-of-the-boxasthemeshavenostandardsonpositioningblocks.SeetheConfigBoxlayoutXMLfileinthefrontend.

ImportantNote:Youneedtosetthedimensionsoftheproductvisualizationintheproducteditscreen(sectionProductVisualization).Otherwiseitwillnotbevisible.

Addinganimagetothevisualization

YouuploadimagesattheoptionassignmentthatrepresentsthepartinthefieldVisualizationImage(seemanualsectionElements).WithVisualizationStackingOrderyoudefinethepositionoftheimageinthestack.

4 OrderManagement

AllprocessingexceptconfigurationisbyMagento.RefertoMagentodocumentationfordetails.

5 CustomizingConfigBox

CustomizationofConfigBoxisstraightforward,wellorganized,requiresnomodificationofthebasesoftwareandenablesyoutomakeprofoundextensionsandmodificationstofunctionalityofthesoftware:

• Designofproductsandconfigurators• Individualconfiguratordesignsforeachproduct

_________________________________________________________________________________________



• Outputofcustom,non-standardproductdata• Modificationandextensionofthebasefunctionality• Customizationofwordingusedintheapplication• Translationinnon-bundledlanguages• Integrationwiththirdpartysoftware

Important:

Anycustomizationyoumakeordelegateneedstobecheckedforcompatibilityonsoftwareupdatesandrevisedifnecessary.Onminorsoftwareupdateswemakeanefforttominimizebreakingchangesandifneedbeprovidedetailedinformationaboutthemonourwebsite(onthedownloadpageforeachversion).

Formajorsoftwareupdates(e.g.2.6to2.7)youneedtobepreparedforacompleterewriteasworst-casescenario.

5.1 CustomQuotationPDFs

QuotePDFsareaConfigBoxforJoomlafeature.ChecktheMagentomarketplaceforsuitablesolutions.

5.2 CustomWordingandTranslations

Customizingwordingisrathereasy.Youneedtocomepreparedwithknowledgeoneditingfilesonyourwebserverandoneditingplaintextfileswithaspecificencoding(UTF-8).Thelatterisexplainedlaterinthissection.

5.2.1 Understandingtheconceptoflanguagefiles

HowwordingandtranslationishandledinConfigBox

TextsyouseeonthepageshandledbyConfigBoxarecustomizable.Toaccomplishthis,thesoftwareusesplaintextfilescalledsystemlanguagefilestofindandoutputtherightphraseintherightlanguage.

Ontopofsystemlanguagefiles,thesystemlooksforcustomlanguagefilesthatyoucanusetocustomizespecificphrases.

ThesefilescanalsobeusedtoaddanewtranslationofConfigBoxortotranslatetextsthatyouhaveincustomtemplates.

Howdoesalanguagefilelooklike?

Atypicallineinalanguagefilelookslikethis:

CONTINUE="Weiter"

Ontheleftinuppercaseyouseethekeywordofthephrasethesystemlooksfor.Ontherightwithindoublequotesyouseethephrasethatthesystemwilldisplay.TypicallythekeywordistheuppercaseformofthephraseinEnglishbutitmaybedifferentfortechnicalreasons.

Locationsofsystemlanguagefiles

/app/code/local/Elovaris/Configbox/application/components/com_configbox/language/frontend.ini/app/code/local/Elovaris/Configbox/application/components/com_configbox/language/backend.ini

Locationsofcustomlanguagefiles

_________________________________________________________________________________________



/media/elovaris/configbox/customization/language_overrides/en-GB/frontend.ini

/media/elovaris/configbox/customization/language_overrides/en-GB/backend.ini

HowtofigureoutwhichlanguagefilecontainsthephraseIsearchfor?

Thefilesareseparatedbetweenthefrontend(akayourstore)andthebackend(akatheadministrationpanel).Inthebackend,bothfilesareloaded,soyousearchfortheEnglishtranslationinthefrontendfirst,theninthebackend.Therearenoduplicatesinthese.

WhicheditorshouldIusetoeditcustomlanguagefiles?

FilesneedtobesavedasplaintextwithUTF-8encoding(noBOM)andonlyuseregulardoublequotes(likethis:")forwrappingphrases.

Ifyouarenotsurewhatthatmeans,takethesaferouteanduseoneoftheseeditorswithdefaultsettings:

• Windows:Notepad++(www.notepad-plus-plus.org)• MacOSX:TextWrangler(www.barebones.com/products/textwrangler)

5.2.2 Workflowtofindandcustomizeaphrase

• Searchforthephraseinthesystemlanguagefilesoftherightlanguage• Copythelinetothecorrespondingcustomlanguagefileandchangethephrase

Notes:

• Thekeywordmustremainunalteredandmakesuretohaveyourphrasewrappedindoublequotes.• Donotputlinebreaksinyourphrases,ifyouneedone,add\nor • Ifyouneeddoublequotesinyourphrase,writethemas\"• WhenchangingphrasesinEnglish,youmaynotalwaysfindthephraseinthesystemlanguagefiles.

ThatisbecausetheEnglishlanguagefilesonlycontainphrasesifthekeyworddiffersfromthephrase.Inthatcaseyoucanexpectthekeywordtobetheuppercaseformofthephrase.Example:Thephrase“SelectProduct”isdonelikethis:SELECTPRODUCT="Yourownwording"

• Phrasesmaychangeinmajorsoftwareupdateswithoutnotice.Itisuptoyoutocheckandreviseyourcustomizationsifnecessary.

5.3 CustomBehaviorofElements

WorkingwithcustomelementclassesrequiresaseasonedPHPdeveloperandaproperlocaldevelopmentsiteisrecommended.Weofferworkshopstogetyourdevelopmentteamuptospeed.Pleasecontactcustomersupportforpricingandscheduling.

UsingtheelementclassAPIyoucanimplementspecificfunctionalityinyourconfigurator.Forinstance:

• DeterminepricingwithyourownPHPcode;e.g.fetchpricingfromexternaldatasources• Storeconfigurationelementvaluesinothersystems

HowistheelementclassAPIused?

YouaddPHPfileswithclassesthatextendtheoriginalConfigBoxelementclassConfigBoxElement(thesourcecodefileislocatedincomponents/com_configbox/classes/element.php).Themethodsofthatclassreturnpricing,theelement’sHTMLoutputonconfiguratorpages,selectionoverviewblocksandthecartpageandstoreselectionsmadebythecustomer.

_________________________________________________________________________________________



Afteryouaddedaclassfile,youcanselecttheelementclassintheelement’sedit-screen.

TheelementclassfilenameandthePHPclassnamefollowanamingconvention.ThefilesarestoredinConfigBox’datafoldertoavoidoverwritingonupdates.

Filefolderandnamingconvention:

Basefolder:/media/elovaris/configbox/customization/element_classes

Eachelementclasshasasub-folder.InityouputthePHPclassfilewiththesamename.

Exampleforelementclassname‘upload’:

PHPclassname:ConfigboxElementUploadFilesystempath:/media/elovaris/configbox/customization/element_classes/upload/upload.php

Methodsyoucanextend:

getPrice($getNetPrice,$getInBaseCurrency)

Thismethodreturnsthepriceinthebasecurrency,eithergrossornet(dependingonthe2parameters).Themethodmustreturnanumberoftypefloat.Ifparameter1isnotentered,thecurrentsystemdefaulthastobeused(usethevalueofconstantCONFIGBOX_SHOW_NET_PRICES),ifparameter2ismissing,thenfalseisassumed.

getPriceRecurring($getNetPrice,$getInBaseCurrency)

AnaloguetogetPrice(),butusedfortherecurringprice.

loadTemplate()

UsethismethodtooutputyourownHTMLinsteadofthedefaultHTMLoutputoftheelementinconfiguratorpages.TheimplementationofthismethodwritesthefrontendHTMLoutputoftheelementintheconfiguratorintotheoutputbuffer.

5.4 CustomFields

Products,elements,optionsandoptionassignmentshave4to6customfieldsyoucanusetoenteranykindofadditional.Thepurposeofthesefieldsisnotspecific.Typicalusefulapplicationsare:

• Usageinpricecalculations(seeonscreen-helpfordetailedinfo)• Usageincompatibilityrules• Usageincustomtemplatesorelementclassesforoutputorapplyingcustomlogic• Usageinconnectorsforintegrationwiththirdpartysoftware

Forpracticalreasons,youcansetyourownlabelsofthesefieldsinSettings->CustomFields.

5.5 CustomCSSstyling

CustomizingCSSstylingrequiresbasictomoderateHTMLandCSSskills.Customstylingcaneitherbesufficienttoamendstylingoftheshoporbeusedincombinationwithcustomizedtemplates.

ConfigBoxcomeswithastylesheetspecificallymadeforstylingcustomizations.Asallfilesinthecustomizationfolder,itisnotoverwrittenduringsoftwareupdates.

Location:

/media/elovaris/configbox/customization/assets/css/style_overrides.css

_________________________________________________________________________________________



Tips:

Useconventionsforruleselectors

Whenlookingatoneofthestylesheets,youseethatmostCSSselectorsstartwith#com_configbox#view-xor#com_cbcheckout#view-xwithxstandingfortheview’sname.Whilebarelyavoidableanyways,werecommendyouadoptthatconventionforyourcustomizations.Itmakesitimmediatelyclearwhatyouintendtochangeanditavoidsunwantedchangesonotherpagetypes.

5.6 CustomJavaScript

CustomJavaScriptrequiresbasictomoderateHTML/JSskills.CustomJavaScriptcanbeusefulincombinationwithcustomtemplates.

Location:

/media/elovaris/configbox/customization/assets/javascript/extra_functionality.js

Tips:

YouhavejQueryavailable

YoucanusejQuerywithcbjintheglobalscope.MindthatthejQueryversionmaychangewithanysoftwareupdate.

5.7 CustomTemplates

CustomizingtemplatesrequiresmoderatePHPprogrammingskillsandrelatedskillslikeHTML/JS/CSS(plus/minusdependingonthekindofcustomizationyouneed).

ConfigBoxisorganizedinpagetypes(e.g.productlisting,cart,checkout,adminorderpageetc.)andeachpagetypemakesuseofaview(ormultipleviews).Eachviewhasatemplatefile(ormultipleones)responsibleforoutputinthebrowserandthesetemplatefilescanbecustomized.

Important:Aswithanycustomization,customtemplatesmayneedtobecheckedandchangedforcompatibilityonsoftwareupdates.Onthedownloadpageyoufinddetailedinformationonbreakingchangesforeachsoftwareupdate.

NotesifyouarefamiliarwithJoomla’sMVCandtemplateoverridesystem:

OurconceptissimilarandpracticallytransparenttothewayJoomlahandlesviewsandtemplates.ThedifferenceisthatoverridesarenotsearchedforintheJoomlatemplatefolder,butinConfigBox’sdatafolder(locationseelaterinthissection)andthatviewfunctions(likeClass::loadTemplate())arenamedandbehavedifferently.

Understandingtheconceptoftemplatecustomization

In/app/code/local/Elovaris/Configbox/application/components/com_configbox/viewsyoufindsub-foldersforeachviewthatConfigBoxusesfordisplayingpages.Thisiscalledaviewfolder.EachviewfoldercontainsaPHPfilecalledview.html.php(orview.raw.phpinsomecases)thathandlespreparationofthedatathatisusedfordisplayingcontent.

Eachviewfolderalsocontainsasub-foldercalledtmplthatcontainsatemplatefilethatistypicallynameddefault.php.TheHTMLproducedinthistemplatefileiswhatyouaregoingtoseeascontentonyourpage.

_________________________________________________________________________________________



Someviewssplitthecontentintomultipletemplatefileswhenitismorepracticalandusetheoutputofotherviewswithintheirtemplatefileswhenitmakessense.Anexampleofthisisthequotationviewwhereorderrecordinformationandpositiondetailscomefromtheviews‘record’and‘positions’.

Workflowforoverridingatemplatefile

1)Firstyoulocatetheviewforwhichyouwanttomakeacustomization.Takethecartasexample:

/app/code/local/Elovaris/Configbox/application/components/com_configbox/views/cart

Thecartviewusesasingletemplatefile,nameddefault.php(Futurereleasesmayhaveitsplitinmultipletemplatefiles).Downloadorcopythetemplatefile,youtypicallywanttouseitasbaseofyourcustomization.

2)Navigatetothefolderforcustomizedtemplates.Thelocationis:

/media/elovaris/configbox/customization/templates/

3)Inthisfolderyoucreateafolderwiththenameoftheviewyouliketooverride:

/media/elovaris/configbox/customization/templates/cart

4)Inthisfolder,youplacethetemplatefileyouliketooverride.Mindthatyoudonotcreatethesub-foldertmpllikeyouhaveitintheviewfolder.

/media/elovaris/configbox/customization/templates/cart/default.php

5)Youthenmakeyourcustomizationstothatfileasyouseefit.

Tips:

Inviewswithmultipletemplatefiles,youcanchoosewhichonestocustomize

Ifyouoverrideonlycertaintemplatefiles,theotherswillbeloadedfromtheoriginalviewfolder.Thishelpsminimizingyoureffortsincaseofbreakingchangesinsoftwareupdates.

AvoidCSSstyling,addingimagesinplacesotherthanthecustomizationfolder

HavealookatthechapteroncustomCSSstyling.Youalsohaveanimagefolderinyourcustomizationfolder.Thishelpskeepingyourworkwellorganizedandquicktocomprehendforcolleaguesandserviceproviders.

Makeuseofcustomfields

Seesectiononcustomfieldsforreference.Youcanaccessthedataofthesefieldsintheappropriatetemplatesandusethemforoutput,calculationsorotherlogic.Seetiponinvestigatingtemplatedataforthebestwaytoseewherethedataisstored.

Formultilingualsites,checkthechapteroncustomwording

Thesoftwarehasanenginetomaketranslatedtextsstraightforward.Managingtranslatedphrasesisexplainedinthatchapter.Tomakeuseofitforyourownwording,youhaveastaticPHPclassmethodtooutputyourtranslatedphrases.

Example:(Obviously,thiscodesnippetneedstobeplacedwithinPHPtags).

echo KText::_('Your phrase');

Thephraseyouuseheremustmatchthekeywordusedinyourcustomlanguagefile.Sothelineinyourlanguagefilewouldlooklikethis:

_________________________________________________________________________________________



YOUR PHRASE="Your translation of the phrase"

Investigatingdataprovidedinthetemplatefiles

ThereisaveryusefulJoomlaextensionthatletsyououtputthedataofanyvariableinabrowserpopup.ItiscalledJDumpandcanbefoundintheJED:

http://extensions.joomla.org/extensions/miscellaneous/development/1509

Example(ObviouslythevariableusedheremustexistandthecallbeplacedinPHPtags):

dump($this->elements);

Makeuseofthelogfilesfordebugging

ConfigBoxlogserrorsandotherthingsextensively.Thelogfilescanbeusefulincaseyouworkdirectlyonawebserveranddonothaveaccesstotheserver’serrorlog.Logsarelocatedinyourwebsite’slogfolderinasub-foldercalled‘configbox’.

Youmayseeplentyofmessagesinsomeerrorlogfiles.

5.8 CustomTemplatesforProducts,PagesandElements

Thissectionisaboutthetemplateeditorthatisessentiallyagraphicinterfaceforcreatingcustomtemplatefileswithsomeextras.

• Convenientlyaddormodifytemplatefilesintheadminarea• Createtemplatefilesforspecificproducts,configuratorpagesorelements.

Intheeditformsofthecorrespondingtypesyoucanassignthetemplateusingthefield‘Template’.

_________________________________________________________________________________________



Editformfortemplates

Youedittemplatesusingcodecoloringandformattingandyoucanalsoeditthesefilesonthefilesystem.

5.9 CustomRuleConditions

Youcandevelopcustomruleconditions.Developingtheserequiresadeptprogrammingskills.Rovexoprovidesnofreesupportorproblemanalysisforcustomruleconditions.

5.9.1 Howtodevelopacustomrulecondition

Youdeveloparuleconditiontypeandsetupalistofconditionsofthattype.Itissimilartotheexampleconditionsyouseeintheruleeditor.Theseservenoactualpurpose,butillustratehowitisdone.

_________________________________________________________________________________________



YouaddaPHPclassinthefolderforcustomruleconditions.Thefolderisinthecustomizationfolderin

/rule_condition_types/

Youpickanameforyourconditiontype(like‘Example’).ThePHPclassneedstobecalledCustomConditionfollowedbyyourtypename.Sofortype‘Example’yougotCustomConditionExample.Thefilenameiscalledthesame(CustomConditionExample.php).TheclassextendsConfigboxCondition.SoyougotclassCustomConditionExampleextendsConfigboxCondition.

Thereareafewmethodsthatneedtobeimplemented.

• CustomConditionExample::getConditionsPanelHtml()• CustomConditionExample::getConditionHtml($conditionData,$forEditing=true)• CustomConditionExample::getEvaluationResult($conditionData,$selections)

getConditionsPanelHtml()

Eachtypegetsapanelintheruleeditor.ThismethodreturnstheHTMLtouseforit.Itessentiallycontainsalistofconditions(theHTMLofeachconditionhasacertainstructure,youwillseemoreaboutitinthemethodgetConditionHtml().

getConditionHtml($conditionData,$forEditing=true)

Thismethodtakesthecondition’sdataasparameterandreturnstheHTMLforthecondition.YouseeanexampleoftheHTMLinExample’sPHPclass,methodCustomConditionExample::readMe().ThegistofitisthateachconditioniswrappedinaElementwithHTML5dataattributescontainingthecondition’sdata.Intheisahuman-readablenameofthecondition,theoperatortochoosefromandatextfieldforthesetpoint,thevaluethethingyoutestforshouldhave.ThosetextfieldshavetheCSSclass‚input’andadataattributecalled‚data-condition-key’thatholdsthekeyoftheentryintheconditiondata.Duringsaving,thosetextfieldsarestoredlikenormalconditiondata,noneedtohavethemasdatainthewrappingelement.

Whateveryouaddasconditiondatawillstoredwhentheruleisstoredandwillbeavailabletoyouinthefollowingmethod.

SeeCustomConditionExample::readMe()foraline-by-lineexplanationoftheHTMLstructure.

getEvaluationResult($conditionData,$selections)

_________________________________________________________________________________________



Thismethodiscalledwhentheconditionisevaluatedaspartofthewholerule.$conditionDatacontainseverythingthatwassetas$conditionDatainthepreviousmethod.$selectionsholdsanarraywiththecurrentconfigurationthatistested.

Themethodhastoreturntrueorfalse.Themethodshouldbeasfastaspossible.Cachewhereyoucansincethismethodmaybecalledmultipletimeseachtimeacustomermakesaselectionintheconfigurator.

SeeCustomConditionExample::readMe()fortheconcretestructureofbothparameters.

5.9.2 WhatisConditionData?

Conditiondataisanarraythathasallthedatatoevaluatetheconditionduringtheconfiguration(viagetEvaluationResult()).IntheruleeditoreachvalueiswrittenasHTML5dataattributeintheconditionsHTML(ingetConditionHtml()).

ConditiondataintheExampletype:

DataKey DataValue Description

type(required) Example Thenameofyourcondition’stype

name Condition1,Condition2,Condition3 Onlyusedfordisplay

fieldname field_1,field_2,field_3 Arbitraryvaluestouseinevaluatingthecondition

operator == Thedefaultoperatorforevaluatingthecondition

shouldValue (empty)–willbepopulatedbytheuserintheeditor

Thevaluethethingtotestforshouldhavefortheconditiontobemet.

Youcanhaveasmuchconditiondatainyourconditionsasyouneed,thedatawillbeavailabletoyouinthemethodgetEvaluationResult().

6 NotesforConfigBoxupgrades

Pleasecheckthecompatibilitynotesatthedownloadpagesonwww.configbox.atfornotesoncompatibilityoncustomtemplates.

7 Troubleshooting

AlwayscheckifyoureadandfollowedtheinstructionsinthesectionInstallationandthesectionConfigBoxupgrades.

_________________________________________________________________________________________



PricingandProductVisualizationdoesnotupdate

Checklist:

PageCachingisactiveonconfiguratorpages

Remove/disableanypagecachingonconfiguratorpages,sincethepageisdynamicandneedstobeloadedfresheachvisit.

IonCubeLoaderisonlyactiveforcertaindirectories

Solution:SeethechapteronInstallation->IonCubeLoaderonhowtosetupionCubeLoadercorrectly.

Magentomoduleconflicts

Magentomodulescanconflict.Thisscenariobecomesmorelikelyifyouusemoduleswithsimilarpurposes.CommonreasonisthatmultiplemodulestrytooverridethesameMagentocoremodel.

IncaseyouneedtokeepbothconflictingmodulesyoucanconsultaMagentodevelopertofindawaytoresolvetheextensionconflict.Pleasenotethatthismaynotbepossibleorprohibitivelyexpensiveandyoumaybeforcedtofindanalternativeforconflictingmodule.

Pleasenotethatwecannotbeheldliableformoduleconflicts.Resolvingmoduleconflictsisthebuyer’sresponsibility.

Helpfulinformationfordevelopers:YoucanseethemodelrewritesthatConfigBoxdoesinitsconfig.xml.Theamountofrewritesisnotextensiveandthereisagoodchancethatconflictingmodulesoverridethesamemodelbutnotthesamemodelmethods.Seethemodule‘ModulesConflictDetector’forhelponidentifyingconflicts.

ConfigBox 3.0 for Magento · Each selection in the list gives you additional text fields for...

Documents

Transcript of ConfigBox 3.0 for Magento · Each selection in the list gives you additional text fields for...