Custom Templates 42

Customizing  templates  requires  moderate  PHP  programming  skills  and  related  skills  like  HTML/JS/CSS   (plus/minus  depending  on  the  kind  of  customization  you  need).  

ConfigBox  is  organized  in  page  types  (e.g.  product  listing,  cart,  checkout,  admin  order  page  etc.)  and  each   page  type  makes  use  of  a  view  (or  multiple  views).  Each  view  has  a  template  file  (or  multiple  ones)   responsible  for  output  in  the  browser  and  these  template  files  can  be  customized.  

Important:  As  with  any  customization,  custom  templates  may  need  to  be  checked  and  changed  for   compatibility  on  software  updates.  On  the  download  page  you  find  detailed  information  on  breaking   changes  for  each  software  update.  

Notes  if  you  are  familiar  with  Joomla’s  MVC  and  template  override  system:  

Our  concept  is  similar  and  practically  transparent  to  the  way  Joomla  handles  views  and  templates.  The   difference  is  that  overrides  are  not  searched  for  in  the  Joomla  template  folder,  but  in  ConfigBox’s  data   folder  (location  see  later  in  this  section)  and  that  view  functions  (like  Class::loadTemplate())  are  named   and  behave  differently.  

Understanding  the  concept  of  template  customization  

In  /components/com_configbox/views  you  find  sub-­‐folders  for  each  view  that  ConfigBox  uses  for  

displaying  pages.  This  is  called  a  view  folder.  Each  view  folder  contains  a  PHP  file  called  view.html.php  (or   view.raw.php  in  some  cases)  that  handles  preparation  of  the  data  that  is  used  for  displaying  content.   Each  view  folder  also  contains  a  sub-­‐folder  called  tmpl  that  contains  a  template  file  that  is  typically   named  default.php.  The  HTML  produced  in  this  template  file  is  what  you  are  going  to  see  as  content  on   your  page.  

Some  views  split  the  content  into  multiple  template  files  when  it  is  more  practical  and  use  the  output  of   other  views  within  their  template  files  when  it  makes  sense.  An  example  of  this  is  the  quotation  view   where  order  record  information  and  position  details  come  from  the  views  ‘record’  and  ‘positions’.   Workflow  for  overriding  a  template  file  

The  cart  view  uses  a  single  template  file,  named  default.php  (Future  releases  may  have  it  split  in  multiple   template  files).  Download  or  copy  the  template  file,  you  typically  want  to  use  it  as  base  of  your  

customization.  

2)  Navigate  to  the  folder  for  customized  templates.  The  location  is:   /components/com_configbox/data/customization/templates/  

3)  In  this  folder  you  create  a  folder  with  the  name  of  the  view  you  like  to  override:   /components/com_configbox/data/customization/templates/cart  

4)  In  this  folder,  you  place  the  template  file  you  like  to  override.  Mind  that  you  do  not  create  the  sub-­‐ folder  tmpl  like  you  have  it  in  the  view  folder.  

/components/com_configbox/data/customization/templates/cart/default.php   5)  You  then  make  your  customizations  to  that  file  as  you  see  fit.    

Tips:  

ConfigBox  consists  of  two  components  (com_configbox  and  com_cbcheckout)  

This  means  that  you  find  views  in  /components/com_cbcheckout/views  as  well.  The  system  for  overriding   is  the  same.  But  the  custom  templates  are  in  the  same  folder  as  for  com_configbox.  

In  views  with  multiple  template  files,  you  can  choose  which  ones  to  customize  

If  you  override  only  certain  template  files,  the  others  will  be  loaded  from  the  original  view  folder.  This   helps  minimizing  your  efforts  in  case  of  breaking  changes  in  software  updates.  

Avoid  CSS  styling,  adding  images  in  places  other  than  the  customization  folder    

Have  a  look  at  the  chapter  on  custom  CSS  styling.  You  also  have  an  image  folder  in  your  customization   folder.  This  helps  keeping  your  work  well  organized  and  quick  to  comprehend  for  colleagues  and  service   providers.  

Make  use  of  custom  fields    

See  section  on  custom  fields  for  reference.  You  can  access  the  data  of  these  fields  in  the  appropriate   templates  and  use  them  for  output,  calculations  or  other  logic.  See  tip  on  investigating  template  data  for   the  best  way  to  see  where  the  data  is  stored.  

For  multilingual  sites,  check  the  chapter  on  custom  wording  

The  software  has  an  engine  to  make  translated  texts  straightforward.  Managing  translated  phrases  is   explained  in  that  chapter.  To  make  use  of  it  for  your  own  wording,  you  have  a  static  PHP  class  method  to   output  your  translated  phrases.    

Example:  (Obviously,  this  code  snippet  needs  to  be  placed  within  PHP  tags).  

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

The  phrase  you  use  here  must  match  the  keyword  used  in  your  custom  language  file.  So  the  line  in  your   language  file  would  look  like  this:  

YOUR PHRASE="Your translation of the phrase"

There  is  a  very  useful  Joomla  extension  that  lets  you  output  the  data  of  any  variable  in  a  browser  popup.   It  is  called  JDump  and  can  be  found  in  the  JED:  

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

Example  (Obviously  the  variable  used  here  must  exist  and  the  call  be  placed  in  PHP  tags):    

dump($this->elements);

Make  use  of  the  log  files  for  debugging  

ConfigBox  logs  errors  and  other  things  extensively.  The  log  files  can  be  useful  in  case  you  work  directly  on   a  webserver  and  do  not  have  access  to  the  server’s  error  log.  Logs  are  located  in  your  website’s  log  folder   in  a  sub-­‐folder  called  ‘configbox’.    

You  may  see  plenty  of  messages  in  some  error  log  files.