Configuring Reportico - System Parameters

Configuring Reportico

Reportico is designed to run reports either as a standalone report designer or for embedding in your own web sites. Reports can be invoked directly vis web links. There are several ways reportico can be configured.

• By running standalone reportico and passing URL parameters to control what reports to run etc

• By creating a custom standalone copy of the runner script ( copying the run.php file described below ) and setting runtime parameters to control user rights, to pass external paramters to reports ( such as user logins etc ), to turn off and on certain report output. See the run.php script below for more details

• By embedding reportico within your web pages and utilising the same parameters mentioned in the run.php script to control the appearance and operation of reportico, but customised to work within your web page

Running Reportico reports by specifying URL parameters

As you can see, once you have created some reports you can access them from the Administration page by pointing your browser at the index.php file in the Reportico directory. However you can also access reports more directly by specifying the relevant information as part of the URL. For example you can :-

• Directly access a report project menu

• Run a report specifying all report criteria and the output format in the URL

• With JSON and XML output format you can effectively turn your report suite into a web API

• Guide users directly to specified report without going through the menu, allowing you to build your own menu front end to reports

• Embed reportico and report output within your web pages

• Run Reportico from a Linux command line (using for example wget) , allowing you to save reports and email them to recipients

In order to achieve the above, you need to point your browser at the run.php in your Reportico area and provide various parameters to identify which project you want to run and what mode - menu mode (the default), report preparation/criteria entry mode or design mode. To generate report output you need to specify the report xml file name, the report output format ( HTML, PDF, CSV, JSON, XML ) and also the criteria. criteria and output format (HTML, PDF, CSV) within the URL. Exampes follow below but a list of available parameters is provided in Appendix 2 - Reportico URL request parameters.

Below find examples of simple common options for running Reportico from the browser :-

To run a report menu for a project which is restricted by a password, enter:

    http://{HOST}/{REPORTICO_DIR}/run.php?execute_mode=MENU&project={PROJECTCODE}&project_password={PASSWORD}

To run a specific report in criteria entry mode:

    http://{HOST}/{REPORTICO_DIR}/run.php?execute_mode=PREPARE&
                           project={PROJECTCODE}&xmlin={REPORT}.xml

To generate HTML output for a report. :

    http://{HOST}/{REPORTICO_DIR}/run.php?execute_mode=EXECUTE&
                          project={PROJECTCODE}&xmlin={REPORT}.xml&
                          target_format=HTML

To generate XML output for a report - just change the XML to PDF, CSV or JSON for those formats :

    http://{HOST}/{REPORTICO_DIR}/run.php?execute_mode=EXECUTE&
                          project={PROJECTCODE}&xmlin={REPORT}.xml&
                          target_format=XML

To generate HTML output for, for example, all invoices from 1st August 2011 to Today for raised for customers living in London or Paris you might do:- :

    http://{HOST}/{REPORTICO_DIR}/run.php?execute_mode=EXECUTE&
                          project={PROJECTCODE}&xmlin={REPORT}.xml&
                          target_format=HTML&MANUAL_daterange_FROM=2011-08-01&MANUAL_daterange_TO=TODAY%MANUAL_city=London,Paris

To Run a specific report in design mode in a password unprotected project:

http://{HOST}/{REPORTICO_DIR}/run.php?execute_mode=MAINTAIN&
                           project={PROJECTCODE}&xmlin={REPORT}.xml

Execution Modes

Reportico may be run in one of 4 modes as specified with the execute_mode URL parameter :-

1. MENU

   Presents the report menu for the desired project. Uses the menu.php file found within the project area for the menu definitions and menu title.

2. PREPARE

   Runs a report in preparation/criteria entry mode. It is in this mode that the user selects report criteria and can then generate the report output in the desired format. Also, if enabled, the user can enter report design mode from the prepare screen. Running an existing report requires that the project name and the report XML definition file is passed. If no report name is passed then the new report definition will be used.

   It is this mode that is entered when you select one of the rpeorts from a menu.

3. MAINTAIN

   Runs the report in design mode. It is in this mode that all the report configuration can be maintained. Reports can be created, modified and stored. Here reports are configured by entry of SQL data access queries, formatting, criteria, groups, graphs etc. Again the project and report definition must be provided to enter this mode directly.

4. EXECUTE

   This is report output generation mode. The report switches to this mode when the user presses the Execute button in Prepare mode. To run a report directly in this mode, the project and report definition file must be provided as well as the output method (HTML,PDF etc) as well as any other output options. See the example above and Appendix 2 - Reportico URL request parameters.

