(I think this is mostly aimed at Tim)...
I've been looking through the 2.0 block, theme and page designs and code, and I'm having a bit of a problem understanding block regions.
It appears that a theme can define its own regions and give them its own names. In the standard theme, there are two regions defined: 'side-pre' and 'side-post'. These appear to be analogous with 'left' and 'right' in pre-2.0 versions.
If I am adding blocks to a page using this theme, then the block has the strings 'side-pre' and 'side-post' stored in the default-region field.
Since a theme can define its own regions (it can, right?), what happens if a theme that doesn't support a region gets set to a page that has blocks in those regions?
Is there any plan to manage regions names at a central level? That is, we have two standard regions now. Will we setup a system to define others?
In particular, what about the centre region?
(and I admit, I may be misunderstanding some of this...)
mike
You seem to be understanding most of it.
The reason I went for 'side-pre' and 'side-post' is that whether they are displayed on the left or the right will depend on whether you have an LTR or RTL language.
Yes, names should be standardised.
For the central regions, I would suggest centre-top and centre-bottom if they are theme-provided regions. If blocks are being used as content on specific pages (that is, a particular script does $PAGE->blocks->add_extra_region('...')) we use names like my-content, home-content. I am thinking that in time the site front page and the my Moodle pages will just contain blocks - no hard-coded content.
Note that block regions have a fairly strict length limit in the DB, I think it is 16 chars.
To answer your question. Suppose you are using a theme that has a centre-top region, and you add a block there. Then you switch to a theme that only does site-pre and side-post. Well, you will notice that in the theme config file, as well as setting 'regions' => array('side-pre', 'side-post'), it also sets 'defaultregion' => 'side-post'. Any blocks from unrecognised regions go into the defaultregion. This is done at the end of blocks_manager::load_blocks.
The reason I went for 'side-pre' and 'side-post' is that whether they are displayed on the left or the right will depend on whether you have an LTR or RTL language.
Yes, names should be standardised.
For the central regions, I would suggest centre-top and centre-bottom if they are theme-provided regions. If blocks are being used as content on specific pages (that is, a particular script does $PAGE->blocks->add_extra_region('...')) we use names like my-content, home-content. I am thinking that in time the site front page and the my Moodle pages will just contain blocks - no hard-coded content.
Note that block regions have a fairly strict length limit in the DB, I think it is 16 chars.
To answer your question. Suppose you are using a theme that has a centre-top region, and you add a block there. Then you switch to a theme that only does site-pre and side-post. Well, you will notice that in the theme config file, as well as setting 'regions' => array('side-pre', 'side-post'), it also sets 'defaultregion' => 'side-post'. Any blocks from unrecognised regions go into the defaultregion. This is done at the end of blocks_manager::load_blocks.
Thanks Tim!
Makes sense for the 'side-pre' and 'side-post' names.
Any thoughts on how we should define and manage these? Should we maybe have a table somewhere, or a document page? Just thinking ahead... Maybe we have at least a number of standard areas that are most likely to be used and then allow themes to go wild after that?
I see the 16 character limit now... I wonder if that could be a problem going forward? We could easily end up with something like 'home-centre-content'. Maybe we should plan now to bump that up to 32 or 64?
Thanks for pointing me to the 'defaultregion' code. There could still be an issue if the theme doesn't define a 'defaultregion' though. Looks like in that case, and blocks with unknown regions just disappear. Maybe we should throw a warning, or have a final default area that is always written to?
And, I agree on the "My Moodle" concept of containing only blocks.
mike
Makes sense for the 'side-pre' and 'side-post' names.
Yes, names should be standardised.
Any thoughts on how we should define and manage these? Should we maybe have a table somewhere, or a document page? Just thinking ahead... Maybe we have at least a number of standard areas that are most likely to be used and then allow themes to go wild after that?
I see the 16 character limit now... I wonder if that could be a problem going forward? We could easily end up with something like 'home-centre-content'. Maybe we should plan now to bump that up to 32 or 64?
Thanks for pointing me to the 'defaultregion' code. There could still be an issue if the theme doesn't define a 'defaultregion' though. Looks like in that case, and blocks with unknown regions just disappear. Maybe we should throw a warning, or have a final default area that is always written to?
And, I agree on the "My Moodle" concept of containing only blocks.
mike
Sure, a table of common region names somewhere makes sense. It probably needs to be in both the blocks developer docs, and in the new theme docs, so perhaps on a separate page, linked (or transcluded if you want to be fancy) in both.
Changing the size of a DB column is trivial. Any finite limit on anything always ends up being too small. This field is using in the really hairy SQL in load_blocks, so it might be nice to do some load-testing to see if the size of the field makes any difference before we arbitrarily change stuff. Note, no one has yet come up with a proposed region which is too long.
If a theme specifies some block regions on a page, but does not nominate one as default, then you should get a coding_exception that explains exactly what the problem is (if you have debug set to DEVELOPER). A lot of the new blocks code is like that. If you don't do the right thing, you will get an exception, but hopefully it will explain the problem to you so you can fix it. Less severe warnings get debugging() output.
Changing the size of a DB column is trivial. Any finite limit on anything always ends up being too small. This field is using in the really hairy SQL in load_blocks, so it might be nice to do some load-testing to see if the size of the field makes any difference before we arbitrarily change stuff. Note, no one has yet come up with a proposed region which is too long.
If a theme specifies some block regions on a page, but does not nominate one as default, then you should get a coding_exception that explains exactly what the problem is (if you have debug set to DEVELOPER). A lot of the new blocks code is like that. If you don't do the right thing, you will get an exception, but hopefully it will explain the problem to you so you can fix it. Less severe warnings get debugging() output.
Ah... By 'table', I meant an actual data table in the database. I think you just mean documentation, correct? ('transclusion')
My concern about the lack of a defined default region is more based on my experience supporting hundreds of Moodles. If a site has installed blocks, and the assign a theme that doesn't have a default region, and contains none of the regions that the blocks were defined for, then the blocks will not show up anywhere. How would they get back to a usable state? The admin block would not show up to be able to reset the theme to one that worked, would it? (I may be worried about an extreme case here, and it may be my ignorance on theme making)
I looked at the 'anomaly' theme that comes with 2.0 now. It does not define any regions. Does that mean that it uses the standard regions by default?
mike
My concern about the lack of a defined default region is more based on my experience supporting hundreds of Moodles. If a site has installed blocks, and the assign a theme that doesn't have a default region, and contains none of the regions that the blocks were defined for, then the blocks will not show up anywhere. How would they get back to a usable state? The admin block would not show up to be able to reset the theme to one that worked, would it? (I may be worried about an extreme case here, and it may be my ignorance on theme making)
I looked at the 'anomaly' theme that comes with 2.0 now. It does not define any regions. Does that mean that it uses the standard regions by default?
mike
Yes. I was talking about documentation. Getting different themes to use consistent region names is a human problem, not a technology problem.
A Moodle 2.0 theme that states the regions it wants, and does not name one as default will not work at all. This situation is not a worry.
At the moment there is clever/ugly/evil backwards compatibility code that means that 1.9 themes sort-of work in 2.0. Petr is proposing to further clean up themes and break backwards compatibility, which is probably a good idea. A 1.9 theme gets regions side-pre and -post with -post as default.
I just added some comments to the talk page of your draft My Moodle proposal. If you would like comments elsewhere, I will happily move them. If you want people to just mind their own bloody business until you have finished the proposal, well I will try to restrain myself
A Moodle 2.0 theme that states the regions it wants, and does not name one as default will not work at all. This situation is not a worry.
At the moment there is clever/ugly/evil backwards compatibility code that means that 1.9 themes sort-of work in 2.0. Petr is proposing to further clean up themes and break backwards compatibility, which is probably a good idea. A 1.9 theme gets regions side-pre and -post with -post as default.
I just added some comments to the talk page of your draft My Moodle proposal. If you would like comments elsewhere, I will happily move them. If you want people to just mind their own bloody business until you have finished the proposal, well I will try to restrain myself
As we mentioned already, for My Moodle, we want to do everything with blocks, so that the pages can be more configurable, which means that we will want to define a new "standard" region for the centre column. There are a few different possibilities. I think that, if possible, I'd like to use a generic name (e.g. "main" or "centre" or "middle") rather than something that's specific to My Moodle, to make it easier for themes to support. We could either do a single centre region (although I'm not sure if it would be better to have it appear before or after the main content), or we could have a "-pre" and a "-post" region. Visually (pardon the ASCII art), the possibilities are:
centre region on top of main content:
[centre]
[side-pre] [MAIN CONTENT] [side-post]
centre region below main content:
[side-pre] [MAIN CONTENT] [side-post]
[centre]
"-pre" and "-post" regions:
[centre-pre]
[side-pre] [MAIN CONTENT] [side-post]
[centre-post]
Tim (or anyone else), do you have any opinion on this?
You have to distinguish block regions that belong to the theme, and centre-top and centre-bottom might be a sensible thing for most themes to offer.
However, for My Moodle, and similar, the particular script (my/index.php) wants to add a block region as the sole thing in [MAIN CONTENT]. In that case, I think it might work better if the region had a specific name, like my-content. However, I am not sure about that. Perhaps just call it 'content' on all such pages.
However, for My Moodle, and similar, the particular script (my/index.php) wants to add a block region as the sole thing in [MAIN CONTENT]. In that case, I think it might work better if the region had a specific name, like my-content. However, I am not sure about that. Perhaps just call it 'content' on all such pages.
OK, just to make sure that I understand what's going on... For My Moodle, we will make the centre blocks go into a region called "content" (I prefer calling in "content" instead of "my-content", since I can imagine that some other pages in the future may want to put block into the centre column, but other than that, I don't have a preference for the name).
The theme would need to handle both the cases where the page just "echo"s the main content, and the case where the content is a block region.
So each theme would need something like "<?php echo $OUTPUT->blocks_for_region('content') ?>" right after (or before?) the "[MAIN CONTENT GOES HERE]" text (and we'd need a similar change to the handle_legacy_theme method in outputrenderers.php).
We also need to add "content" to the regions array(s) in the config.php for each of the themes. (I'm not sure what the equivalent is for legacy themes.)
Is that right? I'm just trying to make sure I understand what's involved in getting all the themes to support a new region.
The theme would need to handle both the cases where the page just "echo"s the main content, and the case where the content is a block region.
So each theme would need something like "<?php echo $OUTPUT->blocks_for_region('content') ?>" right after (or before?) the "[MAIN CONTENT GOES HERE]" text (and we'd need a similar change to the handle_legacy_theme method in outputrenderers.php).
We also need to add "content" to the regions array(s) in the config.php for each of the themes. (I'm not sure what the equivalent is for legacy themes.)
Is that right? I'm just trying to make sure I understand what's involved in getting all the themes to support a new region.
No, no, no.
In a page where you want the main content to be a blocks region (so, for example my/index.php) you need to call
$PAGE->blocks->add_region('content');
before you do $OUTPUT->header(). That is, this block region is specific to this script, not a region common to all pages that is added by the theme.
Then, the whole of the output code becomes:
echo $OUTPUT->header();
echo $OUTPUT->blocks_for_region('content');
echo $OUTPUT->footer();
Or, perhaps,
echo $OUTPUT->header();
if ($PAGE->blocks->region_has_content('content', $OUTPUT)) {
echo $OUTPUT->blocks_for_region('content');
} else {
echo $OUTPUT->box(get_string('turneditingontoaddthingstothispage'));
}
echo $OUTPUT->footer();
In a page where you want the main content to be a blocks region (so, for example my/index.php) you need to call
$PAGE->blocks->add_region('content');
before you do $OUTPUT->header(). That is, this block region is specific to this script, not a region common to all pages that is added by the theme.
Then, the whole of the output code becomes:
echo $OUTPUT->header();
echo $OUTPUT->blocks_for_region('content');
echo $OUTPUT->footer();
Or, perhaps,
echo $OUTPUT->header();
if ($PAGE->blocks->region_has_content('content', $OUTPUT)) {
echo $OUTPUT->blocks_for_region('content');
} else {
echo $OUTPUT->box(get_string('turneditingontoaddthingstothispage'));
}
echo $OUTPUT->footer();
Ah, OK. I misunderstood one of your comments above, then. I thought that if the theme didn't know about a region, then the blocks would show up in the default region. I take it, then, that the add_region call tells the block manager that "content" is a known region and overrides that behaviour.
Exactly. Yes.
I was hoping that this code was quite easy to understand and well documented.
I was hoping that this code was quite easy to understand and well documented.
It seems very powerful and flexible, but there's a lot of new information to understand. From what I can tell so far from trying it out, it seems to be fairly easy to use, once you understand what's going on.