Blocks

Blocks are akin to widgets or boxes on the page. They are small (or large) blocks of content, as their name implies. IP.Content allows you to create many different kinds of blocks which you can use in IP.Content (and IP.Board), as this article will show.

Types of Blocks

The main types of blocks are as follows:

• Custom
  Custom blocks are blocks that contain content that you explicitly provide. There are 3 primary types of content blocks:
  
  
  • Raw HTML
    With a raw HTML block, you are given a blank textarea that you can use to insert any HTML you want. You can use this, for example, to create an "adsense" block and reuse the same adsense code in many places throughout the board.
  • Raw PHP
    A raw php blocks gives you a textarea where you can specify PHP code. The PHP code is then eval'd and the output is displayed. Some tips:
    
    
    • Since the content is eval'd, the scope is inline with the block execution code. This means you have full access to $this->settings, $this->memberData, etc.
    • You should not include the opening or closing PHP tags, since the content is eval'd. IP.Content will show you an error if you try to enter opening or closing PHP tags. This also means you cannot use a closing PHP tag to start rendering HTML, and then an opening PHP tag to start script execution again.
  • BBCode
    You will be presented with the standard board editor to specify your block content. You will use the standard editor or the rich text editor (WYSIWYG) depending upon your board preferences
• Feed
  Feeds allow you to feed dynamic data from around the board into a block. This has many uses and supports many areas of IP.Board (and first party addons) out of the box. Additionally, modification authors can add new feed types at any time without any file modifications to the software. If you create a couple of different feed blocks you will quickly notice that the wizard steps change accordingly based on what functionality and options each feed type supports.
  
  
  • Blogs
    You can feed in entries, comments and blogs into blocks for output.
  • Calendar Events
    You can feed in calendar events within a block.
  • Downloads
    Download feeds allow you to pull in files, categories and comments to show in the blocks.
  • Forums
    You can feed in forums, topics and posts to blocks.
  • Gallery
    You can feed in categories, albums, images and comments to blocks.
  • Members
    You can feed in members, as well.
  • RSS Feed
    RSS feeds are supported as well. Please see the note about caching blocks later.
  
  Each feed has various unique sorting and filtering options, so you can customize how to output the content. For instance, RSS feeds can't be sorted, while members can be sorted by name, joined date, rating, and other options. You can filter many feeds by category (for instance, download files in a specific category), by submitter (you can enter a user's name to filter only their content), and so forth. The exact options depend on the feed and content types you specify. Note that you will only see block types for applications that you have installed.
  
  Feed filters that require date inputs allow you to use natural language date filtering (for developers, it uses php's strtotime() function), so you can specify "today" for instance, to get a feed of content filtered to only show content for today. Or you can specify "last week" and get content from the last week. Where feed filters allow you to enter a name, you can use two special keywords as well: "friends" and "myself". If you specify "myself", only content unique to the logged in user will be shown. If you specify "friends", then the logged in user will see content from his friends.
  
  Using the above feed types, content types, sorting options, and filtering capabilities, you can create many unique types of feeds! Some random examples:
  
  
  • Comments made to gallery images by my friends
  • Calendar events in a specific category (for instance, "New York City")
  • Upcoming calendar events
  • Latest topics
  • Latest posts
  • Most recently joined users
  • RSS feed from an online news site
  • My friends' posts from today
  
  There are some important things to note about the rest of the block options with relation to feeds specifically. See the notes below on caching, specifically.
  
  Addon developers can take a copy of one of the existing feed type files, copy it with a new name, and adjust the code in the various functions (specific to the application you are creating a feed for), then save it back to this folder. If the feed is setup correctly, IP.Content should see it automatically. The feed files are under:
  
  

  admin/applications_addon/ips/ccs/sources/blocks/feed/data_sources/

• Plugin
  Some types of content, while possible in raw PHP blocks technically, is better suited to a full separate PHP script. For this purpose, IP.Content supports plugin blocks. Again, developers can create their own plugin blocks, drop them in a folder, and IP.Content will automatically see them. The plugin blocks that have been provided in the base installation are:
  
  
  • Mini-Calendar
    Shows a mini-calendar, like in the left sidebar when viewing the calendar section.
  • Online friends
    Displays a list of your online friends.
  • Poll
    Allows you to feed a poll from your forums into a block.
  • Online users
    Displays a list of online users, similar to the board index page
  • Watched content
    Shows a watched content block, similar to the one distributed in IPB for the board index sidebar
  • Welcome block
    Shows a welcome block unique to the viewing user, with some statistics and quick links.
  
  As with feeds, you should be careful caching plugin blocks, as the data is generally meant to be dynamic and specific to the viewing user.
  
  Addon developers can create new plugin blocks by adding the appropriately coded files to
  
  

  admin/applications_addon/ips/ccs/sources/blocks/plugin/

  
  You will need to create a folder with the block's key, and then add a plugin.php file into the folder. See one of the existing plugins for a base example. We hope to have more developer information soon.

Block Options

When you add a block, you use a wizard to step through the process. Many of the options for the different blocks will depend on the previous selections in the wizard. Some options, however, are available for all blocks.

• Block Title
  Will often be used in the block's header bar when output. This is a title that is used to identify the block.
  
• Block Key
  The key is used to embed the block into a page or page template later.
  
• Block Description
  This is only used when displaying the block in the ACP to help you identify blocks you have created. You do not need to specify a description.
  
• Block Category
  You can create categories to group your blocks in, making it easier for you to manage them later.
  
• Cache TTL
  Caching allows you to cache the block output for a defined period of time (or you can specify '*' to cache indefinitely). Caching can help boost performance for some blocks, at the cost of being stale for the period of time the block is cached. Additionally, you should not cache certain blocks.
  
  If caching is enabled, when the block output is first created (which generally happens when you save the block via the ACP) it is saved. If a request for the block is made within the defined cache period, the copy that was originally output and saved is presented to the user. When a request is made after the defined cache period has expired, it will be re-evaluated and output, and the new output will be cached.
  
  If you have blocks that show content to a specific user, you should not cache them. If I log in, and trigger the block to recache, and then you login and view the page, the block results from my pageview will be shown to you. This can even result in showing a user more information than they should know (for instance, if you have a topic feed pulling from an administrator-only forum, and it caches, a user will be able to see the list of topics that were pulled for you). Similarly, you would not want to cache the welcome block plugin, since it should show data for different users to the viewing user.
  
  Caching can be good in cases, however, where an expensive query needs to be run to get the block content. For example, showing latest posts is a resource intensive query. Running this on every page can cause efficiency issues in your system (it is possible to come up with combinations in the system that cause slow queries). You can cache this block however, to offset the resource usage. If you have 100 page views of your index page in an hour, and you cache a latest posts block for an hour, that means the expensive query is only run once, instead of 100 times, during that hour. RSS feeds are also a good candidate for caching. It is somewhat slow to connect out to a remote server to grab the feed, and feeds do not change frequently enough that you should pull the feed for every page view vs caching it.
  
• Template HTML
  Each block has it's own template HTML. This allows you to customize each and every block's look specific to the block. A default template will be presented to you that will work to show the data, however you can customize the output for your own needs. Much more information than is actually used is available to the template in most cases. You can use our peer to peer forums if you need help figuring out what to put in a template to show a certain piece of information.

Because most changes to blocks once they are created are usually for editing the output, when you attempt to edit a block, you will have a form that allows you to enter the static details (i.e. the details above that would be the same for each block type) without having to use the wizard. If you wish to change details specific to the block you can click "Use Wizard" at the top right to launch the wizard to help you update the block.

Using Blocks

After you have created a block, you can then embed it into page templates and pages, and even IPB skin templates. You use the same steps as you use for IP.Content to embed a block into an IPB skin template (you take the parse tag that is presented to you on the last page of the block wizard) and put that into any skin template to show the block right where you place the tag.

To embed a block into a page template or page, go to the form to edit the page content or template content, and click the "Template Tag Help" link. A sidebar helper will open with all the tags you can put into the template or page, including your created blocks. In the Template Tag Help window, click the question mark icon if you need further explanation of each tag. You then copy the tag you wish to embed, and paste it into the template or page and save.

Sorting blocks

Within the block management screen you can drag n drop blocks and block categories to sort them. You can even drag blocks and drop them in other categories to move them.

Previewing blocks

Within the block management screen, you can click on the magnifying glass icon next ta block title to view a preview of just that block.

Recache All button

The Recache All button at the top of the page (and the "Recache Block" option available for each block) will rebuild the block cache(s) if the block is configured for caching. Note that this means that any urls will likely be admin control panel urls, so be careful recaching the block via the ACP, depending on the specific type of block you are updating.

Sharing blocks

You can create blocks via your admin control panel and share them with other users. You simply configure the block appropriately, and then you use the "Export Block" option via the options menu for your block. If you wish to install a block someone has provided to you, you can upload the .xml file at the bottom of the block management screen.

Block categories

The "Add Category" option on the block management screen allows you to add categories, and the menus next teach category allow you to edit or delete them. To move them on the block management screen, you simply drag n drop them to the new location.

Developer-Only Options

Export Plugin Templates

If you create your own plugin block and need to export the templates for it, this option will allow you to do that. Users can then import the templates at the bottom of the block management page.


Conclusion
As you can see, there are many different types of blocks and many different ways to configure them. If you think you have created a block that will be useful for other users of the community, please feel free to share it in the resources area.

If you have any questions or suggestions for this article, let me know!