VivvoCMSTemplateDesignGuide

MiloradTopalovic,Spoonlabsd.o.o.

ABSTRACT
AguideonVivvoWebContentManagement(WCM)templates,templatestructure
andVTE(VivvoTemplateEngine)languageforwebdesignersandsystemintegrators.

2 [VIVVOCMSTEMPLATEDESIGNGUIDE]

TableofContents
Introduction........................................................................................................... 3
TheBasics:HowdoesVivvofrontendworks?........................................................ 4
PartI:InstallationandSiteSetup................................................................................................................5
PartII:BasicTheming,WidgetsandLayouts.........................................................................................7
VTEandMagic ....................................................................................................... 9
TemplateFilesandTemplates .............................................................................. 11
Startinghomepage/default.tpl .................................................................................................................. 11
HeaderandFootertemplates .................................................................................................................... 11
Styles..................................................................................................................................................................... 12
Conclusion/FurtherReference ............................................................................ 14

Page 2 of 14

Version1.0|2009Spoonlabsd.o.o.

[VIVVOCMSTEMPLATEDESIGNGUIDE] 3

Introduction

Inthisarticleweshallexplainsomebasicprinciplesandgiverecommendations
for a clear and maintainable Vivvo site, especially regarding a wellstructured
templatedesign.
Template design is like programming: a good style results in reusability and
cheapermaintenance.Themostimportantprinciplesare:

Always start with an analysis of the requirements and the needed site
structure,andplanyourwork.
NeveruseCSScodedouble.(Insteadstoreitinagenericwayandreuseit)
Logicalstructure
Makeenoughcommentssoonecanunderstandthecodeeasilyalsoafter
alongertime.

VivvoCMSmakesjobofcreatingandmodifyingtemplatesmucheasieroffering
premadevarietyoftwocolumn,threecolumn,andfourcolumnlayoutsyoucan
easilyadopttomeetyourspecificneeds,thustensofwidgets(smallfunctional
boxtemplates)premadewithspecificfunctionality.Infollowingsections,well
putsomeoftheminusetoshowcasetheversatilityofVivvoCMStemplate
engine(VTE),templatestructureandavailablepremaderesourcesforrapid
development.

VivvoCMSTemplateDesignGuide 3

4 [VIVVOCMSTEMPLATEDESIGNGUIDE]

TheBasics:HowdoesVivvofrontendworks?

Vivvofrontendiscomposedofindividualframetemplatesthatcarryentirepage
structure.Thosetemplatesarehomepagetemplate,categorytemplate(where
eachrespectivecategorycanhaveowntemplate),fullpage/articletemplate,
searchresults/tagresultstemplate,etc.
Frametemplatesincludesmallertemplatefilesthatencapsulatesingle,specific
functionalityoroutput,whichareinmostcasesarticlelistswithvarious
parametersusedforsortingandpresentingportionsofthecontent,suchas
headlines,latestcomments,featuredauthorandsimilar.Thoseareusually
referredtoasboxtemplatesandcanbereusedthroughoutthetemplate
structure.Multipleframetemplatescanreusethesameboxtemplate.
Mostofboxtemplates(modules)withinVivvoareconstructedoutofthreemain
parts:
1. Boxstatement<vte:box>
2. Parametersblock<vte:params>
3. Templateblock<vte:template>
Box/Loadstatementinstructstheenginewhichmoduletoload,thustowhich
VivvoObjecttheblockapplies(articles,users,comments,categories,etc.).The
scopeofthisblockislocal,soanycontentfetchedwithin<vte:box>blockis
availableonlywithinthescopeofthisblock.
Parametersblock(<vte:params>array)iswhereyoucanspecifyadditional
datafilter,datamanipulationandcachingfetchingoptions:

ConstructstheSQLqueryusingalmostnaturallanguagetoretrieves
articles,comments,categories,users
Instructsthetemplateenginetoflagarticlesasalreadyusedsoitdoesnt
reappearonthesamepageinanyotherblockofcontent
Instructsthetemplateenginetocachethecontent

