ConfigBox 3.1 for Joomla and Wordpress...ConfigBox does silent registration and creates a linked Joomla user account. The group information is used to set the correct Joomla user group

ShopManagerManual

ConfigBox3.1forJoomlaandWordpress

www.rovexo.com

__________________________________________________________________________________________

ConfigBox–ShopManagerManual

Version3.1-RovexoLastupdate:March22,2018 Page2

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

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

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

2.2 InstallationonJoomla.............................................................................................................................................52.2.1 Installerpackages.............................................................................................................................................................................52.2.2 ActivationofJoomlaplugins........................................................................................................................................................62.2.3 Customergroupsetup....................................................................................................................................................................62.2.4 Setupofusergrouppermissions...............................................................................................................................................6

2.3 InstallationonWordpress.....................................................................................................................................7

2.4 IntegrationofConfigBoxinJoomla.....................................................................................................................82.4.1 ConfigBoxMenuItemTypes........................................................................................................................................................82.4.2 NativeSEFURLs................................................................................................................................................................................9

2.5 IntegrationofConfigBoxinWordpress.............................................................................................................92.5.1 Showproductlistsandconfiguratorsonyoursitewithshortcodes........................................................................92.5.2 SEFlinkstoconfiguratorpages...............................................................................................................................................102.5.3 SEFlinkstoCartandCustomerAccountpage..................................................................................................................11

3 CONFIGURATOR...........................................................................................................12

3.1 Basics...........................................................................................................................................................................123.1.1 Languages(Joomlaonly)............................................................................................................................................................123.1.2 ProductListings.............................................................................................................................................................................123.1.3 Products.............................................................................................................................................................................................123.1.4 ConfiguratorPages.......................................................................................................................................................................153.1.5 Questions..........................................................................................................................................................................................153.1.6 PredefinedAnswersandtheirassignmenttoquestions..............................................................................................16

3.2 CompatibilityRules................................................................................................................................................16

3.3 Calculations...............................................................................................................................................................173.3.1 CalculationusingMatrices........................................................................................................................................................183.3.2 CalculationusingCode................................................................................................................................................................193.3.3 CalculationsusingtheFormulaEditor.................................................................................................................................20

3.4 One-timePricesandRecurringPrices.............................................................................................................21

3.5 ProductVisualization............................................................................................................................................25

4 ORDERMANAGEMENT.................................................................................................26

4.1 Cartpage.....................................................................................................................................................................264.1.1 Controlwhatacustomercandoonthecartpage...........................................................................................................264.1.2 SettheContinueShoppinglisting..........................................................................................................................................27

4.2 CustomerData..........................................................................................................................................................27

__________________________________________________________________________________________



4.3 CustomerGroups.....................................................................................................................................................284.3.1 Associatedplatformgroup(Joomlaonly)...........................................................................................................................284.3.2 Taxdisplaymode...........................................................................................................................................................................294.3.3 Controldisplayofprices.............................................................................................................................................................294.3.4 Discountlevels................................................................................................................................................................................29

4.4 ShippingManagement...........................................................................................................................................29

4.5 PaymentMethods....................................................................................................................................................304.5.1 Bundledconnectorstoonlinepaymentserviceproviders.........................................................................................30

4.6 EmailNotifications..................................................................................................................................................314.6.1 NotificationSnippets....................................................................................................................................................................32

4.7 Invoices.......................................................................................................................................................................324.7.1 InvoiceSettings..............................................................................................................................................................................32

4.8 GoogleAnalyticsTrackingandReporting......................................................................................................334.8.1 Prerequisites...................................................................................................................................................................................334.8.2 GoogleAnalyticsE-commerceTracking..............................................................................................................................334.8.3 UseofGoogleAnalyticsgoals...................................................................................................................................................34

4.9 Reviews.......................................................................................................................................................................35

4.10 CountriesandShipping.........................................................................................................................................364.10.1 TaxHandlingforCitiesandStates.........................................................................................................................................364.10.2 PredefinedCities............................................................................................................................................................................36

4.11 UsingIPGeolocationtoprefillcustomerdataandotherpurposes.......................................................36

5 CUSTOMIZINGCONFIGBOX..........................................................................................36

5.1 CustomQuotationPDFs........................................................................................................................................37

5.2 CustomWordingandTranslations...................................................................................................................385.2.1 Understandingtheconceptoflanguagefiles....................................................................................................................385.2.2 Workflowtofindandcustomizeaphrase..........................................................................................................................39

5.3 CustomFields...........................................................................................................................................................39

5.4 CustomCSSstyling..................................................................................................................................................40

5.5 CustomJavaScript...................................................................................................................................................40

5.6 CustomTemplates..................................................................................................................................................40

5.7 CustomTemplatesforSpecificListings,Products,PagesandQuestions.............................................43

5.8 CustomConnectors.................................................................................................................................................43

5.9 CustomNotificationsnippets..............................................................................................................................46

5.10 CustomRuleConditions........................................................................................................................................475.10.1 Howtodevelopacustomrulecondition............................................................................................................................475.10.2 WhatisConditionData?.............................................................................................................................................................48

__________________________________________________________________________________________



6 NOTESFORCONFIGBOXUPGRADES.............................................................................49

6.1 UpgradefromConfigBoxversionspriorversion3.1...................................................................................49

7 TROUBLESHOOTING.....................................................................................................49

7.1 PricingandProductVisualizationdoesnotupdate....................................................................................49

7.2 Theinstallationfailedanduninstallationisnotpossible.........................................................................50

7.3 Paymentmethodchangesarenoteffective...................................................................................................50

7.4 IssueswithSH404SEF............................................................................................................................................50

7.5 Anerrormessageoccurredafteruploadingapackage.............................................................................51

8 EXTENSIONS.................................................................................................................51

8.1 VirtueMartConnector............................................................................................................................................51

1 Introduction

ThismanualisforbothJoomlaandWordpress,thedifferencesabouttheintegrationarepointedoutwheretheyoccur.

Support

RovexoandanetworkofSolutionPartnersprovidesupportforthesetupoftheapplicationanddevelopmentofextensions,customizationandindividualgraphicdesign.

Shopadministrationanddataentry

Productdataentryisimplementedforquicklearning,user-friendlinessandintuitivehandling.Thisenablesstaffwithminimaltechnicalbackgroundknowledgetomanagetheapplication.

__________________________________________________________________________________________



2 Installation

2.1 MakesurethationCubeLoaderisinstalled

OnJoomla2.5:Intheadminarea,gotoSite->SystemInformation->PHPInformationOnJoomla3.x:Intheadminarea,gotoSystem->SystemInformation->PHPInformationOnWordpress:WordpressdoesnotshowyouPHPinformation–askyourdevelopmentcompanyorhostingprovider

Inthefirstsectionofthepage,youseeaninformationblocksimilartothisscreenshot(theactuallogoandexacttextdiffersbetweenwebservers):

Ifyouseetheline‘withtheionCubePHPLoader[…]’,yourwebserverhasionCubeloaderinstalled.

2.1.1 WhattodoifionCubeLoaderisnotinstalled

PleaserefertoyourhostingprovidertogetionCubeLoaderinstalled.

2.1.2 InwhichfoldersdoIneedionCubeloadertobeactive?

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

Joomla:

/(Joomlarootfolder)/administrator//components/com_configbox/

Wordpress:

/(Wordpressrootfolder)

/wp-admin(Wordpressbackendfolder)

2.2 InstallationonJoomla

IfyouuseWordpress,skipovertothenextchapterwherewedescribetheinstallationonWordpress.

2.2.1 Installerpackages

BeforeyouinstallorupgradeConfigBoxyoumustcreateabackupofyourwebsitetopreventdatalossordowntimesofyourstore.Thisisasafetymeasureincaseofaninterruptedupgradeprocess.

__________________________________________________________________________________________



ToinstallConfigBox,haveyourinstallationpackagesready,theyconsistofmultiplefilesofthetype.tar.gzor.zip–YoudownloadedConfigBoxasone.zipfile,youneedtounzipitandusethepackagesinthefolder“Installation”or“Upgrade”.

