How to create dynamic custom blocks on your IPS4 site

[Nathan Explosion]

This is a guide to something I put together for @kar3n2 to allow her to display different custom blocks depending on the category a record was in (see here for more details on that)

The information below is relevant to any portion of the site, installed in the root of the domain, on which a custom block can be added so you are not restricted to only using on a Pages page. For the purposes of the guide, I am using a reference to a Pages page with a database containing 2 categories which have

1) The theory behind the solution

I've got a database with 2 categories in it, and that database is in use on a page. The page is called 'page1' and the categories in the database are called 'Category 1' & 'Cateogry 2' - both categories have had their 'FURL Slug' manually set to 'cat1' and 'cat2'.

Records within the page/database thus can have the following urls:

http://www.yourdomain.com/page1/cat1/stuff1
http://www.yourdomain.com/page1/cat2/stuff2

For 'cat1' I want to display a block that has something specific to that category.
For 'cat2' I want to display a block that has something specific to that category.

However, I can only add one or both or none of the blocks to a page:

• If I add only the block for 'cat1' then it will be seen on 'page1/cat1' and 'page1/cat2'
• If I add only the block for 'cat2' then it will be seen on 'page1/cat1' and 'page1/cat2'
• If I add both blocks then both will be seen on 'page1/cat1' and 'page1/cat2'
• And if I add nothing, then nothing will be seen.

From the url, the important bit for this solution is 'page1/cat1' and 'page1/cat2' and that gives us something to work with.....it shows us what page is in use and what category is in use.

So let's use it.....

[Nathan Explosion]

2) Let's create a new custom block and get on with it

• Go to ACP -> Pages -> (Page Management) Blocks -> Create New Block
• Select 'Custom' and then 'Manual PHP'
• Click Next.
• Populate 'Name' & 'Description' as you wish - I called mine 'Sidebar' as I am going to use it in the sidebar.
• In 'Template Key', put in a name for your block - I called mine 'my_custom_block_of_fun_sidebar'
• Click Save.
• Set the permissions as you wish.

At this point, you might as well add it to the page it is going on....so I've added it to the sidebar on my 'page1' page using the Block Manager on the front end and going to Pages -> Custom Blocks

"But it doesn't display anything" I hear you say - correct, we didn't put any content in.

3) Start putting in some PHP code that is going to help make the magic happen

Go back to the ACP and edit that block you created, then click on to the 'Content' tab.
Add the following code to the content, and save the block:

$sb_path = \IPS\Request::i()->path;
$sb_pathpieces = explode("/",$sb_path);
Echo "You are on the page '".$sb_pathpieces[0]."' and in the category '".$sb_pathpieces[1]."'";

Now go to your page and refresh - you should see the following in the sidebar:

You are on the page 'page1' and in the category ''

Access 'a category and you should see the following in the sidebar:

You are on the page 'page1' and in the category 'cat1'

All the code is doing is taking 'page1/cat1' portion of the url ($sb_path) and splitting it in to an array ($sb_pathpieces) that we then use to echo out a bit of information.

[Nathan Explosion]

4) Let's modify that PHP code

Edit the block again, and remove the following line:

Echo "You are on the page '".$sb_pathpieces[0]."' and in the category '".$sb_pathpieces[1]."'";

And add the following instead:

function sb_show_block($sb_page,$sb_category){
	$sb_show_block = "You are on the page '".$sb_page."' and in the category '".$sb_category."'";
    return $sb_show_block;
}
echo sb_show_block($sb_pathpieces[0],$sb_pathpieces[1]);

All I've done here is create a function that takes arguments and then creates a variable that we return for use with that final echo statement - the result is the same as step 3, just done a different way.

At this point, the full code is as follows:

$sb_path = \IPS\Request::i()->path;
$sb_pathpieces = explode("/",$sb_path);
function sb_show_block($sb_page,$sb_category){
    $sb_show_block = "You are on the page '".$sb_page."' and in the category '".$sb_category."'";
    return $sb_show_block;
}
echo sb_show_block($sb_pathpieces[0],$sb_pathpieces[1]);

