HTML Logo by World Wide Web Consortium ( Click to learn more about our commitment to accessibility and standards.

Moving forward with Composr

ocPortal has been relaunched as Composr CMS. ocPortal 9 is superseded by Composr 10.

Head over to for our new site, and to our migration roadmap. Existing ocPortal member accounts have been mirrored.

Creating Miniblocks from Third-Party Code

There are no pages beneath this page

Submitted by ChrisW
This is a short example-driven tutorial on creating a new ocPortal block (actually a "miniblock") by using externally-provided code. This is a great way to get started with customising ocPortal to your needs, and providing some level of integration between your ocPortal installation and your favourite external Web sites.

Who Is This Aimed At?
 - Those with little to no programming experience, but with a willingness to learn
 - ocPortal Web masters who want a little more integration with their favourite sites and services
 - Programmers wanting to learn how to code for ocPortal

What You'll Achieve
 - Learn a little about the languages which drive ocPortal and the Web in general:
  - PHP
  - Javascript
  - CSS
  - HTML
 - Learn how to integrate existing code into ocPortal in a basic way
 - A new block which you can insert into any Comcode-enabled field on your ocPortal site
 - An addon to share with the ocPortal community

What You'll Need
 - A text editor, preferably one aimed at programmers. A word processor will not do, and neither will Windows Notepad (if you try to use Notepad it will cause you lots of headaches later!). Examples of good programming text editors are:
  - jEdit (Linux, Windows, Mac OSX)
  - Geany (Linux, Windows, Mac OSX)
  - Kate (Linux, Windows, Mac OSX)
  - KWrite (Linux, Windows, Mac OSX)
  - MetaPad (Windows)
  - Notepad++ (Windows)
  - Notepad2 (Windows)
 - A working ocPortal installation (see the ocPortal documentation on how to get up and running). This doesn't necessarily have to be a live Web site, for example it could be installed on your home computer and only accessible to your home network.
 - Some HTML you would like to reference from inside ocPortal. Usually you can find lots of examples of this kind of thing under names like "embed code", "blog widget" and that kind of thing. It should be in the HTML format. For this example I'm using some code from the OpenStreetMap project, which I'll describe below.

Getting Started

In this example we're going to create an ocPortal "miniblock" out of the following code:


<iframe width="425" height="350" frameborder="0" scrolling="no" marginheight="0" marginwidth="0" src=",53.37746,-1.48328,53.38272&amp;layer=mapnik" style="border: 1px solid black"></iframe><br /><small><a href=";lon=-1.487175&amp;zoom=16&amp;layers=M">View Larger Map</a></small>
. This is taken from the OpenStreetMap site, and in this particular case shows a map of the main campus of the University of Sheffield. To get this code I clicked on the "Export" tab at the top of the map and chose "Embeddable HTML". The code appeared in the text box labelled "output". Lots of sites offer code like this, and the purpose of this tutorial is to make accessing such snippets of code really easy for users of our ocPortal sites.

What is a Miniblock?

"Miniblocks" are a simpler form of ocPortal's "blocks". On an ocPortal-powered site, the majority of the content (page content, forum posts, comments, etc.) is written as straightforward text. To give extra control over how this text will be displayed, the Comcode language can be used to specify things like "I want this text to be bold" or "I want this to be a link" or "I want this image here". To get even more power, a programmer can write some specific bits of functionality to display (usually) in a box, which Comcode writers can then embed in the content they write, in much the same way as an image can be embedded. These are called "blocks", and they have lots of useful features (like caching, to reduce the server load; parameters, to give them options,; etc.). A "miniblock" provides the same drop-in usage for Comcode users, but without some of the fancy extras that regular blocks have. This sacrifice makes them much easier to write.

Preparing To Make Our Miniblock

A miniblock is written in the PHP language, a programming language which uses "plain" text files for storing its programs. We'll get to the contents of the file in a moment, but to tell ocPortal that a text file contains some PHP, we give the file a name that ends in ".php" (rather than, for example, ".txt" which is often used for "plain" text files). For ocPortal to find the miniblock we need to put the file inside a folder called "miniblocks" inside the "sources_custom" folder at the location that you've installed ocPortal to. The final thing we need to know is the actual name of the file. This is up to you, but the convention is that blocks which are intended to be used in a large area, like the middle of a page, start with "main_", whilst those intended for use in side panels have file names starting with "side_". Whatever comes afterwards, up to the ".php", is up to you, but try to stick to English letters without accents, since other letters and characters may confuse some systems. For this example I will call our miniblock "main_openstreetmap.php", so we need to make a new, empty text file inside the programming editor and save it as "main_openstreetmap.php" inside the "miniblocks" folder inside the "sources_custom" folder of the ocPortal installation. If you don't have direct access to your ocPortal system, for example if you can only manage the files from a Web interface, FTP or similar then you can simply save it to the drive on whichever computer you're using then upload it to your site when you're finished; though this can be a little tedious if you have to keep making small fixes and changes.

What to Put in the Miniblock?

With your empty PHP text file open in your programming editor, you can begin to write the miniblock. Due to the nature of PHP, as it was originally created to embed inside HTML files, the first thing we need to do is declare that we're going to start writing some PHP in our file. We do this by writing the following at the start of the file:

Code (php)

The next thing we should do is to write a short description of what we're about to do, so that we don't get confused by the code later. Such descriptions are called "comments", and we write a comment by telling PHP to ignore what we're about to say (otherwise it may get confused and try to run our sentences as if they were code). There are 2 ways to do this in PHP. The first is to write two slashes, followed by our comment, like this:

Code (php)

// This is my comment. PHP will ignore it.
PHP will ignore whatever is written after 2 slashes until the end of that line. If you want to write a comment which takes up several lines then you can either put 2 slashes at the start of each line, or you can put a slash followed by an asterisk to start the comment, and an asterisk followed by a slash to end it, like this

Code (php)

/* This is a comment. It carries on for as long as I want it to. Even this is still a comment. I can end it like this */
Using this notation we can put a description at the top of our miniblock, to make our miniblock look like this so far:

Code (php)

/* This is a miniblock to draw a map from
It centres on the University of Sheffield by default. */

The next thing to do is to tell PHP what we want it to output. PHP is an elaborate text-rewriting system which, as it runs, gives out data. The data we want it to give out is text in the HTML format, so that visitors to our site will be able to display it in their Web browsers. The exact text we want it to give out is the code we obtained from Thus we first tell PHP that we want it to output something, which we do by using the "echo" command:

Code (php)

/* This is a miniblock to draw a map from
It centres on the University of Sheffield by default. */

Then, after a space, we say what we would like to have it output; the classic example being

Code (php)

echo "hello world"
Note that we can't just dump our HTML into the PHP, as PHP files allow HTML to be mixed in with the PHP, which will confuse the program. Instead we need to explicitly tell it that the HTML is a piece of text, and not something that it should try to run. We do this by quoting the text, which can be done with either single quotes 'like this' or double quotes "like this". Since our HTML contains some double quotes, and "quotes can't be "nested"" (unlike brackets (which can)) we should use single quotes. To end the echo statement we need to use a semicolon ; outside of any quotes. Thus our miniblock looks like this:

Code (php)

/* This is a miniblock to draw a map from
It centres on the University of Sheffield by default. */

echo '<iframe width="425" height="350" frameborder="0" scrolling="no" marginheight="0" marginwidth="0" src=",53.37756,-1.48325,53.38262&amp;layer=mapnik" style="border: 1px solid black"></iframe><br /><small><a href=";lon=-1.487175&amp;zoom=16&amp;layers=M">View Larger Map</a></small>';
This suddenly looks a lot more complicated, but as far as PHP is concerned this is as simple as the 'echo "hello world";' example. It doesn't care whether the text is written in HTML or not, it's only the user's browser that cares. Also, keep in mind that all of the above HTML was copied straight from someone else's Web site/service, we didn't have to write it and we don't even need to care how it works (although some parts like "height", "lat", "lon" and "zoom" are pretty easy to guess).

Using the Miniblock

That's all there is to writing a miniblock, although of course the PHP language is capable of far more than simply repeating something you tell it. Nevertheless, even this little miniblock should come in handy to those who would otherwise run screaming if they saw its contents. By saving it to our sources_custom/miniblocks folder it is already available to our users, who just need to write


(or whatever else you called it, without the ".php" at the end). I've attached a screenshot of this miniblock embedded on the homepage of a test installation of ocPortal 5.0.3.

In further tutorials we can explore how to make more powerful blocks, for example blocks which we can give whichever longitude, latitude and zoom we want.
Submitted by ChrisW
If you wish to turn your miniblock into an ocPortal addon that anyone can install then you can follow the instructions and diagrams in this section of the ocPortal programming framework tutorial. ocPortal, by default, gives administrators access to a "tree view" of all the addons which have been published on This means that, if you upload your addon to, it will appear inside (almost) every ocPortal installation in the world, and can be downloaded and installed automatically with just a few clicks!
Submitted by Fletch
I have recently suffered several 'Hack Attacks' and viewed many 'Stack Traces'. This triggered something in my dim grey cells, so I dug out the minilblock tute by ChrisW, and went to work.

It only took a few minutes, honest! And the satisfaction from following a well written tute and delivering something I would never have attempted in the past, is beyond measure.

Thanks ChrisW!

The code:

Code (php)

/* This is an attempt to build a miniblock. The content, a game, is another twist on the well-known Tetris original. Warning: it is addictive. Enjoy! */
echo '<div align="center"><h1>Stack Attack - A Logic Game</h1><br /><object classid="clsid:D27CDB6E-AE6D-11cf-96B8-444553540000" codebase=",0,0,0" width="480" height="320" id="6724004770.swf" align="center"><param name="movie" value="" /><param name="quality" value="high" /><param name="bgcolor" value="#e8ffff" /><param name="menu" value="false" /><param name="borderStyle" value ="1" /><comment><embed src="" quality="high" bgcolor="#e8ffff" width="450" height="320" style="border:1px solid #869aa7; padding:2px;" name="6724004770.swf" menu="false" type="application/x-shockwave-flash" pluginspage=""></embed><noembed></noembed></comment></object><br /><br /><a style="font-size:9px;" href="" target="_blank">More Games</a></div>';



P.S. Completely forgot - put it down to senility!
  • Name the miniblock whatever you want. I called mine stack-attack.php (what else?)
  • Save the miniblock in your sources_custom/miniblocks/ folder
  • To use it I simply wrapped stack-attack with 'block' comcode tags
  • The result is as you see it

CEDI change-log Post