Lamplight API examples - organisation listing

Any data shown on this page is fictious - this is an example!

The example

Listing organisations

found 9 organisations


  1. Advocacy Organisation

    more...
  2. Community Centre

    more...
  3. Good News Church

    more...
  4. Healthy Living Centre

    more...
  5. Mental Health Organisation

    more...
  6. Night Shelter

    more...
  7. Support Organisation

    more...
  8. The Older Persons Charity

    more...
  9. Young Peoples Charity

    more...

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.