Jump to content

IP.Content 2.1 Dev Update: Block Variable Help

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!


Recommended Comments

I think this was probably the toughest part of using IP.Content initially. I have a CS degree so I knew to expose some of the variables with different loops and print_r statements where necessary, but I could see this being really difficult for the novice programmer to figure out (or guess). Kudos on this addition as it will make it easier for me as well =)

Link to comment
Share on other sites

[quote name='IH_Jimbo' date='30 September 2010 - 04:44 PM']
This feature is an excellent addition. Something I will use a lot. Is this same functionality going to be extended to pages/templates so we can see our variables for those as well?

The pages and templates already have variable help windows, however it's important to note the differences here.

With blocks, we are passing in data to the block template that is directly relevant to the block you are creating. i.e. if you create a feed of members, we are passing in an array of members, and you may want to see what is available for each record in the array.

With pages and templates, we do not pass any variables into the page or template, so there's not really a similar concept we can apply. With database and article templates there is variable help already, as we do pass variables in, in those cases, but with page templates and pages the help window is similar to what you already see in IP.Content 2.0 - it shows the block and database parse tags you can use. There just isn't localized variables to show you.

(Mind you, we are not going to be documenting global variables that you can use everywhere, such as $this->settings, $this->request, $this->memberData and so on - there are simply too many data variables to document EVERY THING available to the templates, however 2.1 will now show you localized data specific to the block you are creating).

Link to comment
Share on other sites

[quote name='D377' date='30 September 2010 - 10:45 PM']
It looks difficult to add pages...

I didn't add a page in the video. :) I was adding a block, but I was customizing it to show something unique - of course that's going to require custom code to an extent. I was just trying to show off how you can utilize the variable help in the sidebar to more easily determine what "tags" to put in the template to show different things.

Link to comment
Share on other sites

The block feature is what give me headache,and to me it still seem hard to understand i really like IP Content but is there not a way for block to be plug and play,like just add the html code,like how the portal blocks work,i think this way is better for newbies like my self. :thumbsup:

Link to comment
Share on other sites

Join the conversation

You can post now and register later. If you have an account, sign in now to post with your account.
Note: Your post will require moderator approval before it will be visible.

Add a comment...

×   Pasted as rich text.   Paste as plain text instead

  Only 75 emoji are allowed.

×   Your link has been automatically embedded.   Display as a link instead

×   Your previous content has been restored.   Clear editor

×   You cannot paste images directly. Upload or insert images from URL.


  • Create New...