razorCMSDevelopmentExtensionsThems(V3.X.

X)
razorCMSDevelopment
Extensions
Themes
(V3.X.X)
Author Role Handle
PaulSmith Author smiffy6969,razorcms,razor
Revision Changes Date
1.0 InitialcreationonGoogleDocs 03/2014

Page1of14
razorCMSDevelopmentExtensionsThems(V3.X.X)

Contents
Contents
razorCMSExtensionDevelopment
Preface
Introduction
Whatisathemeextension?
Gettingstartedwithcreatingthemes
Alteringanalreadyexistingtheme
1.Alterthefilestructure
2.Configurethemanifests
3.Alldone,nowmakeyourthemelookhowyouwantitto
ThebasicsofthemesinrazorCMSV3
Views
Style
Thatsitreally,itsuptoyounow
Feedbackandhelpingout
Signingoff

Page2of14
razorCMSDevelopmentExtensionsThems(V3.X.X)
razorCMSExtensionDevelopment
Preface
ThisdocumentissupposedtobeanintroductiontocreatingthemesinrazorCMSV3.X.Xandisprimarilyto
serveasawaytogettheprocessoutthereuntilitcanbesuckedintoawebsite,inaclearmanageableway.
Untilsuchtime,allextensiondevelopmentcanbereferenceinthedevelopmentdocs.

Page3of14
razorCMSDevelopmentExtensionsThems(V3.X.X)

Introduction
Whatisathemeextension?
AthemeextensionissimplyaspecifictypeofextensionusedtocontrolthemesinrazorCMS.Thethemesare
generallysplitintotwomainareas,systemandtheme.systemextensionscomeinlotsofareas,like
communication.Themesareasimplyaspecificareaofextensiontypethatwehandleseparatelytoother
extensions.
Themeextensionscontainalltherequiredfilesneededtorunatheme,allinonenicelittlepackage.Themes
mayincludestyle(less,css,pleasenotelessfilesmustbecompilemanuallybutbundledforeasilychanging
stylelater),php,views(phpfileswithhtmlandphppagestructure),images,javascriptandfinallyamanifest
(jsonfiletodetailtheextensiondetails,informationonlayoutsandameansofidentifyingeachtheme/layout).
Astandardthemeshouldconsistofatleastthefollowing,inthisfolderlayout:
extension
theme
handle(suchasrazorcms)
themename(yourthemenameseparatedbyhyphens)
images
(anyimagefilesusedbyanyofthelayouts)
style
(anylessandcssfilesusedbyanyofthelayouts)
view
layoutname.php(yourthemeslayoutasdetailedinmanifest)
layoutname2.php(youmayhavemultiplelayouts)
layoutname.manifest.json(Yourfirstlayoutsmanifestfile)
layoutname2.manifest.json(anyotherlayoutmanifests)
Thisisthemostbasicstructureshowingyoutheabilitytousemultiplelayoutsforeachtheme.Infactyouare
encouragedtocreatedatleast3ormorevariationsforpeopletochoosefrom.Eachlayoutmayhaveitsown
style,imagesetc,butitismuchmoreconservativetocreateamasterstylefile,thenusebootstrapsgrid
systemforsettingthelayoutup.Thisapproachworkswellandcutsdownontheamountofseparatestyling.
Alsoitisagoodideatorememberwearemobilefriendly,pleaseensureyoursystemusesthebootstrap
layoutmarkupinordertoplaynicewithmobiles.

Page4of14
razorCMSDevelopmentExtensionsThems(V3.X.X)
Gettingstartedwithcreatingthemes
BeforeyoucanpublishanythemesontherazorCMSwebsite,youwillhavetoregisteryourhandle.Untilsuch
timeIcangetaniceregistrationpagesetup,Isuggestwedothisadhocviaemail,Icanbecontactedviathe
websitecontactform,sountilthenletsdoitthisway.
Dropmeanemailstatingyourhandle,ifitisavailableIwillreserveitforyou,thiswillbeameansasto
identifyingandgroupingextensionstogether.Youdonthavetodothis,ofcourse,butifyouwishtopublish
yourtheme(andgetsomefreeadvertisingforyoursite)ontherazorCMSsiteIwillonlydothisforthosewith
validhandles.Theonlyexceptionstohandlenamesare,nottouserazorcms,razor,smiffy6969,
administrationoradmin,thesearemyreservednames.Letstrytokeepthiscleanpeople,Iwillnotpublish
rude,offensiveorderogatoryhandles.
Onceyouhaveyourhandleregisteredwithme,youaremorethanwelcometopassonanythemes,Iwillthen
publishthesetotherazorCMSwebsiteasIcanfindthetime.
Thebestwaytostartcreatingyourthemeistotakeonethatalreadyexistsandcopyit,forthistoworkwecan
useanythemewelike.Whatbetterprocess,thantakingathemethatcloselyresembleswhatyouwantlayout
wise,thenalterit.UsingthismethodIamabletocreatethemesinhalfanhourorless.Iwilldemothisprocess
herebasedonthedefaultextratheme,designedtobeanadditiontothedefaulttheme,butyoucoulduseany
oftheavailablethemesfromtherazorCMSwebsite.