AttheExtensionManager,selectyourfirstpackagewiththefileuploadelementandclickon“Upload&Install”.

Afterinstallationofthepackagecom_configbox.zipyouwillbeaskedtoenteryourlicensekey.YouseeyourlicensekeyinthecustomercenterontheConfigBoxwebsite.

Continueinstallingallthepackages.Ifanyerroroccursduringinstallationcheckthetroubleshootingsection.Ifyoufindnosolution,pleaseconsultyourservicepartnerorRovexo.

2.2.2 ActivationofJoomlaplugins

Pluginsthatyouinstallaredisabledbydefault.EnablethemusingthePluginManageratExtensions.Clickontheredsymbolnexttothenewlyinstalledplugins.

2.2.3 Customergroupsetup

ThisisnotneededforJoomla1.5

GotoSettings->CustomerGroups->DefaultGroupandsetaJoomlausergroupatPlatformGroup(saveonceifalreadyfilledout).

MakesurethatthisgrouphaspermissiontologintothesiteatJoomla->Site->GlobalConfiguration->Permissions.

Whatisthismeantfor?ConfigBoxdoessilentregistrationandcreatesalinkedJoomlauseraccount.ThegroupinformationisusedtosetthecorrectJoomlausergroupforthisuseraccount.

2.2.4 Setupofusergrouppermissions

Joomlagrouppermissionsareusedtoallowordisplaycertaintasksorfeatures.Afterinstallation,yourpublicgrouphasnopermissionsforanyofthesetasks,youneedtosetthesemanually.

__________________________________________________________________________________________



AllowSiteLoginfortheJoomlaguestusergroup