5) Before we modify more code, let's create some more blocks

• Go to ACP -> Pages -> (Page Management) Blocks -> Create New Block
• Select 'Custom' and then use whichever content editor you want - I'm going to use Editor.
• Click Next.
• Populate 'Name' & 'Description' as you wish - I called mine 'Sidebar - Category 1' as I am going to use it in the sidebar and it is for Category 1 after all.
• Now this is important (and the reason will become clear later) - for 'Template Key', you will be using the information for the page and category as an identifier.
• I called my main block 'my_custom_block_of_fun_sidebar' earlier, so I'm going to use the same naming convention and call this block 'my_custom_block_of_fun_sidebar_page1_cat1'
• Go to the content tab and enter in anything you want - "Hi, you're in Category 1" for example.
• Click Save.
• Repeat the above for 'Category 2', ensuring you have a different entry in the content section (you do want to display something different, yes?) and that the template key reflects that it is 'cat2' and not 'cat1'

At this point, I've now got 3 custom blocks:

• my_custom_block_of_fun_sidebar
• my_custom_block_of_fun_sidebar_page1_cat1
• my_custom_block_of_fun_sidebar_page1_cat2

[Nathan Explosion]

6) More PHP code

You know the drill now.....edit the block (called 'my_custom_block_of_fun_sidebar', as it's now confusing as you have 3 blocks)

Change the whole code to:

$sb_path = \IPS\Request::i()->path;
$sb_pathpieces = explode("/", $sb_path);
function sb_show_block($sb_page,$sb_category){
	$sb_which_block = 'my_custom_block_of_fun_sidebar_'.$sb_page.'_'.$sb_category;
	$sb_the_block = \IPS\cms\Blocks\Block::display($sb_which_block);
	return $sb_the_block;
}
echo sb_show_block($sb_pathpieces[0],$sb_pathpieces[1]);

Save the block, then go to your page and access 'cat1' and 'cat2' - if you've done the above then you've got different information displaying in the sidebar depending on which category you are in. Now go to the root of the page (ie not in a category) and you should see no content in the sidebar. Want to put some in?

7) Create a fallback system to display something if there is no block for the category

Create a new block, same method as step 5, but set the template key to 'my_custom_block_of_fun_sidebar_page1_fallback'
Throw 'I accept beer' in to the content.

Next, edit the main block ('my_custom_block_of_fun_sidebar') and modify the code in the content to the following:

$sb_path = \IPS\Request::i()->path;
$sb_pathpieces = explode("/", $sb_path);
function sb_show_block($sb_page,$sb_category){
    $sb_which_block = 'my_custom_block_of_fun_sidebar_'.$sb_page.'_'.$sb_category;
    $sb_fallback_block = 'my_custom_block_of_fun_sidebar_'.$sb_page.'_fallback';
    if(\IPS\cms\Blocks\Block::display($sb_which_block) == ''){
        $sb_the_block = \IPS\cms\Blocks\Block::display($sb_fallback_block);
    } else {
        $sb_the_block = \IPS\cms\Blocks\Block::display($sb_which_block);
    }
    return $sb_the_block;
}
echo sb_show_block($sb_pathpieces[0],$sb_pathpieces[1]);

Save the block, then go to your page root and you should see 'I accept beer'

And that is it.

[Nathan Explosion]

Now....that guide dealt with displaying items in the sidebar of a specific page and the idea can be expanded to any other section of the site.

For example, if you want a block to appear in a forum called 'My forum' then your url could be http://www.yourdomain.com/forum/1-my-forum/ so if you create a sidebar block with a template key of 'my_custom_block_of_fun_sidebar_forum_1-my-forum' then the code will display that block in that forum and if you had a block with a template key of 'my_custom_block_of_fun_sidebar_forum_fallback' then that fallback block will display in all other forums. And so on for the other parts of the suite:

