Blocks, a core feature of IP.Content, provide you with an easy way to create static and dynamic widgets that can be embedded anywhere in IP.Content (and indeed, anywhere in IP.Board itself). There are three core block types: custom blocks (where you can effectively embed any HTML or PHP you want into a widget), plugin blocks (these blocks execute a PHP script to generate specific output, such as a mini-calendar or poll), and feed blocks (feed blocks are used to "feed" data from anywhere in IP.Board, as well as RSS feeds). While blocks are extremely powerful, it can be challenging for a novice to fully understand what can be done with the blocks in IP.Content. To get the most out of your blocks, and to make them customized and unique to your site, you have to know what variables are passed to the blocks and thus are available for your use.
As part of our drive to make IP.Content easier to use and more accessible to novice and intermediate users, we have developed an inline block helper window for IP.Content 2.1 that we think will help everyone to better understand what variables are available in individual block templates.
(Please be aware that the following videos and screenshots are of a pre-final copy of IP.Content 2.1. The interface may change before the final version is released.)
Launching the Variable Help
In the following screenshot, I have clicked on the "Recent Articles" block and am now presented with the form to edit the block template. You will see a "help" button that you can click which opens the block variable help window.
Upon clicking the button, the variable help window opens
Here we can see that two variables are passed into the template. Different blocks have different variables available to them, so this helps us understand what is available with the block we are currently working on. $title is a variable that holds the block title (as the description notes), while $records is an array that holds all of the records in this feed. You will note that $records is underlined because it is a link. When we click on this link, it expands the variable help for the $records variable.
Now we can see that when we loop over the $records (this is done by default in the template), each member is an array, and we see what array keys are available.
By default, you see this in the template:
<li class='{parse striping="feed_striping"}'> <a href='{$r['url']}'>{parse expression="IPSText::truncate( $r['field_1_value'], 30 )"}</a> </li> </foreach>
<foreach loop="$records as $r">
Here you can see that the default template uses $r['url'] and as well as $r['field_1_value']. If you were not familiar with the software, you may not know what this means. By utilizing the documentation available now, you can now gain an understanding of what is happening.
$r['url']: The URL to the database record or article
$r['field_1_value']: The formatted value for the field "Title" that should be shown to users
Now What?
While understanding what each variable in the default template is for is very helpful on it's own, you can now take your blocks even further. Now that you can access documentation on what variables are available, and what each variable does, you can modify your block templates to make them more personalized to your site, with the information you want to display. Let's walk through a quick example.
Please see the following video, and the subsequent description of what we have just done.
The first step we take is to create the block. For this demonstration, I am creating a "feed" block that pulls topics from the forums. Because I am showing "news" from a specific forum, I opt to order by "start date" (instead of the date the last post was made). I decided not to edit the template initially, and saved the block. Now I preview the block so you can see what it will look by default.
The default template works well as a "latest posts" block, however if we are intending to show news, we will probably want to show the entire post. Next, I go back in and edit the block template.
I decided to move the date to the beginning of each row, and then I show the name of the member that started the topic.
Now, I remove the code that truncates (shortens) the post, and wrap it in a div that gives it a margin so it is easier to see.
Lastly, I decided to add a small blurb to the end of each row that tells who last edited the post, and a little bit of information about this user. I added the last poster's name, the date they made their last post to the topic, their profile picture (the "mini" size version), the user's post count, and the number of times this user's profile has been viewed. I save the block again, and launch the preview again to give you and idea of what the end result will look like.
All of the above was simply to demonstrate how you might be able to use the block help to find variables you may wish to use in your blocks. By using the block help, I was able to add a lot more data and thus make the block more useful.
Wrapping Up
Of course, the block templates still don't write themselves - you will need to determine what it is you want to show and where. We hope, however, that the block variable help panel provides you with direct, relevant documentation of the various variables you will want to access in your blocks. We believe this help panel will lower the bar to customizing IP.Content just a little bit further, making it easier for more people to do the things they want easier in IP.Content. We look forward to your feedback and hope you like the changes!