AtSite->GlobalConfiguration->Permissionsyouneedtoallowtheguestusergroup(bydefaultcalled‘Public’tologintothesite.ThisenablesConfigBoxtoautomaticallyloginusersafterarequestforquotationorcustomerdataentry.

AllowSiteLoginforusergroupsassociatedwithcustomergroups

IfyoucreatedmultiplecustomergroupsandassociatedthemtootherJoomlagroups,youneedtosetthesamepermissions.

2.3 InstallationonWordpress

DownloadthepluginzipfileanduploadtoyourWordpresssite’spluginfolder

OntheConfigBoxwebsiteyoudownloadthesoftwareasazipfile.Youunzipitandyoushouldhaveafoldercalled‘configbox’.YoucopythisfoldertothepluginsfolderofyourWordpressinstallation.Bydefault,thisfolderisin/wp-content/plugins.

Intheendthereshouldbeafolder/wp-content/plugins/configboxwithanumberoffilesinit.

ActivatetheConfigBoxplugin

GotoyourWordpressbackend,goto‘Plugins’,find‘ConfigBox’inthelistandclickon‘Activate’.

__________________________________________________________________________________________



ClickonConfigBoxonthesidemenuandgothroughthepostinstallationsteps.

AllowamomentforConfigBoxtoruntheinitialdatabasesetupandthengothroughthepostinstallationwizardwherethesoftwarewillaskyouafewthingsaboutcurrencies,taxesetc.OncedonethewizardwilldirectyoutotheConfigBoxdashboardandyouarereadytosetupyourfirstproduct!

2.4 IntegrationofConfigBoxinJoomla

TodisplayConfigBoxpagesonyourwebsite,youusemenuitemsjustasanyothercomponent.

Goto“Menus–YourMenu”andclick“New”,thenchoosethemenutype.ConfigBoxoffersmultiplemenuitemtypeswithparameters.Themostimportantoneisthetype“ConfigBox–ProductListing”whichwillshowallyourproductsoralistingofcertainproducts(groupedbyproductlistings).

2.4.1 ConfigBoxMenuItemTypes• ConfigBox–ConfiguratorPage

Alinktoaconfiguratorpageofaproduct.• ConfigBox–Cart

LinktotheConfigBoxshoppingcart.

__________________________________________________________________________________________



• ConfigBox–ProductDetailsLinktoadefinedproductdetailspage.

• ConfigBox–ProductListingLinktoapagethatshowsallyourproductsorproductsofacertainlistingifdefined.

• OrderManagement–RefundPolicyPageLinktotheRPasdefinedintheShopDataofConfigBoxOrderManagement.

• OrderManagement–TermsandConditionsLinktotheTOCasdefinedintheShopData.

• OrderManagement–CustomerProfilePage• OrderManagement–EditProfilePage• OrderManagement–LoginForm(youcanalsouseastandardJoomlaloginform)• OrderManagement–RegisterForm(youcanalsouseastandardJoomlaregistrationform)

2.4.2 NativeSEFURLs

ConfigBoxusestheJoomlaframeworktocreateSEFURLs.TheuseofthirdpartytoolstomanipulateURLsisnotsupportedandwerecommenddisablingthemforConfigBoxandOrderManagementpages.

Importantnote:YouneedtoenableSearchEngineFriendlyURLsintheJoomlaGlobalConfigurationtobenefitfromConfigBoxSEFURLs.

HowConfigBoxSEF-URLsarebuilt

ConfigBoxanalysesthemenuitemstructureanddeterminestheoptimalSEF-URLforpages.Ingeneralitusesthemostspecificmenuitem.Whentwoequallyspecificmenuitemsarefound,parentmenuitemsofthecurrentpageareprioritized.Inthefollowingyouseetheorderinwhichpagesarechecked.

Productlistings:

• Menuitemoftype‘ProductListing’withamatchinglistingid• Menuitemoftype‘ProductListing’withnodefinedlistingid

ProductPage:

• Menuitemoftype‘ProductPage’withamatchingproductid• Menuitemoftype‘ProductListing’thatcontainstheproduct(productaliasisappended)• Menuitemoftype‘ProductListing’withnodefinedlistingid(productaliasisappended)

Configuratorpage:

• Menuitemoftype‘ConfiguratorPage’withamatchingpageid• Menuitemoftype‘ConfiguratorPage’withamatchingproductid(pagealiasisappended)• Menuitemoftype‘ProductPage’withamatchingproductid(pagealiasisappended)• Menuitemoftype‘ProductListing’thatcontainstheproduct(productandpagealiasisappended)• Menuitemoftype‘ProductListing’withnodefinedlistingid(productandpagealiasisappended)

2.5 IntegrationofConfigBoxinWordpress

2.5.1 Showproductlistsandconfiguratorsonyoursitewithshortcodes

InConfigBoxyousetupyourproductlistsandproductsandthenmakeregularpostsorpageswithshortcodestoaddalist,aproductordirectlyaconfiguratorpageonyoursite.

Onthetopoftheeditscreenforproductlists,productsorconfiguratorpages,youseetherespectiveshortcode.

__________________________________________________________________________________________



Feelfreetoaddsomeextraattributetohelpyourecognizewhatproductyou’redealingwith.

Forexample:[configboxview="product"id="1"product="Myproduct"]

2.5.2 SEFlinkstoconfiguratorpages

TocontrolhowtheURLstoyourconfiguratorpageslooklike,seethefield‘SEFSegment’in‘Others’onyourproducteditscreenandin‘Display’onyourconfiguratorpageeditscreen.

SEFSegmentfieldinproduct:

SEFsegmentfieldintheconfiguratorpage:

Thesetwofieldmatterwhenyouembedaproductlist.TheURLtotheconfiguratorpageswillbebuiltusingtheproduct’sandconfiguratorpage’sSEFSegment.

__________________________________________________________________________________________



2.5.3 SEFlinkstoCartandCustomerAccountpage

YouchoosetheSEFlinkintheConfigBoxsettings.

BesuretouseaURLsegmentthatisn’tinuseforanyposts/pages.Asofnow,thesystemdoesnotcheckforthat.

__________________________________________________________________________________________



3 Configurator

3.1 Basics

3.1.1 Languages(Joomlaonly)

Joomlaonly:TheWordpresseditioncurrentlyisn’tmultilingual–we’relookingintofindingasolidwaytoworkwiththevariousmulti-languageplugins.Tillwecomeupwithsomethinggood,CBforWordpressissinglelanguage.

Tousemultiplelanguagesintheconfigurator,youneedtohavesetcontentlanguagesinJoomla(SeeExtensions->LanguageManager->TabContent.YouthenchoosethelanguagestouseintheconfiguratoratConfigBox->Settings->Languages.

Stepbystep:

• InstallthelanguagepackintheJoomlalanguagemanager(Extensions->LanguageManager)• Addthecontentlanguageforthislanguage(Extensions->LanguageManager>Content)• ActivatethelanguageinConfigBox(ConfigBox->Settings->ActiveLanguages).

Important:MakesureyouhavesetthelanguagetagcorrectlythefirsttimeintheJoomlalanguagemanager.Changingthelanguagetag(e.g.en-GB,de-DEetc.)laterwillmakealltranslationsinConfigBoxdisappearsincethetagconnectstheJoomlalanguagewiththeConfigBoxlanguage.

ConfigBoxhasthelanguagesGermanandEnglishbuiltin.Youcanaddtranslationsyourself;youfinddetailedinformationonhowtodoitinthechapter6.2.3‘Addingalanguage’.

3.1.2 ProductListings

Productlistingsareusedtodisplayproductstogetheronoverviewpages(likehouseholdgoods,powertoolsoraccessories).Youcanassignproductstolistingsandyoucanassignaproducttomultiplelistings.

Toaddalisting,goto“ConfigBox-ProductListings”andclick“Add”.Setanameandsave.YoucanthenaddamenuitemwiththeJoomlaMenuManagertoshowthelistingonyourwebsite.

3.1.3 Products

Youcansetupproductsthatareconfigurableornon-configurable.Tohaveanon-configurableproduct,additanddonotaddanyconfigurationpagestoit.

Youaddoreditproductsintheproducttreeviewontheleft-handsideoftheadminarea.Youcanexpandeachentryandyouseelinkstoaddproducts,pages,questionsandanswers.

Youcandragpagesandquestionstoadjustordering.

__________________________________________________________________________________________



3.1.3.1 Others->ProductSEFSegment

TheproductSEFsegment(prev.calledalias)isusedforSEFURLs(seesection‘HowConfigBoxgeneratesSEFURLs’)andhastoconsistofcharactersthatarevalidforURLs(ifyouareunsure,usea-z,0-9andminusonly).

3.1.3.2 BasepriceandBasepricerecurring

Atthissectionyoucanassignabasepriceonwhichallextrasduringconfigurationareaddedto.

Whenyouuserecurringpayments,thenwiththepricelabelyoucandecorateyourprice,especiallyusefulifyouusesetupandrecurringcostsinparallel.Withacustompricetext,youcanpresentapricewithyourownwordingandinsertthepricevalueusingtheplaceholder%s.Thisenablesyoutodisplayyourpriceas‘Startingfrom€100’.

3.1.3.3 ProductDescription

Productdescriptionsareshownintheproductlistinganddetailspage.Youhaveseparateproductlistingdescriptionandproductdetailsdescription.Ifyouset‘Useproductdetailsdescriptionastemplate`,allyourenteredHTMLwillbeusedas-isintheproductdetailsgivingyoufullcontroloverthelayout.Youcanthenuseplaceholdersfordynamicfieldslikepriceand‘addtocart’or‘configure’buttons.Seethefield’stooltipfortheplaceholdernames.

3.1.3.4 Productdetailpanes

Withproductdetailpanesyoushowproductdetailssegmentedinatabbedinterface.Youcanchoosetodisplaytheproductdetailsinproductpagesandconfiguratorpages.

__________________________________________________________________________________________



Exampleproductdetailpanes

Theseareexampleproductdetailpanes.Actualfont-sizes,colorsandboxwidthsmayvaryandmaybeinfluencedbythewebsite´sstyling.

Listingofproductdetailpanesinproductdataentryform

Importantnote:Ifyoujustaddedanewproduct,saveoncebeforeyouaddproductdetailpanes.

Youcanenterheading,anoptionalicon,CSSclassesandHTMLcontent.CSSclassesenablewebdesignerstosetspecificstylingforheadingsandpanecontents.

Customizationofproductdetailslocation

Tochangetheareawhereproductdetailsaredisplayed,create/edityourcustomproductorconfiguratorpagetemplateandadd/movethissnippet:

<?php if ($this->showProductDetailPanes) { ?> <div class="product-detail-panes-wrapper"><?php echo $this->productDetailPanes; ?></div> <?php } ?>

__________________________________________________________________________________________



3.1.3.5 ProductVisualization

Ifyouliketoshowaproductvisualizationinconfiguratorpages,thecart,thePDF-quotationandorderconfirmation,setupthedimensionsofthevisualization.Visualizationimagesofoneproductshouldhavethesamedimensions.

3.1.3.6 Selectionoverviewonconfiguratorpages

Theselectionoverviewisthepricemodulethatyoucanshowonconfiguratorpages.Itsummarizestheconfiguration,showspricingandtaxesandcanhavecartandquotationrequestbuttons.

Theoverviewisconfigurable.Youhaveglobalsettingsinthesettingspage,andsettingsspecifictoaproductintheproducteditscreen.

3.1.4 ConfiguratorPages

Note:Configuratorpageswerecalled‘Categories’inpreviousversionsofConfigBox.

Configurationpagesenableyoutocreateaconfiguratorwithmultiplesteps.Ifyouonlyneedonestep,youjustcreateonepage.

3.1.5 Questions

Yousetupaquestionforeachchoicethecustomershallmakeintheconfigurator.Youcanchooseifthecustomerneedstoanswerandsetrulesforeachquestionandanswerstocontrolwhatquestionsthecustomerwillseeandwhichanswerswillbeavailabletohim.

__________________________________________________________________________________________



3.1.6 PredefinedAnswersandtheirassignmenttoquestions

Typicallyyouassignanswersthatarespecifictoaquestion.Butincaseyouhavealargercatalogueandsomeanswersrepeatthemselvesyoucanreuseanswersacrossquestionsandacrossproducts.

Mindthedropdownonthetopleftat‘Answer’.Whenyouaddananswertoaquestionyoucanherepickanexistinganswerandwhenyoudo,alldataontheleft-handsideoftheformwillbesharedacrossthecatalogue.Achangeinoneoftheseanswerswillbereflectedinallofthem.

Aboutusingpricecalculationsinanswers

Withoutapricecalculation,thestaticprice(seefieldintheleft-handside)isused.Ifyouassignapricecalculation,thatstaticpricewillbeignoredandthecalculationresultwillbeusedinstead.

AboutVisualization

Mindthatyoudon’tseevisualizationsettingsintheanswersifyouhaven’tenabledVisualizationinyourproduct.

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

Rules

Compatibilityrulesenableyoutosetconditionsthatmustbemettoshowtheanswer.SeesectionCompatibilityRulesforreference.

3.2 CompatibilityRules

Compatibilityrulesenableyoutosetconditionsinquestionsandanswersthatmustbefulfilledbeforethequestion/answerbecomesvisibletothecustomer.Thesystemevaluatestheconditionseachtimethecustomeranswersaquestionorchangesananswer.

Yousetoreditaruleineachquestionandanswereditscreenandchoosebehaviorforvarioussituations.Forquestionsandanswersyouchooseifthequestion(oranswer)shallbehiddenorgreyedoutwhilenotapplying.

__________________________________________________________________________________________



Inthequestioneditscreenyoucanchoosewhatshallhappenwhenthecustomer’scurrentselectionbecomesimpossible(deselect,findalternative,alertthecustomerornot).

Yousettheconditionsofyourrulewithavisualdraganddropeditor.

Ruleeditor:

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

3.3 Calculations

Withcalculationsyoucanimplementcomplexpricingstructureswithnoneedforprogramming.Dependingonthepricinglogicofyourproductsyouseeifpricematrices,formulas,staticanswerpricesoracombinationofallofthemismostsuitable.

Calculationsarealsousedfordynamicweightcalculationofanswersandfordynamicvalidationofcustomerentriesinquestions.

YoucanaddandsetcalculationforeachquestionoranswerinthesectionCalculationsandyoucandisplayalistofallcalculationswiththelinkCalculationsinthesidemenu.

Therearedifferenttypesofcalculationsthatyoucanuseasyouseefitforyourapplication:

• Matrix• Formula

__________________________________________________________________________________________



• Code

Matrixisaclassicpricetableandusefulforcalculatingapricethatdependsonthecombinationoftwocustomerchoices.

TheFormulaenablesyoutocreateformulaswithcustomerentriescustomfielddataofselectedanswers.Italsoenablesyoutoincorporateresultsofothercalculations.

Codeisatext-basedtoolthatenablesyoutocreateformulasthattheeditorcannotcreate.Itisatoolthatistoughtolearnandmanage,butmayhelpyoutopushtheenvelopewhenyouneedit.

3.3.1 CalculationusingMatrices

Withacalculationmatrix,youchoose2questionsorcalculationsastheaxisparameters.Thecustomer’sselectionforeachofthequestions(ortheresultofthecalculations)willbeusedtolookupthevaluesinthematrixandreturnedastheresultofthecalculation.

Typicalworkflow:

• Addacalculation• ChooseMatrixastype• Chooseaquestionforcolumnsandaquestionforrows(orcalculations)• Pickthevaluesforcolumnandrowsinthegreyfields• Enterthedesiredprices

__________________________________________________________________________________________



• Addrowsorcolumnsifneeded• Savethemodelandassignittotheanswerorquestionofyourchoice

Advancedsettings:

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

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

Multiplier:Youcanprovideafactortomultiplytheresultofthecalculation.Thisisusefultoaddmarginstosupplierpricesorsimilar.

QuestionValueMultiplier:Hereyoucanchooseanquestionwhosevalue(thevalueprovidedbythecustomer)multipliestheresultofthecalculation.

CalculatedMultiplier:Thisisthesameastheothermultiplier,buttheresultofanothercalculationisused.

Note:Besuretosetvalidationonthequestionsyouuseincalculations.ConfigBoxautomaticallydealswithdecimalsymbolsfromdifferentlanguages.

3.3.2 CalculationusingCode

Calculationformulasfollowasimilarpatternlikethecalculationtables,buthereyoucanuseamathematicalformulawithplaceholdersforcustomerinputandspecifickeywordstoincludemanysettingsfromquestionsandanswersintheformula.

__________________________________________________________________________________________



Afteraddinganewcalculation,selectthetype‘Codetotoggle.Youcanaddupto4placeholdersthatwillbeusedintheformulawiththelettersAtoD.Theplaceholdersgetreplacedwiththevalueenteredbythecustomerforthatquestion(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.

WiththekeywordElementAttributeyoucanusemetadataofanquestionanditsassignedaswers.E.g.useElementAttribute(10.selectionPrice)togetthecurrentpriceforthequestionwithID10.YoucanlookupquestionIDsatthequestionlistscreenorattheplaceholderdropdowns.

YoucanalsoenterPHPcodetomakemorecomplexcalculationshere.

3.3.3 CalculationsusingtheFormulaEditor

Theformulaeditorletsyoucreateeasyandcomplexformulasusingdraganddrop.

__________________________________________________________________________________________



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

3.4 One-timePricesandRecurringPrices

ConfigBoxsupportstwosetsofpricesenablingyoutoofferproductsthathaveaone-timefeeandarecurringfee(oreitheroneofthem).Thisenablesyoutoofferproductsthatforinstancehaveamonthlypriceandasetupprice.

Enablerecurringpricinginaproductat‘Others’

Typicalusecases

• Rentaloffers• Webhostingproducts• Phonecontracts

__________________________________________________________________________________________



Settingsrecurringpricing

Youcanlabeleachpricetypeindividuallyonaper-productbasisanddefineanintervalfortherecurringpayments.

Productlistitemexampleusingone-timeandrecurringprices

__________________________________________________________________________________________



Configuratorpagedisplayexamplewithrecurringpricing

__________________________________________________________________________________________



Selectionoverviewsettingswithrecurringpayment(inproducteditscreen)

Exampleselectionsoverview(withrecurringpricingpartinfulldetailsandone-timepricejusttotal):

YoucanconfiguretheselectionoverviewforeachproductindividuallyandsetglobaldefaultsintheConfigBoxconfiguration.

__________________________________________________________________________________________



Cartpageshowingone-timeandrecurringprices

Detailmodalwindow:

3.5 ProductVisualization

ConfigBoxenablesyoutopresentyourproductvisuallyandhaverealtimeupdatesofthevisualizationduringacustomer’sconfiguration.Insteadofprovidingimagesforeachcombinationoftheproduct,youcanuploadouttakesofthepartswithtransparentbackground,ConfigBoxstacksthoseimagestoproducetheproductvisualization.

Addinganimagetothevisualization

YouuploadimagesinyouranswersatVisualizationImage(seemanualsectionQuestions).WithVisualizationStackingOrderyoudefinethepositionoftheimageinthestack.

__________________________________________________________________________________________



4 OrderManagement

4.1 Cartpage

4.1.1 Controlwhatacustomercandoonthecartpage

Acustomercanperformthefollowingtasksonthecart

• Requestaquotation

__________________________________________________________________________________________



• Saveanorder• Checkoutanorder

Youcancontrolwhichtasksareavailabletothecustomerforeachcustomergroup.YoufindthesettingsinSettings->CustomerGroups.

4.1.2 SettheContinueShoppinglisting

Atthecartandthankyoupagethecustomerseesa‘ContinueShopping’button,leadingtoaproductlistingofyourchoice.YoucansettheproductlistingatSettings->Checkout.

4.2 CustomerData

Youcancontrolwhatdatacanbeenteredandwhichshallbemandatoryinthevariouscustomerdataentryforms.Theseare

• Customerprofiledata• Formforquotationrequests• Formforstoringcartcontents• Formforassistancerequests• Formforecommercecheckouts

AtCustomerFields,yousetthefieldsthatshallbedisplayedorbeingmandatory.

__________________________________________________________________________________________



ImportantNote:Thebillingfields‘FirstName’,‘LastName’,‘Email’,‘Salutation’and‘Country’arerequiredbythesystemandcannotbemadeoptionalorhidden.

4.3 CustomerGroups

YoucanmanagecustomergroupsasSettings->CustomerGroupsandsetadefaultgroupfornewcustomersatSettings->Checkout.

Withcustomergroups,youcandothefollowing:

• Controlwhatacustomercanseeordointheshopsystem• Setvolumediscountlevels• Joomlaeditiononly:SetwhichJoomlausergroupthegroupisassociatedwith.

4.3.1 Associatedplatformgroup(Joomlaonly)

Youalsoassociatethecustomergroupwithaplatformusergroup.Whenanewcustomeraccountiscreated,aplatformuseriscreatedaswellandwillbeassignedtothatgroup.

__________________________________________________________________________________________



Benefits

Youcanusetheplatform´spermissionsystemtosetpermissionsforactionsintheCMSandotherextensionsthatsupportACL.

Importantnote:OnJoomla,youneedtoallowSiteLoginforanyassociatedgroupatSite->Configuration->Permissions.

4.3.2 Taxdisplaymode

Youcancontrolthewaytaxesarehandledthroughoutthesystem.Thereare2modes

B2C–Businesstocustomer

• Intheconfigurator,itempricesaredisplayednet• Inorderoverviews,itempricesaredisplayednetandtaxesarestatedbeforethetotal(PlusX%tax)

B2B–Businesstobusiness

• Intheconfigurator,itempricesaredisplayednet• Inorderoverviews,itempricesaredisplayednetandtaxesarestatedafterthetotal(includingX%tax)

4.3.3 Controldisplayofprices

Youcanhidepricesintheconfiguratorandcartpage.Priceswillstillshowinquotations,emailnotifications(iforderoverviewsareincluded)andcheckoutpages.

4.3.4 Discountlevels

Foreachgroupyoucansetdiscountlevelsfortheproducts.Youhave5levels,eachwithaminimumordervalueandadiscountpercentageorfixedamounttosubtractfromtheproductvalue.Ifadiscountapplies,itwillbeshowninorderoverviewpages.

Importantnote:Thediscountrateneedstobeanegativenumber.

4.4 ShippingManagement

ConfigBoxautomaticallycalculatesshippingcostsfromthetotalweightoftheorder,shippingcountryandchosenshipper.

Setupofzones

AtCountriesandShipping->ShippingZonesyoudefinezonesandassigncountriestothese.Youusethesezonesinshippingratestoenableyoubeabletouseasingleshippingrateformultiplecountriesthathavethesameshippingcosts.

__________________________________________________________________________________________



4.5 PaymentMethods

ConfigBoxshipswithvariousconnectorstoonlinepaymentserviceproviders(PSPs)andsupportsofflinebanktransaction(showingathank-you-pagewithbankinformation)andorderswithnoimmediatepayment.InConfigBoxyouaddpaymentmethodswithvarioussettings,choosetheregardingPSP,click‘save’,andconfiguretheconnectoratthesettingsontheright.

4.5.1 Bundledconnectorstoonlinepaymentserviceproviders• Autorize.NetSIM(USAandCanadaonly)• BillSAFEInvoice(Germanyonly)• mPAY24Classic(Austriaonly)• MultiSafepayConnect(Netherlandsandinternational)• PaymillRESTAPI(International)• PayPalPaymentsStandard(International)• PostFinanceBasic,StartupandProfessional(Switzerlandonly)• QuickPay(International)• SagePayServerIntegration(International)• SOFORTÜberweisungClassic(International)• VRPAYVirtuell(Germanyonly)

__________________________________________________________________________________________



• WirecardCheckoutPage(International)• WorldPayBusinessGateway(UKandinternational)

SincethewebsiteURLsoftheprovidersareliabletochange,pleaseuseasearchengineforinfoabouttheregardingPSP.IfyouarenotsureyougottherightPSPorproduct,pleaserefertocustomersupport.

WearestrivingtoextendourselectionofPSPintegrations.IfyourequireaspecificPSPintegration,pleasecontactcustomersupportwiththecompanyandproductnameofthePSP.Thishelpsusprioritizing.

4.6 EmailNotifications

Emailnotificationsareautomaticallysentwhenthestatusofanorderchanges.Youdefinewhichnotificationsaresenttothecustomerand/ortotheshopmanagerandwhichsubjectandcontenttheemailshouldcontain.

StoremanageremailsgototheaddressyousetupatStoreInformation->EmailSales.

Note:Below‘EmailtoCustomer`thereisanothersection`EmailtoShopManager`

Enteraninternalnameandchoosetheorderstatusonwhichtheemailshouldbesent.

SubjectandemailHTMListhecontentofyouremail.Youfindalistofavailableplaceholdersontherightsideoftheeditform.

Youfindthesamefunctionalityfortheshop-managernotificationbeneaththeCustomerEmailsettings.

Withtheplaceholder{element_order_overview}youcandisplayanoverviewoftheorder.

__________________________________________________________________________________________



4.6.1 NotificationSnippets

Withnotificationsnippets,youcaninsertprecompileddatainyournotificationtext.YouaddtheplaceholdersincurlybracketsintheemailHTML.See{element_order_overview}or{element_store_information}forreference.

SeethemanualsectionconcustomNotificationSnippetsonhowtomakeyourown!

Importantnote:Toavoidlayoutproblemsinemailclients,placesnippetplaceholdersina<div>element.SelecttheplaceholderandclickFormats->Blocks->Div(seescreenshotbelow).

4.7 Invoices

4.7.1 InvoiceSettings

TherearevariouswaysonhowCBhandlesinvoicing.SeethesettingspageintheCBbackendat‘Invoicing’.

__________________________________________________________________________________________



With‘Sendinvoiceviaemail’activated,yourcustomersgettheirPDFinvoiceperemailassoonastheinvoiceisreleased.

Invoicegeneration

If‘Automaticafterclearance’isactivated,theinvoicewillbeauto-generatedbutyouchoosethemomentmanually(intheorderdetailpageOrders).Theinvoicewillbeavailableanddownloadablebythecustomerinthecustomerprofilepage.

If‘Automatic’isactivated,invoicesareauto-generatedandsentautomaticallyoncethestatusoftheorderissetto‘paid’(eitherfromthePSPduringcheckoutormanuallybyyouchangingtheorderstatus).

If‘Aftermanualdownload’isactivated,youuploadyourownPDFintheorderdetailpage.

Exampleoftheorderdetailpageusing`Aftermanualdownload’

4.8 GoogleAnalyticsTrackingandReporting

4.8.1 Prerequisites

TousetheGoogleAnalyticsintegrationfeaturesofConfigBox,youneedtohaveGoogleUniversalAnalyticstrackingcodeintegratedinyourwebsite.

• SetupGoogleAnalyticsWebTrackinghttps://developers.google.com/analytics/devguides/collection/analyticsjs/

4.8.2 GoogleAnalyticsE-commerceTracking

GoogleAnalyticsE-commerceTrackingisintegratedbydefault.YouneedtoenableE-commerceTrackinginyourGoogleAnalyticsprofileSetting.

• SetupGoogleAnalyticsE-commerceTrackingonyourwebproperty’sprofilehttps://support.google.com/analytics/answer/1009612?hl=en

__________________________________________________________________________________________



Whendoestrackingtakeplace?

SinceGoogleAnalyticsE-commercetrackingreliesonthecustomertoreturntotheshopafterpaymentthereisnoguaranteethatthetrackingwilltakeplace.ConfigBoxraisestheprobabilitybyschedulingthetrackingforthenextvisittoaConfigBoxshoppage(giventhecustomerlogsin).

Thereare2scenarios:

• Customerreturnstotheorderpageafterpayment:Trackingtakesplaceimmediately.

• Customerdoesnotreturnafterpaymentortherightorderstatusissetmanually:Trackingwillbescheduledforthenexttimethecustomervisitsandlogsin.Caveat:Thedateofpurchasewillbethetrackingdate(GAE-commerceTrackinglimitation),distortingstatisticstosomeextent.

4.8.3 UseofGoogleAnalyticsgoals

IfyousetupagoalforanalyzingconversioninGoogleAnalytics,youcanuseeventtrackingasgoaltype.Thegoalvalueisthetotalpayableamount(includingmerchandiseprice,shipping,paymentfeeandtaxes;incaseofdepositpaymentonlythedepositpaymentisused).

__________________________________________________________________________________________



Importantnotes:Pleasenotethatonlypaidordersaretracked;e.g.orderswithstatuschangeto‘ordered’arenottracked.Weplantoextendthegoalintegrationtootherorderstatusesinthefuture.AlsotheeventistrackedonthesameconditionsasE-commerceTracking(seeGoogleAnalyticsE-commerceTracking).

SetupinGoogleAnalyticsProfile:

GoalType:

Event

Category:

configbox_goals

Action:

order_payment

Label:

leaveempty

Value:

leaveempty

GoalValue:

Usetheactualeventvalue

Alwaysuse‘thatisequalto’

4.9 Reviews

Customerscanwritereviewsandsetratingsonproducts.YouenableordisablereviewsgloballyatConfigBox->Configuration->Reviewsorenableordisablethemforspecificproductsattheproducteditscreen.

Newreviewsareinactiveinitiallyandneedtobeapproved.Anotificationemailonnewreviewsisdispatchedtoalertstaff.

AtSettings->Reviewsyouenterthenotificationemailaddress.

AtReviewsyouhavealistofallreviewswhereyoucanfilter,approveandeditreviews.

__________________________________________________________________________________________



4.10 CountriesandShipping

Besidesshippingmanagement,inthescreensforCountriesandShippingyousetupallavailablecountries,states,countiesandcities.CountriesandStatesarepre-filledoutofthebox,ifyouwanttomakethecustomerchoosehiscountyorhavehimselectacityinsteadofenteringthecityname,youcanaddthisinformation.

4.10.1 TaxHandlingforCitiesandStatesForeachcountry(orstate)youcandefineifVATmustbecharged(forcountriesyoualsodefineifthecountryisintheEU-VATzoneforB2BVAT-freeinvoicing).IncountriesandstatesyoucanalsoOVERRIDEthetaxrateforeachtaxclassyouhavesetup.IncountiesandcitiesyoucanenterapercentagethatwillbeADDEDtothecountry/statetaxrate.ThisaccommodatesthetaxsystemfortheUnitedStates,Canadaandothercountries.Pleasenotethattheindividualtaxesarenotdisplayedseparately,butasonecompoundtaxrate.

4.10.2 PredefinedCitiesAddingcitiesatCountriesandShipping->Citiesforcesthecustomertoselectacityfromasearchabledrop-downlistinsteadoflettinghimenterthecitynameinatextfield.Citiesareconnectedtocounties,soyouneedtoentercountiesandtheircities.Pleasenotethatyouneedtohaveacompletecitylistforacounty,otherwisecustomersfromothercitiescannotorderorrequestquotes.Youcanhaveamixofcountieswithandwithoutpredefinedcities.Theformswillshowtheappropriateformfieldasthecustomerselectsthecounty.

PleasenotethatIPGeolocationcannotdeterminethecountyinanycaseandcannotdeterminethecityifyouusepredefinedcities.

4.11 UsingIPGeolocationtoprefillcustomerdataandotherpurposes

ConfigBoxenablesyoutohavecustomerformsprefilledtothebestextendpossible.ThisfeaturecoversRFQforms,saveorderformsandthecheckout.YouneedanaccountandacontingentforGeoIP2Precision:CitywithMaxMind(https://www.maxmind.com/),atrustedandindustry-leadingproviderofIP-Geolocationdata.

Asof2015-02-26thelinktothepurchasepageis:

https://www.maxmind.com/en/geoip2-precision-city-service

Yougetalicensekey(informofatext-code)byMaxMind.YouenteritatConfigBox->Settings->IPGeolocationTracking->MaxMindLicenseKey,thenactivatethefeature.

5 CustomizingConfigBox

CustomizationofConfigBoxisstraightforward,wellorganized,requiresnomodificationofthebasesoftwareandenablesyoutomakeprofoundextensionsandmodificationstofunctionalityofthesoftware:

• Designofproductsandconfigurators• Individualconfiguratordesignsforeachproduct• Outputofcustom,non-standardproductdata

__________________________________________________________________________________________



• Modificationandextensionofthebasefunctionality• Customizationofwordingusedintheapplication• Translationinnon-bundledlanguages• Integrationwiththirdpartysoftware

Important:

Anycustomizationyoumakeordelegateneedstobecheckedforcompatibilityonsoftwareupdatesandrevisedifnecessary.Onminorsoftwareupdates,wemakeanefforttominimizebreakingchangesandifneedbeprovidedetailedinformationaboutthemonourwebsite(onthedownloadpageforeachversion).

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

CustomizationfolderJoomla:

/components/com_configbox/data/customization/

CustomizationfolderWordpress:

/wp-content/plugins/configbox/data/customization/

5.1 CustomQuotationPDFs

NoteforcustomersusingcustomquotePDFsinearlierversions:AsopposedtoearlierreleasesofConfigBox,itisnolongernecessarytooverridebothPDFdownloadandPDFattachment.

YoucanoverridetheoutputofquotationPDFsinthesamewayasothertemplates(seeCustomTemplatesforreference).However,templatesusedforPDFgenerationaremoredelicate:

• TheproducedHTMLandCSSneedstoadherestrictlytoHTML1.1strictandCSSlevel3.

• UsingCSSfloatisnotsupported

• Nestedtables(<table>withina<table>)needtobeavoidedbecauseyougetbadresultsiftheeithertablespansovermultiplepages.

• IncaseyourcustomizationshaveledtoasizablecustomCSSfile,considercreatingaseparatestylesheetforthequotationPDFforperformancereasons(settheURLtothatstylesheetinthe<head>block).

• SinceConfigBox2.6.26wemovedtheheader/footerPHPtoaseparatetemplatefile(header_footer)foreasiercustomization.Ifyouoverridesomethinganddon’tneedchangestotheheader/footer,simplydon’tcopytheheader_footer.phptemplatetoyourcustomizationfolder.Thesystemwillloadtheoriginaltemplatethen.

• Mindthatifyouwanttoadjustpagemargins,setmarginsonthe<body>tag.ThisisthereliablewaytohavemarginssetoneachPDFpage.Since2.6.26thereareCSSclassesonthe<body>tag(body-pdfandaclassforeachtype–body-pdf-quotation,body-pdf-invoiceandbody-pdf-orderslip).Domarginstylingontheseclassestoavoidchanging<body>stylingonnormalwebsitepages.

Locationoftheoriginaltemplate:Joomla:/components/com_configbox/views/quotation/tmpl/default.phpWordpress:/wp-content/plugins/configbox/app/views/quotation/tmpl/default.php

__________________________________________________________________________________________



Locationofthecustomtemplate:Joomla:/components/com_configbox/data/customization/templates/quotation/default.phpWordpress:/wp-content/plugins/configbox/app/data/customization/templates/quotation/default.php

Thetemplateusesoutputofotherviews

Thetemplateusestheoutputofotherviews(namely‘record’and‘positions’.Ifyouneedtoalterthispartofthequotation,youcanmakeoverridesofthesetemplates,butbemindfulaboutthefactthattheseviewsareusedelsewhere(adminorderpage,userorderpage,checkoutpageandpossiblemoreinthefuture).

5.2 CustomWordingandTranslations

Customizingwordingisrathereasy.Youneedtocomepreparedwithknowledgeoneditingfilesonyourwebserverandoneditingplaintextfileswithaspecificencoding(UTF-8).Thelatterisexplainedlaterinthissection.

5.2.1 Understandingtheconceptoflanguagefiles

HowwordingandtranslationishandledinConfigBox

TextsyouseeonthepageshandledbyConfigBoxarecustomizable.Toaccomplishthis,thesoftwareusesplaintextfilescalledsystemlanguagefilestofindandoutputtherightphraseintherightlanguage.

Ontopofsystemlanguagefiles,thesystemlooksforcustomlanguagefilesthatyoucanusetocustomizespecificphrases.

ThesefilescanalsobeusedtoaddanewtranslationofConfigBoxortotranslatetextsthatyouhaveincustomtemplates.

Howdoesalanguagefilelooklike?

Atypicallineinalanguagefilelookslikethis:

REQUEST QUOTATION="Angebot anfordern"

Ontheleftinuppercaseyouseethekeywordofthephrasethesystemlooksfor.Ontherightwithindoublequotesyouseethephrasethatthesystemwilldisplay.Typically,thekeywordistheuppercaseformofthephraseinEnglishbutitmaybedifferentfortechnicalreasons.

Locationsofsystemlanguagefiles

Joomla:

/components/com_configbox/language/en-GB/frontend.ini/components/com_configbox/language/en-GB/backend.ini

Wordpress:

/wp-content/plugins/configbox/app/language/en-GB/frontend.ini/wp-content/plugins/configbox/app/language/en-GB/backend.ini

Locationsofcustomlanguagefiles

Joomla:

/components/com_configbox/data/customization/language_overrides/en-GB/overrides.ini

__________________________________________________________________________________________



Wordpress:

/wp-content/plugins/configbox/app/data/customization/language_overrides/en-GB/overrides.ini

Note:Overridesaffectbothfrontendandbackend.

HowtofigureoutwhichlanguagefilecontainsthephraseIsearchfor?

Anyphasethatisusedinbothbackendandfrontendisinfrontend.ini–backend-onlyphrasesareinbackend.ini.Bestsimplysearchfirstininfrontend,theninbackend.

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(aphrasemayappear

inmultiplefiles,inthatcase,copyeachofthemtoavoidcomplicatedsituations)

Notes:

• Thekeywordmustremainunalteredandmakesuretohaveyourphrasewrappedindoublequotes.• Donotputlinebreaksinyourphrases,ifyouneedone,add\nor<br/>• Ifyouneeddoublequotesinyourphrase,writethemas\"• WhenchangingphrasesinEnglish,youmaynotalwaysfindthephraseinthesystemlanguagefiles.

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

• Phrasesmaychangeinmajorsoftwareupdateswithoutnotice.Itisuptoyoutocheckandreviseyourcustomizationsifnecessary.

5.3 CustomFields

Products,questionsandanswershave4to6customfieldsyoucanusetoenteranykindofadditional.Thepurposeofthesefieldsisnotspecific.Typicalusefulapplicationsare:

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

Forpracticalreasons,youcansetyourownlabelsofthesefieldsinSettings->CustomFields.

__________________________________________________________________________________________



5.4 CustomCSSstyling

CustomizingCSSstylingrequiresbasictomoderateHTMLandCSSskills.Customstylingcaneitherbesufficienttoamendstylingoftheshoporbeusedincombinationwithcustomizedtemplates.

ConfigBoxcomeswithastylesheetspecificallymadeforstylingcustomizations.Asallfilesinthecustomizationfolder,itisnotoverwrittenduringsoftwareupdates.

LocationinJoomla:

/components/com_configbox/data/customization/assets/css/custom.css

LocationinWordpress:

/wp-content/plugins/configbox/app/data/customization/assets/css/custom.css

Tips:

Useconventionsforruleselectors

Whenlookingatoneofthestylesheets,youseethatmostCSSselectorsstartwith#com_configbox#view-xorwithxstandingfortheview’sname.Whilebarelyavoidableanyways,werecommendyouadoptthatconventionforyourcustomizations.Itmakesitimmediatelyclearwhatyouintendtochangeanditavoidsunwantedchangesonotherpagetypes.

5.5 CustomJavaScript

CustomJavaScriptrequiresbasictomoderateHTML/JSskills.CustomJavaScriptcanbeusefulincombinationwithcustomtemplates.

ProTip:YoucanuseAMD-likedefinecallsandusecbrequiretoloadothercustomAMDmodules.ThecustomJSfileisloadedasAMDmodulenamedconfigbox/custom/custom.

LocationJoomla:

/components/com_configbox/data/customization/assets/javascript/custom.js

LocationWordpress:

/wp-content/plugins/configbox/app/data/customization/assets/javascript/custom.js

Tips:

WeuseAMDmodulesusingrequirejs.Weuseourowncontext(‘CB’).Yougotcbrequireavailableintheglobalscopetogetmodules.

WeregistercbjasjQuerymodule(whichisindependentfromwhateverjQueryyoumayhaveintheglobalscope).Usecbrequire([cbj],function($){..})tohavejQueryloaded(weusethelatestjQueryversionsandupdateregularly).

5.6 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/components/com_configbox/views(forWordpress/wp-content/plugins/configbox/app/views)youfindsub-foldersforeachviewthatConfigBoxusesfordisplayingpages.Thisiscalledaviewfolder.EachviewfoldercontainsaPHPfilecalledview.html.phpthathandlespreparationofthedatathatisusedfordisplayingcontent.

Eachviewfolderalsocontainsasub-foldercalledtmplthatcontainsatemplatefilethatistypicallynameddefault.php.TheHTMLproducedinthistemplatefileiswhatyouaregoingtoseeascontentonyourpage.

Someviewssplitthecontentintomultipletemplatefileswhenitismorepracticalandusetheoutputofotherviewswithintheirtemplatefileswhenitmakessense.Anexampleofthisisthequotationviewwhereorderrecordinformationandpositiondetailscomefromtheviews‘record’and‘positions’.

Workflowforoverridingatemplatefile

1)Firstyoulocatetheviewforwhichyouwanttomakeacustomization.Takethecartasexample:

/components/com_configbox/views/cart(orforWordpress/wp-content/plugins/configbox/app/views/cart)

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

2)Navigatetothefolderforcustomizedtemplates.Thelocationis:

Joomla:/components/com_configbox/data/customization/templates/

Wordpress:/wp-content/plugins/configbox/app/data/customization/templates/

3)Inthisfolderyoucreateafolderwiththenameoftheviewyouliketooverride:

/components/com_configbox/data/customization/templates/cart

4)Inthisfolder,youplacethetemplatefileyouliketooverride.Mindthatyoudonotcreatethesub-foldertmpllikeyouhaveitintheviewfolder.

Joomla:/components/com_configbox/data/customization/templates/cart/default.phpWordpress:/wp-content/plugins/configbox/app/data/customization/templates/cart/default.php

5)Youthenmakeyourcustomizationstothatfileasyouseefit.

Tips:

__________________________________________________________________________________________



Inviewswithmultipletemplatefiles,youcanchoosewhichonestocustomize

Ifyouoverrideonlycertaintemplatefiles,theotherswillbeloadedfromtheoriginalviewfolder.Thishelpsminimizingyoureffortsincaseofbreakingchangesinsoftwareupdates.

AvoidCSSstyling,addingimagesinplacesotherthanthecustomizationfolder

SeethechapteroncustomCSSstyling.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(Joomlaonly)

ThereisaveryusefulJoomlaextensionthatletsyououtputthedataofanyvariableinabrowserpopup.ItiscalledJDumpandcanbefoundintheJED:

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

Example(ObviouslythevariableusedheremustexistandthecallbeplacedinPHPtags):

dump($this->questions);

Makeuseofthelogfilesfordebugging

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

Youmayseeplentyofmessagesinsomeerrorlogfiles.

__________________________________________________________________________________________



5.7 CustomTemplatesforSpecificListings,Products,PagesandQuestions

Thissectionisaboutthetemplateeditorthatisessentiallyagraphicinterfaceforcreatingcustomtemplatefileswithsomeextras.

• Convenientlyaddormodifytemplatefilesintheadminarea• Createtemplatefilesforspecificproducts,configuratorpagesorquestions.

Intheeditformsofthecorrespondingtypesyoucanassignthetemplateusingthefield‘Template’.

Editformfortemplates

Youedittemplatesusingcodecoloringandformattingandyoucanalsoeditthesefilesonthefilesystem.

5.8 CustomConnectors

Whatareconnectorsfor?

__________________________________________________________________________________________



ConnectorsareusedtointegratethirdpartysoftwarewithConfigBoxtoextendorreplacefunctionality.

Exampletasks:

• Processanorderandbringthecustomertoacustomcartpage• Checkoutacart• Createaquotationfile• Performactionsonorderstatuschanges

Whatareconnectorstechnically?

AconnectorisbasicallyaPHPfilecontainingaPHPclasswithasetofmethods.ConfigBoxcallsthesemethods(iftheyexist)andprovidestandardizeddataasparametertoperformvariousprocesses.Thisisdoneusingtheobserverpattern.Dependingonthenatureofthetaskthesystemcallsonlythefirstconnectororallconnectors.

Exampleconnector:

Joomla:/components/com_configbox/observers/Orders.php

Wordpress:/wp-content/plugins/configbox/app/observers/Orders.php

Howtomanageconnectors

ConfigBox->Settings->Connectors:

Hereyoucanenableordisableconnectorsandaddorremovethem.

Addingaconnector

Afterclickingaddyouenternameoftheconnector,thesettingsandprovidethefile.Entertheformasperinstallationinstructionsoftheconnectorprovider.

__________________________________________________________________________________________



Howtodevelopaconnector

• Firstyoupickanameforyourconnector.Inthisexampleweuseecomsystem.• CreateaPHPfilewithaPHPclasscalledObserverEcomsystem.

<?php class ObserverEcomsystem { }

• Savethefileandadditasconnector(see6.8.3).

Customconnectorsarestoredinthispath:

Joomla:/components/com_configbox/data/customization/custom_observers

Joomla:/wp-content/plugins/configbox/app/data/customization/custom_observers

Connectortoplaceaconfiguredproductinathirdpartyecommercecart

AddthemethodonConfigBoxAddToCartwithoneparameter(passedbyreference).

function onConfigBoxAddToCart(&$cartDetails) { // Code to add product to shop system $grandOrderDetails->redirectURL = 'URL TO THIRD PARTY CART'; return true; }

About$cartDetails

__________________________________________________________________________________________



Theparameter$cartDetailsisaPHPobjectcontainingtheinformationofthecurrentcartandallpositionsinit.Usevar_dump(),print_r()ordump()(installJDumpfromtheJED)toseethestructureanddataoftheobject.

About$cartDetails->redirectURL

SetthememberredirectURLtotheURLofyourecommercesystem’scartpage.ConfigBoxreadsthismemberandredirectsthecustomertothegivenURL(canbeacompleteURLorarelative/absoluteURI).

ConnectortoplaceConfigBoxcartcontentsinathirdpartyecommercecheckoutpage

ThesameprocedureappliesasforonConfigBoxAddToCart,themethodnameforthisisonConfigBoxCheckout.

function onConfigBoxCheckout(&$cartDetails) { // Code to add product to shop system $orderDetails->redirectURL = 'URL TO THIRD PARTY CHECKOUT PAGE'; return true; }

5.9 CustomNotificationsnippets

Youcanaddcustomnotificationsnippetstooutputcustomdatainyouremailnotifications.AsnippetisasimplePHPfilethatisincludedandthebufferoutputgeneratedwillbeinsertedwheretheplaceholderisset.

Locationofthecustomsnippetfolder

Joomla:/components/com_configbox/data/customization/notification_snippets

Wordpress:/wp-content/plugins/configbox/app/data/customization/notification_snippets

Snippetandfilenameconvention

Sayyoucallyoursnippet‘customsnippet’.Thefilenamehastobecalledcustomsnippet.html.php,theplaceholder{element_customsnippet}.

Dataavailableinthesnippetfile

$orderRecord–Objectholdingallorderdata(see$orderRecord->orderAddressforordercustomerdata)

$shopData–Objectholdingtheshopdata

Helpfultips

Seethecodefortheorderoverviewforreferencein

Joomla:/components/com_configbox/observers/notifications/elements/order_overview.html.php

Wordpress:/wp-content/plugins/configbox/appobservers/notifications/elements/order_overview.html.php

Joomlaonly:ThereisaveryusefulJoomlaextensionthatletsyououtputthedataofanyvariableinatreestructureinapopup.ItiscalledJDumpandcanbefoundintheJED:

__________________________________________________________________________________________



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

Examplecall:

dump($orderRecord);

5.10 CustomRuleConditions

Youcandevelopcustomruleconditions.Developingtheserequiresadeptprogrammingskills.Rovexoprovidesnofreesupportorproblemanalysisforcustomruleconditions.

5.10.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().Thegistofitis

__________________________________________________________________________________________



thateachconditioniswrappedina<span>ElementwithHTML5dataattributescontainingthecondition’sdata.Inthe<span>isahuman-readablenameofthecondition,theoperatortochoosefromandatextfieldforthesetpoint,thevaluethethingyoutestforshouldhave.ThosetextfieldshavetheCSSclass‚input’andadataattributecalled‚data-condition-key’thatholdsthekeyoftheentryintheconditiondata.Duringsaving,thosetextfieldsarestoredlikenormalconditiondata,noneedtohavethemasdatainthewrapping<span>element.

Whateveryouaddasconditiondatawillstoredwhentheruleisstoredandwillbeavailabletoyouinthefollowingmethod.

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

getEvaluationResult($conditionData,$selections)

Thismethodiscalledwhentheconditionisevaluatedaspartofthewholerule.$conditionDatacontainseverythingthatwassetas$conditionDatainthepreviousmethod.$selectionsholdsanarraywiththecurrentconfigurationthatistested.

Themethodhastoreturntrueorfalse.Themethodshouldbeasfastaspossible.Cachewhereyoucansincethismethodmaybecalledmultipletimeseachtimeacustomermakesaselectionintheconfigurator.

SeeCustomConditionExample::readMe()fortheconcretestructureofbothparameters.

5.10.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.

6.1 UpgradefromConfigBoxversionspriorversion3.1

3.1.0isamajorreleaseandunderwentarewriteofalmostallcode.Youbesttakeanycustomizationsyouhaveandcompareitwiththebuilt-incounterpartandrewrite.

7 Troubleshooting

AlwayscheckifyoureadandfollowedtheinstructionsinthesectionInstallationandthesectionConfigBoxupgrades.

7.1 PricingandProductVisualizationdoesnotupdate

Checklist:

PageCachingpluginsareactiveonconfiguratorpages

PagecachingpluginslikeYot-CacheorJoomlArtT3TemplateCachesandotherspreventConfigBoxfrompreparingconfigurationsbeforedisplayingtheconfiguratorpage.

Solution:Deactivatethecachingingeneralordisableitforthecomponentcom_configbox.

Linksandbuttonsdonotredirecttotheintendedpage

ThirdpartySEF-URLslikeAceSEF,SH404SEFandothersmanipulateURLsthatcanleadtoincorrectredirections.

Solution:FinetunetheSEFtoolordisablethesetoolsforthecomponentcom_configbox.

AdminToolsdonotallowdirectaccesstocomponents/com_configbox/configbox.php

ThereisanextensioncalledAdminToolsthatcreatesrestrictionsforimprovedsecurity.Youneedtosetupanexceptionthatallowsdirectaccesstothementionedfile(ConfiguratorupdatestodirectlytothecomponentinsteadofthroughJoomlabecauseofsignificantperformanceimprovement).

Solution:GotoComponents->AdminTools->.htaccessMaker->Exceptionsandaddthislinetothefield‘Allowdirectaccess,including.phpfiles,tothesedirectories’:components/com_configbox

IonCubeLoaderisonlyactiveforcertaindirectories

Solution:SeethechapteronInstallation->IonCubeLoaderonhowtosetupionCubeLoadercorrectly.

__________________________________________________________________________________________



7.2 Theinstallationfailedanduninstallationisnotpossible

IftheinstallationfailedthereisaknownissuewithJoomla2.5leavingdatabasetablerowsabouttheextensionbehind,makinguninstallation,launchandreinstallationsimpossible.

Solution

• LaunchphpMyAdmininyourserverhostingpanel• Gotothetablejos_assets• Searchforrowswithname‘com_configbox’andremovetherows• Searchforrowswithname‘com_cbcheckout’andremovetherows• Gotothetablejos_extensions• Searchforrowswithname‘com_configbox’andremovetherows• Searchforrowswithname‘com_cbcheckout’andremovetherows

7.3 Paymentmethodchangesarenoteffective

Whenanorderischeckedout,ConfigBoxcreatesacopyofallpaymentmethodsettingsforthatorder.Ifyoumakechangestothepaymentmethods,youwon’tseethosechangesinanalreadycheckedoutorder.Checkoutanewordertoseethecurrentsetup.

7.4 IssueswithSH404SEF

IfyougotissueswithSEFURLsonConfigBoxandOrderManagementpages,configureSH404SEFlikethis:

• GotoComponents->SH404SEF->Configuration(toprightcorner)->General->Bycomponent• Forconfigbox,usethesettings‘UseJoomlarouter’,‘TranslateURL’,‘Insertlanguagecode’,‘Use

Joomlarouter’,‘DisableshURL’(seescreenshotforreference)

__________________________________________________________________________________________



InordertouseSEFURLsforConfigBoxpages,usetheJoomlanativeSEFtechniques.Createmenuitemsforproductlistings,cartpageetc.

7.5 Anerrormessageoccurredafteruploadingapackage

Checkthefollowingthings:

• Makesureyourfolderfortemporaryfilesiscorrectandwritable(Joomlaglobalconfiguration)• Makesurethetargetfoldersarewritable(e.g.components,modules,plugins/*,

administrator/components)• Makesureyourwebserverallowsuploadoffileslargerthan32MB(seephp.inisettingspost_max_size

andupload_max_filesize).Checkthesizeofyourupdatepackageandmakesurebothsettingsarehighenough.

• CheckforanywarningsontheJoomlaextensionmanagerpage.

8 Extensions

8.1 VirtueMartConnector

PleasenotethatwediscontinuedthesaleandsupportoftheVirtueMartConnector.Seethemanualofpreviousversions.

Documents

ConfigBox 3.1 for Joomla and Wordpress...ConfigBox does silent registration and creates a linked Joomla user account. The group information is used to set the correct Joomla user group