Page5of14
razorCMSDevelopmentExtensionsThems(V3.X.X)
Alteringanalreadyexistingtheme
Thefirstthingweneedtodoiscopythethemetoanewlocation.Onyourdesktop(orwhereveryoulikefor
thatmatter).Downloadthedefaultextrathemefromthewebsite,extractittodesktop,andwecanstartto
configureit.
1.Alterthefilestructure
Youwillnoticethedefaultextrathemeissavedinthefoldernamedrazorcms.ThisisthehandleIusefor
extensions.ThehandleshouldberegisteredwithrazorCMSifyouwanttopublishonthesite,fornowwewill
giveyouthedefaulthandledave.
Changetherazorcmsfoldernametodave.
Nextweneedtogivethethemeaname,wewillcallthisdavesnewtheme.Changethefolderinsidethe
davefoldercalleddefaultextraandchangethistodavesnewtheme.
Youshouldnowhavethefollowingstructure.
extension
theme
dave
davesnewtheme
images
style
style.css
style.less
style_ie8.css
style_ie8.less
style_ie9.css
style_ie9.less
view
1column.php
2column.php
3column.php
1column.manifest.json(matchesthe1columnlayout)
2column.manifest.json(matchesthe2columnlayout)
3column.manifest.json(matchesthe3columnlayout)

Page6of14
razorCMSDevelopmentExtensionsThems(V3.X.X)
2.Configurethemanifests
Wenowneedtoconfigurethemanifests(thisisathreelayouttheme),withyourdetails.Openeachmanifest
fileandchangethefollowingdetails.Soyouwillneedtorepeatthisstepthreetimesfor1column.manifest.json,
2column.manifest.jsonand3column.manifest.json.
Forthetimestamp,created,visithttp://www.unixtimestamp.com/andgetanewtimestamp
Changethesevalues,leavingtherestastheywhere:
{
"handle":"dave",
"extension":"davesnewtheme",
"name":"DavesNewTheme",
"author":"dave",
"version":1,
"created":1394394028,
"description":"Thisisdavesnewthemeanditsreallygood.Ithas3layouts."
}
Asdetailedearlier,youwillneedtoconfigureallthreemanifests(ensureyoudonotmessupthelayout
names).
Thisisallyouwillneedtochangeinordertoconfigurethemanifest,foradetailsdescriptionofallfields,see
below:
manifest:Thisisthemanifestfilename,whichmatchesthelayoutname,placeinquotes.
type:Thisisthenameoftheextensionarea,forthemes,itstheme,placeinquotes.
handle:Yourhandle,registeredwithrazorCMSifyouwanttopublishtoourwebsite,placeinquotes.
extension:Yourthemename,placeinquotes.
layout:Thelayoutname,whichshouldmatchmanifestname,andphpviewname,placeinquotes.
name:Anicereadablenameforyourtheme,pleasewriteasatitle,placeinquotes.
author:Yourhandle,asyouregisteredit,placeinquotes.
version:Yourversionnumber,pleaseusewholeintegers(e.g.1,2,3),noquotes.
created:Timestampofcreationdate(asabove,inred),noquotes.
description:Agooddescriptionofyourtheme,pleasebeinfromative,500wordsmax,placeinquotes.
menus:["header","footer"],Anarrayofmenususedinthislayout.
content:{"header":1,"main":1,"footer":1}Anobjectdetailinglocationcolumns(howmanycolsperlocation).

