Jump to:

17452 Posts in 4473 Topics by 1971 members

Archive

SilverStripe Forums » Archive » Clearer documentation on how themes and templates work?

Our old forums are still available as a read-only archive.

Moderators: martimiz, Sean, biapar, Willr, Ingo, simon_w

Page: 1
Go to End
Author Topic: 7130 Views
  • CubeDave
    Avatar
    Community Member
    8 Posts

    Clearer documentation on how themes and templates work? Link to this post

    Hi,

    I'm new to silverstripe and I've been trying to work out how the whole thing hangs together without much luck. Things seem to work for a bit, but I change something and they break again!

    I need to build my own theme. But I don't understand the following things:

    * What causes SS to load a particular .ss file for a given page. I know that in the page controller's index function I can call renderWith("templatename"), but how does SS know where to find the file? Is it always under mysite/templates?
    * While we're on the subject, how does SS know to look in the mysite folder? Is that hardcoded, or can I change it?
    * What is the effect of calling SSViewer::set_theme()? in _config.php, and when is _config.php loaded? Is it only at database re-build time?
    * What is the significance of the 'Layout' folder in the default blackcandy template? I notice a $Layout in the page.css in blackcandy/templates, but I thought that this would call a function on the page's class. Can it also invoke another template in the layout folder?

    None of this seems to be explained in any of the documentation I can find. Is there some more documentation I should be looking it? I'd love to use SS because it seems nice, but I'm very close to giving up and going back to modx (which is perverse but at least I more or less understand how it works).

    -dave

  • Hamish
    Avatar
    Community Member
    712 Posts

    Re: Clearer documentation on how themes and templates work? Link to this post

    Yeah, the documentation needs a lot of love.

    My responses might not be 100% correct, but here goes:

    * What causes SS to load a particular .ss file for a given page. I know that in the page controller's index function I can call renderWith("templatename"), but how does SS know where to find the file? Is it always under mysite/templates?

    Basically, lets take an example page type, called "ArticlePage". An ArticlePage extends Page.

    SilverStripe renders the page like this:

    1. Look for templates called ArticlePage.ss in the theme templates directory. So, if your theme is set as 'blackcandy', it looks for 'themes/blackcandy/templates/articlepage.ss'

    2. If it can't find it, it will then look for 'articlepage.ss' in the templates folder in the same folder tree as the atriclepage.php. Ie, for the page 'mysite/code/articlepage.php' it will look for 'mysite/template/articlepage.ss'

    3. If it can't find, it repeats the process for subsequent class inheritances - ie, it will look for '/themes/blackcandy/templates/page.ss', then '/mysite/templates/page.ss'

    When you use renderWith(), SilverStripe will go find your template using a similar scheme as above (ie, try the themes folder first).

    This is clever, because then you can create themes (in the themes dir), but also create templates specific to the project (in your project dir), or even apply templates programatically (with renderWith())

    * While we're on the subject, how does SS know to look in the mysite folder? Is that hardcoded, or can I change it?

    It's just the folder with your _config.php file in it. You can change 'mysite' to 'bananamonkey' if you like, your site will still work exactly the same (after you have done a db/build?flush=1)

    * What is the effect of calling SSViewer::set_theme()? in _config.php, and when is _config.php loaded? Is it only at database re-build time?

    It just tells SilverStripe where to look *first* for template files. It doesn't effect your database, just the cached output files and subsequent rendering.

    * What is the significance of the 'Layout' folder in the default blackcandy template? I notice a $Layout in the page.css in blackcandy/templates, but I thought that this would call a function on the page's class. Can it also invoke another template in the layout folder?

    Yes.

    The layout are just like page templates but for smaller snippets of the page. For example, You could create a 'articlepage.ss' layout template (in the layout folder) - and NOT have an 'articlepage.ss' page template (in the templates folder). When building the page, SilverStripe will render the PAGE with the page.ss template, and the LAYOUT section with the articleholder.ss template.

    Does this help, or is it just confusing?

  • CubeDave
    Avatar
    Community Member
    8 Posts

    Re: Clearer documentation on how themes and templates work? Link to this post

    That was extremely helpful thanks very much.

    However one huge problem remains, which I've seen mentioned a few times on this site, and that is that silverstripe is *incredibly* slow.

    It's easily the slowest web application I've ever used. It's slower than every other CMS i've used, and it's even slower than using the control panel app on my web provider!

    I followed a bit of advice I found somewhere in these forums to change some code in ManifestBuilder so that the manifest is rebuilt only when 'flush' or 'buildmanifest' is set. This helped, but even with that change it's still terrible.

    I use 'debug_profile' and I've seen times as long as 11 seconds to run "Director direct"! I cannot understand where this time could possibly be going!

    Anyway I'll keep trying but if I can't fix this speed issue then it's back to modx I go (albeit with a heavy heart..)

    -dave

  • Willr
    Avatar
    Forum Moderator
    5464 Posts

    Re: Clearer documentation on how themes and templates work? Link to this post

    CubeDave, what are you trying to run SS on? It is a fairly bulky system, running it on a shared host, if thats what you have you might like to look at gzip compression or mod_deflate etc.

    And note we are currently replanning and rewriting all the current documentation but it is a slow slow process

  • CubeDave
    Avatar
    Community Member
    8 Posts

    Re: Clearer documentation on how themes and templates work? Link to this post

    I totally understand about the documentation, and having examples and of course all the source code mitigates that to some extent

    But its the performance that's the issue - it's running on a shared server yes - but not one that's unduly loaded (as far as I know). The amount of time spent in the director and controller parts of the profile output are very large (seconds!) which seems crazy.

    Does SS do alot of disc access? Using the filesystem as a database to some extent? While its doing things like looking for the template files? Or is that the function of the manifest file?

    -dave

    7130 Views
Page: 1
Go to Top

Want to know more about the company that brought you SilverStripe? Then check out SilverStripe.com

Comments on this website? Please give feedback.