The Block SystemStarted by Arceus at May 11, 2019 7:56 am
Stand up child, and turn towards the lightning, and the thunder; so I can see what I've known for all these years.
The Block System
Gaia ships with a feature called blocks. Blocks are somewhat like widgets; each one has a type, and a name, and, if a custom block, user-defined content. By default, the system will gather information about these blocks, and then output them in the order they're arranged in, using a template called template_block. This template creates a standard, uniform look for all your blocks.
But, what if you want one block in a different spot? What if you want them arranged a certain way? What if, you want them in a different template than is standard?
In this guide, we'll go over what types of blocks there are; how to move the default output to a different place; how to manually output a block by ID; and how to output them without using the standard block template.
Types of Blocks
When you click New <Whatever> Block, you're taken to a screen with just a drop-down menu on it. This tells Gaia what kind of block you want, and there are quite a few choices, so here, we'll go over really quickly what they all do.
Affiliates List: Currently, you can only have one set of affiliates, this may change in later versions of Gaia. But, this block sets up and outputs all the buttons and links for your active and approved affiliates.
Character Tallies: If you need a list of your character groups and how many characters are in each one, this your jam.
Custom Content: Need a welcome message? A cbox? This block allows custom input and displays it for you.
Established Date: Once you've switched on the We're Open! switch, this will display the date that you turned it on, thereby proudly displaying how long you've been around.
Forum Stats: This displays: total topics; total posts; total members; total characters; most recent member; most recent character.
Online Today: A list of all users that have logged in within the last 24 hours, I couldn't figure out how to make it actually today, re: timezones. So I didn't.
Posted Today: A list of users, and characters, that have posted within the last 24 hours. Again, timezones.
Random Character: Pulls a random character and displays their basic information and a link to their profile. Good for "of the moment" spotlights.
Random Member: Pulls a random user and displays their basic information and a link to their profile. Also good for "of the moment" spotlights.
Recent News: Pulls and displays the most recent news announcements and displays links and their summaries. This is good for keeping users up to date with recent announcements.
Recent Topics: This pulls and displays recent posts on the site. Note that it will count a post edit, as it arranges by last updated time, and post editing ups that date, this is so that joint-post style sites get accurate activity representation.
Reputation Leaders: Who got the most reputation? These users got the most reputation!
Staff List: Auto-list of staff members, groups 1 and 2, and their last login time.
Who's Online: I always feel like, somebody's watchin meeee~ these users are currently browsing your site.
Each block type has its own special formatting that it decides on and outputs from Pontus. If you want to alter these default templates, you'll have to get into pontus.php in /application/core to change them. Be careful. Here there be scary.
Moving the Block Output
Now, by default, the blocks are output in something that looks a little somethin' like this:
foreach($page->blocks['bottom'] as $block)
Just pick these up and move them, and voila, you're done. Note that because these are in an if statement (do not take that out, it will cause errors on pages that don't have any blocks displayed), you'll need to make sure there is a closing '; at the line above, and a starting echo ' or so after.
Manually Calling a Block by ID
Calling a block by ID is very simple. All you need to do is something like:
Surrounding it in whatever HTML you want, this is just an example, but it can be adapted to pretty much anything. A note here, too, you may want to add the [#] identifier at the end of the blocks['bottom'] in the if empty statement, so that if you have bottom blocks on multiple pages, it won't error because it can't find the one you're specifically calling on pages it is not enabled for.
Outputting With a Custom Template
Alright the good stuff.
So every block outputs an stdClass object. This object is accessed like $page->blocks['direction'][id]->var. Var can be: id; name; content. These are all that are loaded. If you want your blocks in non-standard block templates, you can do:
foreach($page->blocks['direction'] as $block)
Obviously, your HTML will be different, but this is just an example of how you could do that. If you have a specific arrangement in mind, you can use, in conjunction with each other, outputting a block without the standard template and calling blocks by ID, in order to get the exact block arrangement that you want out of it.
The block system in Gaia is actually quite powerful, and I hope that everyone finds some good solid use out of them. Get creative and play with them a little; errors are rarely unfixable, and blocks have a lot to offer you and your site.