TemplateblockiswhereyouformattheoutputusingnormalxHTMLandCSS
styles.Youmaypresentyourcontentlistsinvariousways(titleonly,title+
abstractimage,title+abstractimage+shortsummary,etc.)

YouwillfindmoredetailedexplanationandexamplesinsectionVTEandMagic.

Page 4 of 14

Version1.0|2009Spoonlabsd.o.o.

[VIVVOCMSTEMPLATEDESIGNGUIDE] 5

PartI:InstallationandSiteSetup

AfteryoucompletestandardVivvoinstallation,allyourthemesandtemplates
filesarestoredinrootfolder.

<VivvoRoot>
o (...)
o /templates
/legacy_3.4(3.4legacyversiontemplateset)
/legacy_3.5(3.5legacyversiontemplateset)
/mobile(mobiletemplateset)
/xhtml(defaulttemplateset)
o /themes
/default(defaulttheme(css)set)
/legacy_3.4(3.4legacytheme(css)set)
/legacy_3.5(3.5legacytheme(css)set)
/mobile(mobiletheme(css)set)

TreeaboveshowstemplatesandthemessetsthatcomewitheveryVivvodefaultinstallation.

YoucanquicklymanageyourtemplatesandthemesfromLayoutsectionin
Vivvoadministration.YoucanreadmoreaboutthatatintheUserManual:
http://wiki.vivvo.net/user_manual/layout
Togetthemostofyourtemplatesandthemes,installingExtendVivvopluginis
highlyrecommended.ExtendVivvopluginintegratesVivvoResourceCenterin
yourlayoutsectiongivingyouabilitytodownloadandsynchronizethemes,
templatesandotherresourcessuchaspluginsandwidgetsavailableforfree
download.
Tocreatenewtemplate/themeset,allyouhavetodoiscreatenewfolders
within/templatesand/themesfolders,andcopyentirecontentfrom/xhtml
and/defaultfoldersrespectively.

<VivvoRoot>
o (...)
o /templates
/xhtml(defaulttemplateset)
/my_custom_template
o /themes
/default(defaulttheme(CSS)set)
/my_custom_theme

Assoonasyoucreatethesefolders,theywillbeavailableforactivationwithin
Admin>>Layoutsection.Youcanalsohavemultiplethemesforonetemplate
setandviceversa.
VivvoCMSTemplateDesignGuide 5

6 [VIVVOCMSTEMPLATEDESIGNGUIDE]

AniceexampleofmultiplethemesforonetemplatesetisVivvoGreen/Orange
themeset.
ThesethemesaremadefordefaultVivvotemplateset,andaftertheir
installation,withinseconds,youcanchangeyoursitefromdefaultgraytoorange
orgreencolorscheme.
AnexampleofmultipletemplatesforonethemesetisourLayoutsavailablefor
downloadonResourceCenter.
Basically,theseareindividualframetemplatesusedforhomepage,articleand
categorypage.
Afterdownload,theybecomeavailableforactivationfromLayoutsectionof
Vivvoadministration,andwithasimpleclick,youcanchangethelayoutofyour
Vivvofrontendfromthreecolumnstotwocolumnlayout.
Note:PleasereadfollowingknowledgebasearticletoinformaboutfreedownloadsfromVivvo
ResourceCenterhttp://www.vivvo.net/resources/knowledgebase/accessdeniedtodownload
center.html

Page 6 of 14

Version1.0|2009Spoonlabsd.o.o.

[VIVVOCMSTEMPLATEDESIGNGUIDE] 7

PartII:BasicTheming,WidgetsandLayouts
Tominimizetimeneededtodevelopanddeploywebsites,eachVivvolicense
holderisgrantedaccessToVivvoResourceCenterwhereyoucanfindvarietyof
freetemplateandthemesets,individualtemplatelayouts,widgets,pluginsand
muchmore.
Numeroushomepage,categorypageandarticlepagelayoutsareavailable,such
as:

Equalright(homepage)
Twobythree(homepage)
Twocolumn(homepage)
Equalright(category)
Fourbytwo(category)
Twocolumn(article)
Equalright(article)