Example: for Activity Streams (http://www.yourdomain.com/discover/.....)

• my_custom_block_of_fun_sidebar_discover_unread
• my_custom_block_of_fun_sidebar_discover_content-started
• my_custom_block_of_fun_sidebar_discover_followed-members
• my_custom_block_of_fun_sidebar_discover_fallback

Go further?

You could even display a block in a specific topic (as long as the title of the topic is not going to change) but a different one for all other topics:

Example: http://www.yourdomain.com/topic/1-this-is-the-topic-title/

• my_custom_block_of_fun_sidebar_topic_1-this-is-the-topic-title
• my_custom_block_of_fun_sidebar_topic_fallback

test

[Nathan Explosion]

But what if I want to use the top or bottom horizontal sections and not the sidebar?

Take the theory and adapt it - the following code can go in the top horizontal block:

$th_path = \IPS\Request::i()->path;
$th_pathpieces = explode("/", $th_path);

function th_show_block($th_page,$th_category){
    $th_which_block = 'my_custom_block_of_fun_top_'.$th_page.'_'.$th_category;
    $th_fallback_block = 'my_custom_block_of_fun_top_'.$th_page.'_fallback';
    if(\IPS\cms\Blocks\Block::display($th_which_block) == ''){
        $th_the_block = \IPS\cms\Blocks\Block::display($th_fallback_block);
    } else {
        $th_the_block = \IPS\cms\Blocks\Block::display($th_which_block);
    }
    return $th_the_block;
}

echo th_show_block($th_pathpieces[0],$th_pathpieces[1]);

And the following in the bottom horizontal block:
 

$bh_path = \IPS\Request::i()->path;
$bh_pathpieces = explode("/", $bh_path);

function bh_show_block($bh_page,$bh_category){
    $bh_which_block = 'my_custom_block_of_fun_bottom_'.$bh_page.'_'.$bh_category;
    $bh_fallback_block = 'my_custom_block_of_fun_bottom_'.$bh_page.'_fallback';
    if(\IPS\cms\Blocks\Block::display($bh_which_block) == ''){
        $bh_the_block = \IPS\cms\Blocks\Block::display($bh_fallback_block);
    } else {
        $bh_the_block = \IPS\cms\Blocks\Block::display($bh_which_block);
    }
    return $bh_the_block;
}

echo bh_show_block($bh_pathpieces[0],$bh_pathpieces[1]);

As long as you've got the relevant target blocks set with the right template keys, then all will be good:

• my_custom_block_of_fun_th_page1_cat1
• my_custom_block_of_fun_th_page1_cat2
• my_custom_block_of_fun_th_page1_fallback
• my_custom_block_of_fun_bh_page1_cat1
• my_custom_block_of_fun_bh_page1_cat2
• my_custom_block_of_fun_bh_page1_fallback

Why is the code slightly different for each of the block locations (ie sb_, th_ & bh_)? If you have the code in use in more than one of the block locations, then only one of them will display. So use different naming in the code to avoid that.

Final few bits:

I mentioned earlier that this for a site installed in to the root of the domain. If you have the suite installed in a subdirectory, then you need to account for that in the code.

To do this, let's take the following url as an example(sub-directory is 'forums'):

http://www.yourdomain.com/forums/page1/cat1/stuff1

To account for this, modify the final echo in the code to change the $sb_pathpieces[0] and $sb_pathpieces[1] to $sb_pathpieces[1] and $sb_pathpieces[2] ($sb_pathpieces[0] would be 'forums')

[Nathan Explosion]

Note: the above can be expanded out to accommodate subcategories in databases too. If anyone needs assistance with that, let me know.

[kmk]

Hi @Nathan Explosion

I want to learn from this tutorial, but only reading code is a little hardly for me what exactly effect resulted, is possible put here screenshot?

[Nathan Explosion]

I'm not going to put it together just to provide a screenshot; this was done 2 years ago and that test environment is long gone.

Simply put: what you get will be a block containing whatever you want it to contain, in the place where you place the block. Any screenshot isn't going to elaborate on that at all.

If you want to learn from the tutorial then you are going to have to do the tutorial yourself....and I'm not even sure if it will work in 4.2.x either.

"Try it and see"

[Rogefeller]

You sir, are a freakin' genius. I managed to modify your code to obtain the desired result and it worked perfectly in 4.3.6.

Thank you so much for this write up.

👍