Page7of14
razorCMSDevelopmentExtensionsThems(V3.X.X)
3.Alldone,nowmakeyourthemelookhowyouwantitto
Nowyouhaveyourbasiclayoutandmanifestsconfigured,youshouldbeabletoinstallthisthemeinto
razorCMS.Youcaninstallthethemeasyouwouldanytheme,justsimplycopytheextensionfolderthat
containsthetheme,directlyintothewebrootofyourrazorCMSinstall,merginganyfolders.
Onceinstalled,logintoyourwebsitebyappending/logintotheendoftheURL,chooseapagetousethenew
themeon(thesecondpageonafreshinstallhassomegoodtestoutputonit),clickthedashboardiconand
selectthenewthemeandsave.Onceloaded,youmaynowstartalteringtheviewfilestoconfigurethe
template,andalteringtheless/cssfilestoconfigurethestyle.
Pleasenote,wetrytouselesstowritestylesheets,itsnicer,cleaner,easiertoreadandhaslotsofbenefits.
Ensureyoucompileanylessfilestocssbeforetesting,andpleasesupplylessfileswithyourthemes.

Page8of14
razorCMSDevelopmentExtensionsThems(V3.X.X)
ThebasicsofthemesinrazorCMSV3
Themesaregenerallysplitintothreeparts,youhavetheviews(thelayoutPHPfiles),youhavethestyle(we
writelessandcompiletocsstobeusedinthelayoutviews)andwehavetheaccompanyingassets(js,
imagesetc.).
Views
ThesearePHPfiles,generallyahtmltemplateviewcreatedasaPHPfiletotakeadvantageofserverside
processing,likesettingbasepaths,outputtingmenus,contentandotherfunstuff.Thefileislaidoutmuchlike
aHTMLfilewiththeadditionofPHPtagsincertainplaces.
Thereareafewthingsyouneedtobeawareofwiththeviews,liketheuseofacustomopeningbodytag.This
isveryimportantandthebasisbehindallowingtheangularJSoverlaytobeinsertedinformanagingthe
website.Ifyoumissthisout,youwillhavenoadminpanels.
Insteadofhavinganopeningbodytag,weusethefollowing,thencloseitnormallyasfollows:
<?php$this>body()?>
</body>
Thenextisthatwerequirecertainattributesonthehtmltag,tohelpangularJSout
<htmlxmlns:ng="http://angularjs.org"id="ngapp">
</html>