andmuchmore.
Combiningthesevariousframetemplates,youllhaveastartingpointfor
developing,forexample,twocolumnwebsitewithinminutes.
Letssayyouwanttohavetwocolumnwebsiteusingdefaulttheme,oryouwant
tostartdevelopingyoursiteasatwocolumnlayout.
AllyouhavetodoislogintoyourVivvoAdministration,gotoLayoutsection,
andontheleftside,underIndividualframelayoutsclickonHomepage
layouts.
Next,underRemotetabontherightside,findTwocolumnandclickoninstall
icontodownload/installthislayout.
Afterthat,youcanactivateitfromDownloadedtabbyclickingonactivate
icon.

Thesameprincipleisusedforallotherlayouts.
Youcanalsohaveindividuallayoutsforeachcategoryonyourwebsite.
Afterdownloadingandinstallingcategorylayouts,theybecomeavailablewithin
CategoriessectionofyourVivvoadministration.
Toactivatethelayoutforspecificcategory,choosedesiredcategoryfromthe
treeontheleftside,andontheright,underAdvancedoptions,chooseyour
layoutfromCustomlayout(overridesdefault)optionslist.
Youcanalsochoosearticletemplateusedtorepresentarticlelayoutofthat
category,andeventhemeifyouwishtoapplydifferentthemeonsomespecific
category.
VivvoCMSTemplateDesignGuide 7

8 [VIVVOCMSTEMPLATEDESIGNGUIDE]

IfyoucantfindwhatyouarelookingforonResourceCenter,youcaneasily
createframetemplateonyourown,whetheritsforhomepage,articlepageor
categorypage.
Forexample,tocreateanewcategorytemplate,firstchooseonefromResource
Center(oryoucanjuststartformdefaultone)thatisclosesttowhatyouare
lookingfor.
Duplicateit,andsaveitundertemplates/TEMPLATE_SET_NAME/category
folder,givingitappropriatenameforeasiervisualizationofhowthetemplate
lookslikeandforwhichcategoryisused(forexample
two_column_entertainment.tpl).
Next,chooseitasacustomlayoutasexplainedabove,andcustomizeitfurtherto
matchyourneeds.
YoucancustomizeyourtemplatefromLayoutsection,byclickingonedit
iconnexttolayoutname.

Bearinmind,builtinVivvotemplate/themeeditorismostlyusedforquick
editingtemplatesandcssfiles,ifyouwishtogetdeeperintocustomization,
usingothereditorsuchasDreamweaverorNotepad++ishighlyrecommended.

Page 8 of 14

Version1.0|2009Spoonlabsd.o.o.

[VIVVOCMSTEMPLATEDESIGNGUIDE] 9

VTEandMagic

VTElanguageisXMLbasedanditconsistsoftagsandattributes.ItusesVTE
namespaceandcanbemixedwithanyotherXMLlanguage(ie.xHTML).Each
VTEtemplatemustbewellformattedXMLdocument,anditmustnotcontain
XMLheadingandDoctype.
VTEhasonly14instructionsforloadingandmanipulatingdata,assigning
customJSandCSS,buildingcontrolstructures.Inordertofetchspecificdata,
VTEusuallyinteractswithVivvomodules.
FordetailedreferenceonVTElanguageitself,pleasereferencetheDeveloper
Wiki:http://wiki.vivvo.net/devdoc/vte
InthispaperwewillcoveronlybasicsofVTEthrubox_article_listmodule,asitis
themostusedone.

Since70%ofdefaultVivvoinstallationconsistsofvariousarticlelists,well
explainabasicarticlelisttemplateandhoweasyistoadjustbothparameters
arraytofetchcontent,ortemplatetodisplaythedata.
Belowisanexampleofabasicarticlelistthatwillfetchandprepareforoutput
10latestarticlesindescendingorderfromspecificcategories(referencedby
theirIDsinthisexample1,3and5).Itwillthendisplaythearticlesusing
defaultsummarytemplate(summary/default.tpl):

<vte:boxmodule>instructstheenginetoloadbox_article_listmodule,and
operateswithinthescopeofthatmodule.

VivvoCMSTemplateDesignGuide 9

10 [VIVVOCMSTEMPLATEDESIGNGUIDE]

Paramsarraydoesthefollowing:

