ee-garage.com

NSM Report Class

The Nsm_report_base class is the starting point for any report as it is the class that all reports will extend.

It provides the mandatory variables and methods that define a report.

Define your report

There are a series of protected class variables that need to be set so that users can identify your reports in the Control Panel.

  • $title - is the name of the report as it will appear to the user.
  • $notes - should contain a short description of what the report does.
  • $author - is the name and/or company of the developer that built the report.
  • $docs_url - can be a hyperlink to the online reports documentation that users can view.
  • $version - is a good place to store the revision number of your report.
  • $type - tells NSM Reports what level of complexity the report should be.
  • $output_types - list the report's allowed generated report formats.
  • $config - is used as the default report configuration when generating a report. The helps preventing errors by specifying the default values first.

The other public variables are set later in the report's runtime and no not need to be altered.

protected $title = 'DEMO: Report name';
protected $notes = 'A short description of what the report does.';
protected $author = 'Name and/or company of the report developer';
protected $docs_url = 'http://www.newism.com.au';
protected $version = '1.2.3';
protected $type = 'complex';
public $output_types = array(
  'browser' => 'View in browser',
  'csv' => 'Comma-Seperated Values (CSV)',
  'tab' => 'Tab-Seperated Values (TSV)',
  'html' => 'HyperText Markup Language (HTML)',
  'xml' => 'eXtensible Markup Language (XML)'
);
protected $config = array(
  '_output' => 'browser',
  'channel_filter' => false,
  'status_filter' => false
);

Extending the report

It is important to always start your constructor method with parent::__construct() to ensure that the report is initialised the intended way.

public function __construct(){parent::__construct();}

A simple example

A very basic report will extend the Nsm_report_base class and override the generateResults() method to assemble a different SQL statement and return the data results as an array.

public function generateResults()
{
  $sql = "SELECT
    `p`.`entry_id` AS `ID`,
    `p`.`title` AS `Title`,
    `p`.`url_title` AS `URL Title`,
    `c`.`channel_title` AS `Channel Name`
  FROM `exp_channel_titles` AS `p`
  LEFT JOIN `exp_channels` AS `c`
    ON `c`.`channel_id` = `p`.`channel_id`
  ORDER BY `p`.`channel_id`";
  
  $query = $this->EE->db->query($sql);
  if ($query == false){
    return false;
  }
  return $query->result_array();
}

Complex report extensions

Generating your SQL

A more complex report will use user-input data collected on the report configuration form to build a SQL statement and return an array of data results.

public function generateResults()
{
  $config = $this->config;
  
  $channel_cond = ($config['channel_filter'])
    ? " AND `t`.`channel_id` = '".intval($config['channel_filter'])."'"
    : false;
  $status_cond = ($config['status_filter'])
    ? " AND `t`.`status` = '".$config['status_filter']."'"
    : false;
  
  $sql = "SELECT
    `t`.`entry_id` AS `id`,
    `t`.`title` AS `name`,
    `t`.`entry_date` AS `created_at`,
    `t`.`url_title` AS `url_title`,
    `t`.`status` AS `status`,
    `t`.`channel_id` AS `channel_id`,
    `c`.`channel_title` AS `channel_name`
  FROM `exp_channel_titles` AS `t`
  LEFT JOIN `exp_channels` AS `c`
    ON `c`.`channel_id` = `t`.`channel_id`
  WHERE `t`.`channel_id` > 0 " . 
    $channel_cond .
    $status_cond .
  "
  ORDER BY `t`.`channel_id`,
    `t`.`title`";
  
  $query = $this->EE->db->query($sql);
  if ($query == false){
    return false;
  }
  return $query->result_array();
}

Capturing user input

The power of a complex report comes from this ability to define a configuration form to capture user input in order to generate different report data. It is recommended that you use the configHTML() method in the example class Channels_complex_report as a starting point and live example of collecting existing data and passing the information to the Code-Igniter View loading function.

public function configHTML()
{
  $channels = $this->EE->db->query('
    SELECT 
      `exp_channels`.`channel_id`, 
      `exp_channels`.`channel_title` AS `title`
    FROM `exp_channels`
    ORDER BY `channel_title`'
  );
  $status_options = $this->EE->db->query('
    SELECT DISTINCT
      `exp_channel_titles`.`status`
    FROM `exp_channel_titles`
    ORDER BY `exp_channel_titles`.`status`'
  );
  
  $data = array(
            'config' => $this->config,
            'channels' => $channels->result_array(),
            'status_options' => $status_options->result_array()
          );

  if(APP_VER < '2.1.5') {
    // EE < .2.2.0
    return $this->EE->load->_ci_load(array(
      '_ci_vars' => $data,
      '_ci_path' => $this->report_path . 'views/configuration.php',
      '_ci_return' => true
    ));
  }else{
    $this->EE->load->add_package_path($this->report_path);
    return $this->EE->load->view('configuration', $data, TRUE);
  }
}

Any information that is collected on the report configuration form is captured and assigned to the report class via the setConfig() method. This new user input is merged with the class's original configuration details to allow the default values to remain present until overwritten.

Extending output types

You can extend a report by adding new output types. Pushing a new entry to the report's $output_types array will provide a new option that can be chosen by the user when a report is generated. You will need to add a new method in your report to process the report data and generate the output for the new $output_type entry. The method needs to be named in a particular way with the prefix output_ followed by the new output type array key.

public $output_types = array(
  'browser' => 'View in browser',
  'csv' => 'Comma-Seperated Values (CSV)',
  'tab' => 'Tab-Seperated Values (TSV)',
  'html' => 'HyperText Markup Language (HTML)',
  'xml' => 'eXtensible Markup Language (XML)',
  'xls' => 'Excel Spreadsheet'
);

public function output_xls($results)
{
  $xls = '"ID","Title","Date Created","Status","Channel"';
  foreach($results as $row_i => $row){
    $xls .= "\n" .
      '"' . $row['id'] . '",' . 
      '"' . $row['name'] . '",' . 
      '"' . date('d/m/Y', $row['created_at']) . '",' . 
      '"' . ucwords($row['status']) . '",' . 
      '"' . $row['channel_name'] . '"';
  }
  return $xls;
}
Releases RSS Feed © Copyright 2017 | Policies All prices shown are in Australian Dollars ($AUD) Newism