Page9of14
razorCMSDevelopmentExtensionsThems(V3.X.X)
Finally,werequirecertainassetsloadedinordertomakethesystemfunctioncorrectly,aswellasspecific
metatagsset.PleaseensureanyofyourassetscomeAFTERthedefaultassets.
<head>
<metacharset="utf8">
<metaname="viewport"content="width=devicewidth,initialscale=1">
<metaname="description"content="<?phpecho$this>page["description"]?>">
<metaname="keywords"content="<?phpecho$this>page["keywords"]?>">
<title><?phpecho$this>site["name"]?>::<?phpecho$this>page["title"]?></title>
<link
href='http://fonts.googleapis.com/css?family=Open+Sans:400italic,600italic,700italic,800italic,400,700
,800,600'rel='stylesheet'type='text/css'>
<!resolvebaseURL/IP/UAGENTforanyjsapplications>
<scripttype="text/javascript">
varRAZOR_BASE_URL="<?phpechoRAZOR_BASE_URL?>"
varRAZOR_USERS_IP="<?phpechoRAZOR_USERS_IP?>"
varRAZOR_USERS_UAGENT="<?phpechoRAZOR_USERS_UAGENT?>"
varRAZOR_PAGE_ID="<?phpecho$this>page['id']?>"
</script>
<!requirejs>
<script<?php$this>data_main()?>src="<?phpechoRAZOR_BASE_URL
?>library/js/require.js"></script>
<scriptsrc="<?phpechoRAZOR_BASE_URL?>library/js/requireconfig.js"></script>
<!loadbootstrap,styleoverridesandpubliccss>
<linktype="text/css"rel="stylesheet"href="<?phpechoRAZOR_BASE_URL
?>library/style/razor/razor_base.css">
<![ifIE9]><linktype="text/css"rel="stylesheet"href="<?phpechoRAZOR_BASE_URL
?>library/style/razor/razor_base_ie9.css"><![endif]>
<![ifIE8]><linktype="text/css"rel="stylesheet"href="<?phpechoRAZOR_BASE_URL
?>library/style/razor/razor_base_ie8.css"><![endif]>
<!loadyourthemestylehere>
<linktype="text/css"rel="stylesheet"href="<?phpechoRAZOR_BASE_URL
?>/extension/theme/razorcms/davesnewtheme/style/style.css">
<![ifIE9]><linktype="text/css"rel="stylesheet"href="<?phpechoRAZOR_BASE_URL
?>/extension/theme/razorcms/davesnewtheme/style/style_ie9.css"><![endif]>
<![ifIE8]><linktype="text/css"rel="stylesheet"href="<?phpechoRAZOR_BASE_URL
?>/extension/theme/razorcms/davesnewtheme/style/style_ie8.css"><![endif]>
</head>
Soasyoucanseethereisalottoensureyougetright.Tobehonest,ifyoucopythedefaultextratheme,you
onlyneedtoremembertochange3thingshighlightedinredabove,thatsthelocationtoyourcssfiles.
Youwillnoticeafewthingsintheheadsection.Likeweareusingphptoloadcertainvaluesinmetadata,using
ittoconfiguretheloadpointforrequireJS(toloadtheadminoverlays),weuseconstantstogetthebasepaths
andbaseurls,aswellasusingconditionalcommentstoaddtothemesforIE8andIE9(YesIknowwedonot
supportIE8,butothersmaywanttosupportitforthepubliclyviewablesite,nottheadminoverlays).UsetheIE
overridestylefilestotweakthethemeforIE8and9.IE10andupshouldbeprettycompatible.
Page10of14
razorCMSDevelopmentExtensionsThems(V3.X.X)
Movingontothebodyarea,again,dontforgetthatcustombodyopeningtag,Icannotstressthisenough.If
youarenotawareofbootstrap,Iwouldgetusedtoitnowhttp://getbootstrap.com/asitwillsaveyouthemost
amountoftimeever,Iamserious,learnit.Onceyouhavelearntit,youmaybetterunderstandthemarkupin
thebodyarea.
Weuseversion3andupofBootstrap,souseyournewpowerstosetoutthethemeasyouwish,usethe
powerofthegridsystemtolayoutyourpageandmakeitmobilefriendlyto.
TheonlyrealthingIneedtopointouthereishowtoloadthemenusandcontent.
<ulclass="navnavpillsmobilehideblock">
<?php$this>menu("header")?>
</ul>
Thiswillloadaheadermenu,ifoneispresentinthesystem.Thethreemainmenusareheader,mainand
footer.AtpresenttheALPHAversiononlyallowsthesemenustobeused,buttheBETAversionwill
automagicallycreateanynewmenusyouadd.Basically,ifitcannotfindthemenu,itwillcreateitforyou.This
willallowyoutoaddmenussimplybyaddingthesnippitaboveinyourview.
Fortheinterestsofinteroperabilityacrossthemes,pleaseuseheader,mainandfooterformainnavigation.
Onlyresulttoaddingcustomnamesforspecialnavigation.Thiswillensurethatwhenpeopleswapthemes,
theydonotloseallnavigation.
Thenextthingtopointoutisthis.
<?php$this>content("main",1)?>
Thislittlesnippitwillloadcontent,itwillloadanycontentfromthemainareacolumn1.Thecontentlocations
aresplitintoareasandlocations.Thethreemainareasareheader,mainandfooter.Youmayonlyusethese
locations.Howeveryoumayhaveasmanycolumnsasyouwish.Pleaseordercolumnsintheorderof
importance.BythisImeanplacecolumn1inthemostimportantplaceofthearea.Forthemainarea,column
1isusuallythelargestcontentarea.Columns2and3wouldprobablybeleftorrightsidebars.
Againyoumayhaveasmanyasyoulike
<divclass="row">
<divclass="colsm6">
<divclass="templatemaincontent">
<?php$this>content("main",1)?>
</div>
</div>
<divclass="colsm6">
<divclass="templatemaincontent">
<?php$this>content("main",2)?>
</div>
</div>
</div>
Thatsitreally,youshouldbeabletolayoutyourviewnowinabootstrapfriendlywayandgetthemostoutof
bootstrap,overridingthedefaultlookandfeelforsomethingmoreunique.
ThelastthingIwanttofinishonhereisthedefaultstyle.Wefirstloadthebootstrapstyling,extendthis(we
Page11of14
razorCMSDevelopmentExtensionsThems(V3.X.X)
couldusemixinshere,Imayswaptothislateratsomepointtobeabletoaltermixins,thismaymakeitto
BETA).Youshouldbeabletousethefollowingstylesforcontrollingwhatyoushoworhideformobile/desktop.
//showonmobile
.mobileshowblock
.mobileshowinlineblock
.mobileshowinline
//hideonmobile
.mobilehideblock
.mobilehideinlineblock
.mobilehideinline
Theseclassesshouldallowyoutomanipulatetheviewfurtherformobile,likeshowingdifferentnavigation
menusorhidingcertaincontent.
Alsofontawesomeisinstalled,somakeuseofit(http://fortawesome.github.io/FontAwesome/),addthe
classestoaddtheicons
<iclass=fafatrash></i>
Style
Wearebasicallywritinglessfileshere,thencompilingthemmanuallyandsubmittingbothtothestylefolder.If
youuseSASS,wellsorry,IuseLESS,thatsitreally,nootherreason.SureyoucanuseSASSifyouwish,but
IwillonlyexceptLESSintotherazorCMSpublishedecosystem.Itissillytosupporttostylesheetlanguages
sowearegoingtosticktoLESS.
InanythemesentinforpublishingontherazorCMSwebsite,IexpecttoseeLESSandcompiledCSSfor
eachstylefile.IfyoudonotknowwhatLESSis,http://lesscss.org/thisshouldhelp.Itquitesimplywill
transformhowyouwriteyourstyle.Isuggestyougettoknowthisbeforegoingfurther.
Ifnothingelse,Iatleastexpecttoseehierarchicalstylewritten,likeso:
body
{
backgroundcolor:#F4F4F4
.templateheader
{
backgroundcolor:#F4F4F4
paddingtop:20px
paddingbottom:10px
borderbottom:1pxsolid#E2E2E2
.templateheadermenu
{
marginbottom:20px
}
}
}

Page12of14
razorCMSDevelopmentExtensionsThems(V3.X.X)
Wherepossible,itwouldbegoodtoputdefaultcolours,sizes,bordersetcinmixinsatthetopofthesheet
@lightgreybackground:#f4f4f4
body
{
backgroundcolor:@lightgreybackground
.templateheader
{
backgroundcolor:@lightgreybackground
paddingtop:20px
paddingbottom:10px
borderbottom:1pxsolid#E2E2E2
.templateheadermenu
{
marginbottom:20px
}
}
}
Thismakesadjustingthethemeeasierforyouandothers.Onceyouharnessthepoweroflessyouwillbe
knockingoutthemesextraquick.
SoyouwillbewritingLESSandcompilingtoCSSasyougo,wecoulddothisautomagicallyonfirstloadofthe
system,butIwouldrathersaveontheoverheadofthat,sowewillcompilemanually,Iwillnotsacrifice
overheadandloadingforlazynessoncompiles(wedonthavetodoitoftensoletsgetintothehabit).Youhave
afewoptionshere,createatasktodothisforyou(suchasgrunt)oryoucandothisthemanualway.Iuse
sublimetexteditor,thiscomeswithseveralLESScompileraddons(Iusenode.jsless),simplyinstalandctrl
+Bcompilestocss,Ithinkthelatestversionevenminifiesandaddsamapfile.
Ifyoucannotfindalesscompilerforyourtexteditorofchoice,Isuggestitistimetochange,sublimeisagood
placetostart.

Page13of14
razorCMSDevelopmentExtensionsThems(V3.X.X)
Thatsitreally,itsuptoyounow
Icanonlyopenthedoorforyou,nowyouneedtoexplorewhatcanbeachieved.Togetthemostoutofyour
theme,andyoursite,lookintotheresourcesincludedabove,youhaveafullscalable,colourableiconset,you
havethepowerofbootstrap,andthebeautyofLESS.
Feedbackandhelpingout
IfyouhaveanyfeedbackonrazorCMS,pleasedonthesitate,anyfeedbackisgoodfeedback,seriously,even
negativejustletmeknow.Icanbecontactedthroughthesupportforumthroughthehandlesmiffy6969or
throughtherazorCMSmainwebsitecontactpage.
Ifyouwanttooffermorethanfeedback,greatyoullmakemeveryhappy.Idoallthisfornothing,yougetall
myworkforabsolutelyzerocost,yesmywifethinksImnutsbutthatsnotthepoint.Ifyouwanttooffer
anything,beittime,yourexpertise,money,livestock,alcohol,moustachesorevenmunchiesIwillbeyour
friendforlifeandmoretothepointyoullhelpmefeedmychildrenwhilstprovingtomywifethatopensourceis
worthit.
Signingoff
Thatsaboutitfornow,ifyouthinkthismanualisutterpants(Iamtryingtodo30tasksatoncehere),have
spottederrorsinthemanualthinkyouwouldliketorewritethisforme.Pleaseletmeknow,someonemuch
morepassionateaboutwritingdocsissoverywelcometocomeandputmycardsinorder.
smiffy6969
www.razorcms.co.uk
ulsmith.net
Page14of14