Skip to main content

This site requires you to update your browser. Your browsing experience maybe affected by not having the most up to date version.

Archive /

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

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

Clearer documentation on how themes and templates work?


Reply


5 Posts   7256 Views

Avatar
CubeDave

Community Member, 8 Posts

19 November 2008 at 4:07pm

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

Avatar
Hamish

Community Member, 712 Posts

19 November 2008 at 5:02pm

Edited: 19/11/2008 5:12pm

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? :D

Avatar
CubeDave

Community Member, 8 Posts

20 November 2008 at 11:11am

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

Avatar
Willr

Forum Moderator, 5513 Posts

20 November 2008 at 7:49pm

Edited: 20/11/2008 7:50pm

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 :)

Avatar
CubeDave

Community Member, 8 Posts

20 November 2008 at 9:23pm

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