From RNWiki
Jump to: navigation, search

INTRODUCTION

Blocks are a fundamental layout element within Ravennuke. Blocks are rectangular elements within which content can be arranged. You use the Administration Control Program (ACP), blocks, to create, activate, edit, and arrange blocks. Blocks can be positioned on your page in a prioritized order. The standard positions in Ravennuke are: left, right, center up, and center down. In Ravennuke 2.5 a new position is being introduced: center top -- above the standard message that appears on most home pages.

There are several types of blocks:

  • simple blocks created with the ACP block editor -- you actually enter the contents of these blocks in the editor (no programming code permitted)
  • block files -- these exist in your /blocks directory and can contain sophisticated programming commands, text or html or a combination
  • feeds -- these blocks pull in data from external RSS feeds and display them (and links to them) on your web page. A set of standard feeds is provided as part of your distribution, but others can be added

As indicated, quite a few blocks come predefined with the distribution. Even if you are not a programmer, you should take some time to get familiar with these. On a test system, try activating and looking at each. There is no universal layout or set of blocks that is appropriate for all sites, so get used to the idea of customizing your block layout. Once you have done that, you can try creating a few simple blocks with the blocks editor in the ACP. You can put pretty much any html code, including tables and images into these blocks. Also, take a look at some of the RSS blocks, if only to see how they work. You can deactivate them when you are done.

Aside from setting up blocks, you can control which groups of users within your system get to see them. So, if you have a block that you only want administrators to see, you can do that. Or if you set up groups using NSGgroups facilities (a separate program on the ACP) you can restrict blocks to specific groups. Finally you can control the timing of activation and expiration of your groups.

ADMINISTERING BLOCKS, PART I, Editing blocks

To read this part, we highly recommend that you bring up the blocks editor for your site or test site in another browser tab or window. The top section, above where it says REORDER BLOCKS, is basically a listing of all blocks in your system, arranged by their position and their order (or "weight") within that position. This is where you can reorder your blocks within their current position. You use a simple numeric code to indicate the order ... 1 comes before 2 etc. Simply type in the new ordering, taking care to avoid duplicates and hit the reorder blocks button. You can reorder several positions at once. Also, in this section you can select a block to edit and you can activate or deactivate blocks. You can also use the "show" button to see a preview of what currently deactivated blocks would look like.

Below the REORDER BLOCKS button you will see the blocks editing area. Pick an existing block to edit and take a look. Mostly the fields on the editing screen are self-explanatory. You can customize the title of your block (this is what will show in the top center of your block on the page). The filename entry gives you a choice of any block files that exist on your system. All the program does here is rummage through the /blocks directory and present a list of block files. If you create your own block file it will show up here also.

The "position" entry allows you to select any of the positions mentioned in the introduction here for your block. Your block will be positioned initially at the "bottom" of that position and you can use the reordering facilities later to move it around. The "activate?", "expiration" and "after activation" fields work as you would expect. Most admins either activate or deactivate a block, but if you have a reason to set a block up for a specified time period and then deactivate it you can use these fields for that.

The "who can view this" field works in conjunction with the "what groups" field to control viewing of your block. Of course, limiting the viewing of blocks to specified groups only works if you have already set up nsngroups in your system. Likewise, the "visible to subscribers" field is only relevant if you are using the subscription facilities of the Your Account module. But, if you are, you can limit viewing of specific blocks to users who have subscribed to your site.

ADMINISTERING BLOCKS, PART II, Adding blocks

When you first bring up the blocks ACP, the add blocks area shows beneath the REORDER BLOCKS button. As you might guess, this is where you add a new block. Again, we assume that you have the screen for this open in another browser tab. The "title" field is a custom title for your block. It can be anything you want as long as it is plain text. The next line: "RSS/RDF file URL:" actually contains a series of somewhat complicated capabilities. While discussing RSS (Really Simple Syndication) is beyond the scope of this section of the documentation, suffice it to say that these contain new feeds from other sites. A series of news feeds that are provided with the Ravennuke distribution show up when you click on the "custom" drop down box. And you can add other news feeds (or eliminate unneeded ones) to/from the "custom" dropdown by using the "setup" button. Or you can just put the URL of a known news feed into the "RSS/RDF file URL:" field directly. Using this capability can be a really great way to add content to your site without a lot of programming effort.

Below (and mutually exclusive with) the RSS line, there is a filename field. This is the name of a block file in your blocks directory. Only existing block files will show up in this dropdown box. If you are familiar with programming in PHP, you can add your own blocks files ... we'd recommend that you use an existing block file as a template. Basically, you use PHP programming to put anything you want (including data from the database) to display in the block into a variable named $content, then the system displays $content when the block execution finishes.

Further down, the "content" field is also mutually exclusive with the RSS and filename fields (in other words you have one of three choices for what you put in the block). You can use any entries that are permitted by the WYSIWYG editor in this content field -- text, images, tables, links and other and standard HTML. You cannot, however, insert programming commands in the content ... to do this you need to create a block file and use the "filename" entry.

With one exception, the fields beneath the "content" entry have been covered in the editing blocks section. That exception is the refresh time for RSS blocks. The feeds module basically caches summary content from your RSS blocks so that they can be displayed when you move your mouse over the feed items on the page. This allows you to see a summary of what is in the feed item without leaving your site, you can then click to see the full content of the item on the other site that provides the feed. The refresh field determines how often this cache is refreshed.

A LITTLE MORE ON POSITION

As indicated above, we are adding a new block position, center top, to the four pre-existing block positions that have been in previous distributions -- left, right, center up, and center down. To understand how these positions "work" you need to understand a bit about how Ravennuke works. Basically, when you configure Ravennuke, you select a default theme and a module that runs on your home page. You also have the ability to set up a standard message that will appear near the top of your home page (after a header area but before your home module). The message is a special type of block that is not administered through blocks administration and is displayed separately from your normal blocks. You use the "Message" application in the ACP to manage messages separately from blocks.

So, your page starts to load. The header.php program in your distribution does some housework for you (loading files behind the scenes) and then calls the themeheader function in your active theme. This displays the header area of your page, including any logos, the Nukenav menu, possibly a search box and anything else you want in your header. When themeheader is called it will display any left blocks (position = l (the letter l)). These blocks are actually displayed by calls to several functions in the mainfile program. These in turn look up the order or the "weight" of each individual block within its position. When all the active left blocks are displayed the system (header.php) then displays the message block, then any blocks that have been defined as center up, then the home module. After this footer.php is run where it displays the center down blocks, the footer area of the page and any active right blocks.

In Ravennuke 2.5, with the center top position, you will have the ability to create a block (or blocks) that go below the header area and BEFORE any active message blocks. This might be particularly useful if you want to have a "dynamic" block (one that selects images randomly from a picture gallery for instance) near the top of your page. But basically, the capability is there to give you, as administrator of your site, further choice in layout. If you choose not to set up blocks in any of the positions, of course none will be displayed.

In summary, the order of positions and layout will be:

  • header (from theme)
  • top blocks
  • message box
  • center up boxes
  • home module
  • center down boxes
  • footer
  • right blocks (unless the right block area is suppressed)