Customising Reportico - The Reportico run.php script

When you run Reportico in standalone mode ( i.e. not embedded in another script ) you will, by default, be running reportico via the run.php script. This script creates an instance of reportico and allows Reportico to run in your browser. Within this script there are several parameters than can control Reportico's behaviour, such as:-

• Specifying what mode ( report menu, criteria, report output ) to start in

• Specifying what access web user has ( Single report output, single report crtieria entry, project menu or full access to admin functions

• Hiding some of reportico's user interface elements to simplify the screen

• Specfying external parameters that can be included in report queries - such as user logins, session parameters etc

• Specifying an SQL query to generate report output from without having to create a specific report

• Specifiying whether to run using bootstrap or classic stylings

• Specifying which charting engine to use

• Specifying whether to turn on dynamic sortable/searchable grids

• Specifying menu definitions ( dropdown and static )

To customise Reportico you can just edit the run.php to set system parameters, or you can copy this script for each of the different ways you want to call Reportico. You can create copies outside of the main Reportico folder but be sure to modify the line which includes reportico to set its fully pathed location. If you do copy this script then, depending on the parameters you have configured, it will probably be necessary to uncomment the line:-

        $q->reportico_ajax_script_url = $_SERVER["SCRIPT_NAME"];

Also if you are embedding reportico in different scripts it is a good idea to use a namespace in each place, so that if you swap between them in a browser session they dont interfere with each other.

The runner looks as follows :-

<?php
/*
 Reportico - PHP Reporting Tool
 Copyright (C) 2010-2014 Peter Deed

 This program is free software; you can redistribute it and/or
 modify it under the terms of the GNU General Public License
 as published by the Free Software Foundation; either version 2
 of the License, or (at your option) any later version.
 
 This program is distributed in the hope that it will be useful,
 but WITHOUT ANY WARRANTY; without even the implied warranty of
 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 GNU General Public License for more details.

 You should have received a copy of the GNU General Public License
 along with this program; if not, write to the Free Software
 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.

 * File:        run.php
 *
 * Reportico runner script
 *
 * @link http://www.reportico.org/
 * @copyright 2010-2013 Peter Deed
 * @author Peter Deed <info@reportico.org>
 * @package Reportico
 * @license - http://www.gnu.org/licenses/gpl-2.0.html GNU/GPL
 * @version $Id: run.php,v 1.24 2014/05/17 12:39:08 peter Exp $
 */

    // set error reporting level
	error_reporting(E_ALL);

    // Set the timezone according to system defaults
    date_default_timezone_set(@date_default_timezone_get());

    // Reserver 100Mb for running
	ini_set("memory_limit","100M");

    // Allow a good time for long reports to run. Set to 0 to allow unlimited time
	ini_set("max_execution_time","90");

    // Include Reportico - for embedding reportico in a script running from outside the Reportico directory, 
    // just include the full path to the file reportico.php
	//require_once('<FULL_PATH_TO_REPORTICO>/reportico.php');
	require_once('reportico.php');

    // Only turn on output buffering if necessary, normally leave this uncommented
	//ob_start();

	$q = new reportico();

    // In design mode, allow sql debugging
	//$q->allow_debug = true;

    // Specify any URL parameters that should be added into any links generated in Reportico.
    // Useful when embedding in another application or frameworks where requests need to be channelled
    // back though themselves
	//$q->forward_url_get_parameters = "";

    // Reportico Ajax mode. If set to true will run all reportico requests from buttons and links
    // through AJAX, meaning reportico will refresh in its own window and not refresh the whole page
    //$q->reportico_ajax_mode = true;

    /*
    ** Initial execution states .. allows you to start user and limit user to specfic
    ** report menus, reports or report output
    ** The default behaviour is to show the Administration page on initial startup
    */

    // Start user in specific project
    //$q->initial_project = "<project>";          

    // If starting user in specific project then project passweord is required if one exists
    // and you dont want user to have to type it in
    //$q->initial_project_password = "<project password>";

    // Specify a report to start user in specify the xml report file in the specified project folder
    //$q->initial_report = "reportfile.xml";

    // Specify whether user is started in administration page, project menu, report criteria entry, 
    // report output or report design mode, use respectively ( "ADMIN", "u$q->get_execute_mode(), true);ENU", "PREPARE", "EXECUTE", "MAINTAIN")
    // default is "ADMIN"
    //$q->initial_execute_mode = "<MODE>";

    // When only executing a report, indicates what format it should be showed in .. HTML(the default), PDF or CSV
    //$q->initial_output_format = "HTML";

    // When initial mode is report criteria entry or execution, these set the flags for whether report detail, group hears, columns headers
    // etc are to be show. For example you might only want to run a report and show the graphs, by default all show except criteria
    //$q->initial_show_detail = "show";
    //$q->initial_show_graph = "show";
    //$q->initial_show_group_headers = "show";
    //$q->initial_show_group_trailers = "show";
    //$q->initial_show_column_headers = "show";
    //$q->initial_show_criteria = "show";

    // Set default output style - TABLE = one row per record, FORM = one page per record
    //$q->initial_output_style = "TABLE";

    // Set source SQL to generate report from, without requirement for report , requires an initial_project to be defined for connection details
    //$q->initial_sql = "SELECT column1 AS columntitle1, column2 AS columntitle2 FROM table";

    // Specify access mode to limit what user can do, one of :-
    // FULL - the default, allows user to log in under admin/design mode and design reports
    // ALLPROJECTS - allows entry to admin page to select project  but no ability to logon in admin/designer mode
    // ONEPROJECT - allows entry to a single project and no access to the admin page
    // ONEREPORT - limits user to single report, crtieria entry and report execution ( requires initial project/report )
    // REPORTOUTPUT - executes a report and allows to "Return" button to crtieria entry ( requires initial project/report )
    //$q->access_mode = "<MODE>";

    // Default initial execute mode to single report output if REPORTOUTPUT mode specified
    if ( $q->access_mode == "REPORTOUTPUT" )
        $q->initial_execute_mode = "EXECUTE";

    // The session namespace to use. Only relevant when showing more than one report in a single page. Specify a name
    // to store all session variables for this instance and then when running another report instance later in the script 
    // use another name
    //$q->session_namespace = "namespace";

    // Current user - when embedding reportico, you may wish to run queries by user. In this case
    // set the current user here. Then you can use the construct {FRAMEWORK_USER} within your queries
	//$q->external_user = "<CURRENT USER>";

    // Indicates whether report output should include a refresh button
    //$q->show_refresh_button = false;

    // Set to true if you are embedding in another report
    $q->embedded_report = false;

    // Specify an alternative AJAX runner from the stanfdard run.php
    //$q=>reportico_ajax_script_url = $_SERVER["SCRIPT_NAME"];


    // If you want to connect to a reporting database whose connection information is available in the calling
    // script, then you should configure your project connection type to "framework" using the configure project link
    //and then you can pass your connection info here
    //define('SW_FRAMEWORK_DB_DRIVER','pdo_mysql');
    //define('SW_FRAMEWORK_DB_USER', '<USER>');
    //define('SW_FRAMEWORK_DB_PASSWORD','PASSWORD');
    //define('SW_FRAMEWORK_DB_HOST', '127.0.0.1'); // Use ip:port to specifiy a non standard port
    //define('SW_FRAMEWORK_DB_DATABASE', '<DATABASENAME>');

    // For passing external user parameters, can be referenced in SQL with {USER_PARAM,parameter_name}
    // and can be referenced in custom SQL with $this->user_parameters
    //$q->user_parameters["your_parameter_name"] = "your parameter value";

    // Jquery already included?
    //$q->jquery_preloaded = false;

    // Bootstrap Features
    // Set bootstrap_styles to false for reportico classic styles, or "3" for bootstrap 3 look and feel and 2 for bootstrap 2
    // If you are embedding reportico and you have already loaded bootstrap then set bootstrap_preloaded equals true so reportico
    // doestnt load it again.
    $q->bootstrap_styles = "2";
    $q->bootstrap_preloaded = false;

    // Engine to use for charts .. 
    // HTML reports can use javascript charting, PDF reports must use PCHART
    //$q->charting_engine = "PCHART";
    //$q->charting_engine_html = "NVD3";

    // Whether to turn on dynamic grids to provide searchable/sortable reports
    // $q->dynamic_grids = true;
    // $q->dynamic_grids_sortable = true;
    // $q->dynamic_grids_searchable = true;
    // $q->dynamic_grids_paging = false;
    // $q->dynamic_grids_page_size = 10;

    // Generate report definition from SQL  and set some column / report attributes
    // Also the full report definition can be built up programmatically
    // which requires further doicumentation
    //$q->importSQL(""SELECT column1 AS columntitle1, column2 AS columntitle2 FROM table";
    //$q->get_column("column1")->set_attribute("column_display","hide");
    //$q->get_column("column1")->set_attribute("column_title","Custom Title");
    //$q->set_attribute("ReportTitle","New Report Title");

    // Show or hide various report elements
    //$q->output_template_parameters["show_hide_navigation_menu"] = "show";
    //$q->output_template_parameters["show_hide_dropdown_menu"] = "show";
    //$q->output_template_parameters["show_hide_report_output_title"] = "show";
    //$q->output_template_parameters["show_hide_prepare_section_boxes"] = "show";
    //$q->output_template_parameters["show_hide_prepare_pdf_button"] = "show";
    //$q->output_template_parameters["show_hide_prepare_html_button"] = "show";
    //$q->output_template_parameters["show_hide_prepare_print_html_button"] = "show";
    //$q->output_template_parameters["show_hide_prepare_csv_button"] = "show";
    //$q->output_template_parameters["show_hide_prepare_page_style"] = "show";

    // Static Menu definition
    // ======================
    // identifies the items that will show in the middle of the project menu page.
    // If not set will use the project level menu definitions in project/projectname/menu.php
    // To have no static menu ( for example if you just want to use a drop down then set to empty array )
    // To define a static menu, follow the example here.
    // report can be a valid report file ( without the xml suffix ).
    // If title is left as AUTO then the title will be taken form the report definition
    // Use title of BLANKLINE to separate items and LINE to draw a horizontal line separator

    //$q->static_menu = array (
	    //array ( "report" => "an_xml_reportfile1", "title" => "<AUTO>" ),
	    //array ( "report" => "another_reportfile", "title" => "<AUTO>" ),
	    //array ( "report" => "", "title" => "BLANKLINE" ),
	    //array ( "report" => "anotherfreportfile", "title" => "Custom Title" ),
	    //array ( "report" => "", "title" => "BLANKLINE" ),
	    //array ( "report" => "andanother", "title" => "Another Custom Title" ),
	//);

    // To auto generate a static menu from all the xml report files in the project use
    //$q->static_menu = array ( array ( "report" => ".*\.xml", "title" => "<AUTO>" ) );
    
    // To hide the static report menu
    //$q->static_menu = array ();

    // Dropdown Menu definition
    // ========================
    // Menu items for the drop down menu
    // Enter definition for the the dropdown menu options across the top of the page
    // Each array element represents a dropdown menu across the page and sub array items for each drop down
    // You must specifiy a project folder for each project entry and the reportfile definitions must point to a valid xml report file
    // within the specified project
    //$q->dropdown_menu = array(
    //                array ( 
    //                    "project" => "projectname",
    //                    "title" => "dropdown menu 1 title",
    //                    "items" => array (
    //                        array ( "reportfile" => "report" ),
    //                        array ( "reportfile" => "anotherreport" ),
    //                        )
    //                    ),
    //                array ( 
    //                    "project" => "projectname",
    //                    "title" => "dropdown menu 2 title",
    //                    "items" => array (
    //                        array ( "reportfile" => "report" ),
    //                        array ( "reportfile" => "anotherreport" ),
    //                        )
    //                    ),
    //            );


    // Run the report
	$q->execute();

	//ob_end_flush();
?>

Taking the essential lines at a time :-

        error_reporting(E_ALL);

Sets full error reporting, which is useful when debugging reports - this can be turned off or commented out as required.

        date_default_timezone_set(@date_default_timezone_get())

The reporting engine works with dates and needs a system timezone to be set. If not it is forced to a UK timezone.

        ini_set("memory_limit","100M");

For more complex reports, more memory may be required than allowed by the existing PHP config. This allocates 100 Mb but can be changed or commented out as required.

        ini_set("max_execution_time","90");

For complex reports, some time may be needed to run them, this should allow enough time for most reports to run without the script exiting.

    require_once('reportico.php');

Includes the reporting class that is responsible for all the capabilities of Reportico such as menus, report design, report criteria entry and output generation.

    $q = new reportico();

Creates an instance of the reporting tool in variable $q.

    $q->allow_debug = true;

Enables debug mode. When running a report, a debug list box will appear. The user can then get information about the database calls made while the report is being generated.

    $q->forward_url_get_parameters = "";

Specifies a list of URL GET parameters which are included in all invocations of this calling script and all links presented while running Reportico. This is useful when embedding Reportico within web frameworks that rely on parameters being used to control navigation around the site. Specify in the form <param1=value1&param2=value2>

    $q->execute($a->get_execute_mode(),true);

Enters the reporting tool in the current mode whether MENU, PREPARE, MAINTAIN or EXECUTE. This is the mode that is provided on the URL command line. The default is PREPARE.

For more detalis on all the configuration options see the next page 'Embedding Reportico in a Web Page'