search_sort_bywithvaluecreatedsortsarticlesbydatetheyarecreated.
search_orderwithvaluedescendingsortsarticlesbydescendingorder.
search_cidwithvalues1,3,5specifiesfromwhichcategoriesarticlesare
pulled.
search_limitwithvalue10limitsarticlelisttoonly10articles.
add_to_printedwithvaluetrueflagsarticlesasdirtyorusedsotheydo
notreappearonthesamepageagaininsomeotherbox.
exclude_printedwithvaluetrueinstructsmodulenottousedirty
articles.

Acompletelistofparametersforbox_article_listcanbefoundhere:
http://wiki.vivvo.net/devdoc/modules/box_article_list
Ok,sowepreparedanarticlelistbasedonourcriteria(actuallyweformedaSQL
queryusingalmostnaturallanguage),andalsoinstructedthetemplateengine
howtohandlethisdata.
Now,letsdosomequickmagic.Sayyouwantaquickchangeofarticlelistabove
todisplayonlyarticletitles,insteadofTitle+Image+Summary.Onlythingyou
needtodoistellthisboxwhichsummarytemplatetoload.Simplyrename
default.tpltotitle_only.tplwithin<vte:include/>line,andvoilthatsit!Your
templateoutputlookstotallydifferentwithonlyonelinechanged!
Youcancreateindefinitenumberofsummarytemplates,andloadthemwithin
box_article_listtorepresentyourarticlesindifferentways.
Note:Allsummarytemplatesarestoredwithin
/templates/TEMPLATE_SET_NAME/summaryfolder

ForcompletelistofVTEinstructionspleasereferencetheDeveloperWiki:
http://wiki.vivvo.net/devdoc/vte/getting_started#vtetagsinstructions
Youcanalsoreferencesomeexamplesofcreatingcustomboxarticlelistshere:
http://wiki.vivvo.net/devdoc/vte/creatingcustomboxarticlelist

Page 10 of 14

Version1.0|2009Spoonlabsd.o.o.

[VIVVOCMSTEMPLATEDESIGNGUIDE] 11

TemplateFilesandTemplates

Inthissection,welltrytoshowyouthestructureoftypicalframetemplateusing
homepagetemplateasexample.Also,youlllearnbasicsbehindsomeofthemore
importantCSSfiles.

Startinghomepage/default.tpl

AniceexampleofhowtheVivvohomepageisconstructedcanbefoundonour
developerWiki:http://wiki.vivvo.net/_detail/devdoc/vivvotemplate
structure.png?id=devdoc%3Atemplates
ThisexampleshowsyouthelogicbehindallVivvoframetemplates:
1. Frametemplate(inthiscasehomepage)
2. Individualboxtemplates(usuallycontent/articlelists)whichareloaded
withVTEincludestatement
Typicalframetemplatehasfollowingstructure:

Openingsystempartconsistsof:
o Opening<html>tag
o Includeforhtml_header.tpl(locatedinsystemfolder),whichis
basicallyentire<head>partofyourpage(pagetitle,METAs,
includesforCSSandJavaScriptfiles,etc.)
o Opening<body>tag
Containerblockincludes:
o Headertemplate
o Contentblockthisblockincludesyourleftcolumn
(dynamic_box_left),centercolumn(dynamic_box_center)and
rightcolumn(dynamic_box_right)
o Footertemplate
Closingsystempartconsistsof:
o Closing</body>tag
o Closing</html>tag

HeaderandFootertemplates

Bothheaderandfooterarereusablecomponentsandhavesystemwiderange.
Eventhoughyoucanhavemultipleheaderandfootertemplates(i.e.different
headersforhomepage,articlepage,categorypage,etc.),itshighly
recommendedtokeepthemuniqueforeasiersystemmaintenance.
Youcanfindyourheaderandfootertemplatesin
templates/TEMPLATE_SET_NAME/boxfolder.
VivvoCMSTemplateDesignGuide 11

12 [VIVVOCMSTEMPLATEDESIGNGUIDE]

Styles

