Recent Changes Printable View Page History Edit Page

A layout is a way of formatting data from OpenBiblio for use outside of OpenBiblio. Usually, layouts format data for printing, but you could use a layout to put data into a format like MARC or RSS.

Currently, layouts must be written in PHP, so some familiarity with that language is assumed here. Hopefully, we'll make an easier way to write layouts at some time, but that time isn't now.

Layout basics

Here's the basic skeleton of a layout:

<?php

class Layout_name {
  function render($rpt) {
    while ($row = $rpt->next()) {
      # do something
    }
  }
}

That defines a layout named 'name'. In order for reports to be able to call on this layout, you need to put it in a file .../layouts/name.php. Note that the name in the filename (before .php) and the name in the class name (after Layout_) must be the same.

When the layout is used, the render() method is called with the report results as argument. Iterating through those results with the ->next() method will give you each row in turn as an associative array. So if the report has a column named 'foo', then you can get at that column's data in the while loop using $row['foo'].

Here's a layout that just prints the 'title' column of a report, one title per line:

<?php

class Layout_titletxt {
  function render($rpt) {
    header('Content-type: text/plain');
    while ($row = $rpt->next()) {
      echo $row['title']."\n";
    }
  }
}

That isn't very useful, but you can use any PHP code you want in your layout, so if you're ready to write your own code, you can stop here.

What about printing?

Most layouts are intended for printing, and to do that, they make PDFs. There are any number of ways of making a PDF from PHP, and the layout system doesn't care which one you use -- just make sure the libraries you need are installed on the server. However, there are two modules for making PDFs that come with OpenBiblio. One is called PDF and is a pretty low-level interface that's based on FPDF. PDF isn't really intended for general use, but the other module, called Lay, builds on PDF to make a very flexible system for laying text out on pages.

Lay

Lay allows you to pack containers (like a page, line, or column) with elements (like a word or picture). Containers are also elements, so you can place them inside one another. You can think of a layout that uses Lay as a bunch of boxes inside one another. The kinds of boxes and how they are placed inside one another determine where the words and pictures appear on the page. Let's start with the simplest example:

<?php
require_once('../classes/Lay.php');

class Layout_hello {
  function render($rpt) {
    $lay = new Lay;
      $lay->container('TextLine');
        $lay->text('Hello, World!');
      $lay->close();
    $lay->close();
  }
}

The first thing to do is include the Lay module itself. Then in the render method, we create an instance of the Lay class. When we do this, Lay initializes its layout engine and opens the top-level container.

In Lay, there is always a set of open containers, one inside another. The innermost of these containers is the one we're placing elements or new containers in right now. The top-level container in lay produces a page in the PDF for every element placed inside it.

The next line opens a new container by calling Lay's container() method. When you open a container, it's placed inside the container that's currently opened. The first argument to container() specifies what kind of container we're opening. Here, we're creating a TextLine. A TextLine is intended to contain words that are laid out in a single line without wrapping. Now we have 2 containers open: the top-level container, and a TextLine.

To place words on this TextLine, we call the text() method with the string we want to add. The text() method splits a string into words and adds each word as an element to the current container.

Once we are done with a container, we need to close it. The next two lines close first the TextLine, then the top-level container. Closing the top-level container ends the document.

To be continued...

SourceForge.net Logo
Edit Page - Page History - Printable View - Recent Changes - Search
Page last modified on December 17, 2008, at 07:36 AM