Lamplight API examples - organisation listing

The code

As in all these examples, we're using the php Lamplight_Client class, which makes constructing requests a bit easier. First, set up the client

     $client = new Lamplight_Client('', array(
       'key'     => LAMPLIGHT_APIKEY,
       'lampid'  => LAMPLIGHT_ID,
       'project' => LAMPLIGHT_PROJECT
    ));   
    

This gives us an Http Client with the authentication parameters set (we use an include to define the LAMPLIGHT_APIKEY, LAMPLIGHT_ID and LAMPLIGHT_PROJECT constants). We don't need to pass a uri because the Lamplight_Client does it for us.

Next, tell it what we want to fetch, and make the request:

$orgResponse = $client->fetchOrgs("user")
                      ->fetchAll()
                      ->request();
    

NEW in version 1.11 is the ability to request more or less data in calls to fetchAll() or fetchSome(). The default is a small, quick response - the default setting. However, you can change this to request a bigger (and unavoidably slightly slower) response with all publishable data - the same as you'd get by requesting fetchOne(). To do this, use the new returnFullData() on the Lamplight_Client before making the request:

$orgResponse = $client->fetchOrgs("user")
                      ->fetchAll()
                      ->returnFullData()
                      ->request();
    

The Zend_Http_Response returned (see Zend Framework API docs has some useful methods: we use isError() and getStatus() to check we've got something back with a 200 response, and then getBody() to retrieve the json encoded data. It's then a simple step to decode it and iterate over the data returned to write out some data.

To do this, you would do something like this:

$orgList = json_decode($jsonOrgs);

foreach($orgList->data as $org) {
    echo '
' . htmlentities($org->name, ENT_QUOTES, "UTF-8") . '
';
    // echo other data we want here... $org has summary and id properties here.
}
    

However, Lamplight_Client can do a lot of this for you. In this example we actually retrieve a Lamplight_RecordSet from the client:

$recs = $client->getRecordSet();
  

What's happening here? The call to getRecordSet() actually does the following:

1. Checks that a request has been made. The last response is used to get the data from
2. Lamplight_RecordSet has a static factory method that uses the Lamplight_Client to check the status (for 200 OK), and then builds a set of Lamplight_Record* instances, one for each record in the returned data.
3. The record class used will be one of:
   • Lamplight_Record_WorkSummary
   • Lamplight_Record_Work
   • Lamplight_Record_PeopleSummary
   • Lamplight_Record_People
   • Lamplight_Record_OrgsSummary
   • Lamplight_Record_Orgs
   • Lamplight_Record_WorkareaSummary
   depending on the request (*Summary classes are used for some or all calls). In fact, each of these classes extend the abstract class Lamplight_Record_Abstract (or classes which extend this abstract class), which does all the work: these classes have no additional methods/properties and may be extended by implementers to add custom functionality.
4. These records are put in a new Lamplight_RecordSet class (which can only be instantiated by the factory method) which is returned.

This Lamplight_RecordSet instance (which implements the Iterator interface) has a couple of convenience methods. $recset->count() gives you the number of records and $recset->plural() returns an 's' if there's no records or more than one record. More interesting is the render() method. Here's how it's used in this example:

  $recordTemplate = '<li><h4>{name}</h4><p>{summary}</p>'
     . '<a href="orgdetail.php?id={id}" title="see more info on {name}">'
     . 'more...</a>'
     . '</li>';
  echo $recs->render($recordTemplate); 
  

render($template) takes a simple template string and for each record substitutes field values for placeholders. Placeholders should be of the form {fieldname}. Each field is rendered using the renderField method of the Lamplight_Record_Abstract class, which may be overloaded in sub-classes to provide custom formatting (for example of date strings).

So the entire code to generate the list in this example is:

/**
 * Set up the new Http_Client (constants defined in an include file)
 */
$client = new Lamplight_Client('', array(
   'key'     => LAMPLIGHT_APIKEY,
   'lampid'  => LAMPLIGHT_ID,
   'project' => LAMPLIGHT_PROJECT
));


// Set up the client to fetch all orgs
$client->fetchOrgs("user")
       ->fetchAll()
       ->request();
                      


// Build a record set
$recs = $client->getRecordSet();


// If there were errors, stop here:
if ($recs->getErrors()) {

  echo 'Unfortunately there was a problem showing this page.';  // You would probably want to do a bit more here!

} else {

  // Some intro html
  ?>

  <h3>Listing organisations</h3>
  <p>found <?php echo $recs->count() . " organisation" . $recs->plural();?> </p>
  <br/>
  <ol>
  
  <?php
  $recordTemplate = '<li><h4>{name}</h4><p>{summary}</p>'
     . '<a href="orgdetail.php?id={id}" title="see more info on {name}">'
     . 'more...</a>'
     . '</li>';
  echo $recs->render($recordTemplate);
  
  
  ?>
  </ol>
  <?php
}  
  

For pages like this, we would strongly recommend a cacheing strategy, which will dramatically improve performance.