AllstylesheetfilesofVivvothemearelocatedinthemes/THEME_NAME/css
folder.SinceVivvohascompletelyCSSbasedlayoutallstylesofawebsiteare
separatedfromthecontentitself.
ForbetterperformanceandfasterloadingallfileswithinCSSfolderare
compressedandmergedintosingleoutputusingcompress.phpfile.
Inthissection,weregoingtomentionjustfewofthemainfilesandtheirusage,
forcompletelistpleaserefertohttp://wiki.vivvo.net/devdoc/css.
Firstandoneofthemostimportantfilesislayout_default.css.
Thisfilecontains,stylesforvariouslayouts,including:

Defaultthreecolumnlayout
Twocolumnlayout
Layoutwiththreeequalcolumns

Andcouplemore.
Eachlayoutiscarefullyconstructedtosupportvariousbannersandadssizesout
fromthebox.
Forexample,ifwetakedefaultthreecolumnlayout,youllseethatrightcolumn
supportsbannersupto250x250px,leftcolumnisidealforskyscraperbanners
(120x600and160x600px),andcentercolumnwillholdstandard468x60px
banners.
Ifyouwishtoknowhowtoapplyquicklayoutchangetoyoursite,pleasereferto
http://wiki.vivvo.net/devdoc/css#layout_default.css.

Next,wehavestyle.css.
Asitsnamesays,thisfilecontainsmajorityofVivvofrontendstylessuchasfont
families,fontsizes,liststyles,boxstylesetc.
Thisiswhereyoullbespendingmostofyourtimepaintingyourwebsite.
Foreasierunderstanding,thisfileisintersectedwithnumerousinlinecomments
thatcanbecategorizedintwogroups
1. SectioncommentssuchasGLOBALSTYLES,HEADERSTYLES,FOOTER
STYLES,RIGHTCOLUMNSTYLESetc.Thesecommentsareallin
UPPERCASE.
2. ExplanationcommentssuchasLists,Latestcommentsbox,Globalbox
styles,Globalheadingstylesetc.Thesecommentshaveprettymuchself
explanatorymeaning.
Forexample,stylesusedforloginboxislocatedunder/***LoginBox***/comment.

Page 12 of 14

Version1.0|2009Spoonlabsd.o.o.

[VIVVOCMSTEMPLATEDESIGNGUIDE] 13

FinalstylesheetthatIwouldliketomentionhereisprint.css.
Thisstylesheetcontrolsyourarticleprintpage,andwhatitdoesisbasically
takesarticletemplate,andstripitsstylestobarebones(ahthepowerofCSS)
makingitprinterfriendly.
Understandingthisfilerequiresunderstandingyourarticletemplateandstyles
andclassesusedinthatpage.
Forexample,ifyouwishhideimageshowninprintpage,allyouhavetodois
modify#article_bodydiv.imageselector,andinsteadofexistingstylesplace
display:none;property.
Thesamecanbeappliedtoallnewelementsthatyouareaddingonyourarticle
template(bannersincentercolumn,imageshardcodedwithintemplate,etc.),
youjustneedtopinpointthatelementusingCSSselectors,andapply
display:none;property.
ExcellenttutorialaboutCSSselectorscanbefoundhere
http://css.maxdesign.com.au/selectutorial/.

Tip:Whendevelopingyourtheme,itshighlyrecommendeddisablingyour
compress.php(renameittemporarily)andusingFirebugextensionforFirefox.
Thatway,youllbeabletoinspectandseefromwhichfileisspecificclassused.

DownloadFirefox
DownloadFirebug
IntroductiontoCSSeditingusingFirebugvideo

VivvoCMSTemplateDesignGuide 13

14 [VIVVOCMSTEMPLATEDESIGNGUIDE]

Conclusion/FurtherReference

This paper covers basic principles of Vivvo template architecture, template

engine (VTE) and styles. It is basic/intermediate level and aimed towards web
designers and system integrators. For future reference, we recommend
exploring our Developer Wiki resources (http://wiki.vivvo.net/devdoc) and
reading other datasheets and white papers on our Resource Center
(http://www.vivvo.net/resources/articles/whitepapers/index.1.html).

Page 14 of 14

Version1.0|2009Spoonlabsd.o.o.