[ class tree: reportico ] [ index: reportico ] [ all elements ]
Prev Next

Running Reportico - Options

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 exmaple 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.


The Reportico run.php script

When you run Reportico in standalone mode ( i.e. not embedded in another script ) you will be running reportico with 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 be set to alter the behaviour of Reportico, such as setting what mode you enter Reportico as, what access the web user has to Reportico ( run a single report, access criteria entry, access a whole report suite, access design mode etc ) and several others.

When embedding reportico in another script or page, you generally copy the contents of this run.php script into your web content, set the embedded_report property to true and set the correctly include the fully pathed reportico.php file remotely and then set whatever parameters you want to control what project, reports and output options you want to offer the user. Note that if you are experimenting with different properties, every time you want to see their effect it may be necessary to pass the url parameter clear_session=1 to your calling script as some parameters are only brought into effect upon initial execution and session creation. See below on this page for details of how to embed Reportico.

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 :-

    // set error reporting level
    error_reporting(E_ALL);

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

    // Reserve 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", "MENU", "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";

    // 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 default output style - TABLE = one row per record, FORM = one page per record
    //$q->initial_output_style = "TABLE";

    // 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";

    // 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" 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>');

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

    //ob_end_flush();

Taking the essentials 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. Use the system default. If none is available then you may need to specify your own 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->execute();

Runs the Reportico instance to the browser current mode whether MENU, PREPARE, MAINTAIN or EXECUTE. This is the mode that is provided on the URL command line. The default is PREPARE.


Embedding a report within a web page

In order to place a fully functional report within your own web pages you need to include code similar to the above within your script. It is necessary therefore to include reportico by providing its fully pathed position. When embedding you probably also want to customise how Reportico appears ot the user. For example you may want to include a single report output within a div, or include a single graph within a div or give the user the ability to enter criteria for a singl erpeort and execute it. You may want to give user access to a single report suite but disallow entry to report menus.

To embed just the basic Reportico include something like the following in your code

    <HTML>
      <BODY>

          ...... Your web content ...... 

          <!-- Start of Reportico Report -->
          <?php
            require_once('{FULL PATH TO REPORTICO DIRECTORY}/reportico.php'); 
            $q = new reportico();
            $q->embedded_report = true;
            $q->execute();
          ?> 
          < !-- End of Reportico Report -->

          ...... More web content ......

      </BODY>
    </HTML>


Control user access to projects, reports

Using a combination of the initial_execute_mode and access_mode properties, it is possible to take a user to a specific report or specific report menu to execute report, execute a report to show just the graphs, just the report detail or just the group headers, for example. When generating report out you have control whether the user has a return button to go back to criteria entry.

initial_execute_mode indicates what type of screen user is first taken into. Valid values for initial_execute_mode are ADMIN, MENU, PREPARE or EXECUTE. ADMIN takes user to the ADMIN page, MENU takes user to a report menu ( an initial project must be specifiedd ), PREPARE takes user to the criteria entry screen of a specfic report ( project and report must be specified ) and EXECUTE runs a specified report ( project and report must be specified ).

Allow using the properties initial_project and initial_report take users directly to the specified report suite and report files respectively. If a project is controlled by a password this can be provided in the initial_project_password so the user doesnt have to type the password in.

access_mode indicates what Reportico pages and functions a user has access to. Valid options are

  • FULL

    - provides access to the Admin Page and the ability to enter Design mode, if users give the correct Admin password
  • ALLPROJECTS

    - users can use admin page to select a project (but not be able to enter admin mode). Users can select and run reports and navigate between report output, report criteria and the report project menu where users can choose a report to run. Dropdown menus ( see documentation ) can be used to swap between project reports and projects if required
  • ONEPROJECT

    users can use a single project, select and run reports and navigate between report output, report criteria and the report project menu where users can choose a report to run. Swapping between project menus in rhis mode must also be down by a dropdown menu (see documentation for how to do this)
  • ONEREPORT

    user gets access to a single report's criteria entry mode and can run the report and then jump back to criteria entry again
  • REPORTOUTPUT

    the output of a single report is presented and the user may not navigate to any other Reportico page

Example 1 - Run a single report salesforecast,xml in project sales (which is password protected with password "password" and run to HTML output.

    <HTML>
      <BODY>

          ...... Your web content ...... 

          <!-- Start of Reportico Report -->
          <?php
            require_once('{FULL PATH TO REPORTICO DIRECTORY}/reportico.php'); 
            $q = new reportico();
            $q->initial_project = "sales";
            $q->initial_project_password = "password";
            $q->initial_report = "salesforecast.xml";
            $q->initial_execute_mode = "EXECUTE";
            $q->initial_output_format = "HTML";
            $q->access_mode = "REPORTOUTPUT";
            $q->embedded_report = true;
            $q->execute();
          ?> 
          < !-- End of Reportico Report -->

          ...... More web content ......

      </BODY>
    </HTML>

Example 2 - Run the menu for project "stock" with no access to menu

    <HTML>
      <BODY>

          ...... Your web content ...... 

          <!-- Start of Reportico Report -->
          <?php
            require_once('{FULL PATH TO REPORTICO DIRECTORY}/reportico.php'); 
            $q = new reportico();
            $q->initial_project = "stock";
            $q->initial_project_password = "password";
            $q->initial_execute_mode = "MENU";
            $q->access_mode = "SInGLEPROJECT";
            $q->embedded_report = true;
            $q->execute();
          ?> 
          < !-- End of Reportico Report -->

          ...... More web content ......

      </BODY>
    </HTML>


Controlling output

When directly taking a user to report output or criteria entry you can control certain output features.

To control whether output is provided in HTML, PDF, CSV, XML or JSON format just set the initial_output_format property to HTML, PDF, CSV, XML or JSON respectively For example :-

            $q->initial_output_format = "PDF";

To control whether output includes the graph, report detail, group headers etc you can set any of the following to "show" or "hide". The default is to show all except a criteria summary at the top of the page. For example the following will show only the graph to the user.

            $q->initial_show_detail = "hide";
            $q->initial_show_graph = "show";
            $q->initial_show_group_headers = "hide";
            $q->initial_show_group_trailers = "hide";
            $q->initial_show_column_headers = "hide";
            $q->initial_show_criteria = "hide";

To control whether reports are generated as a single line per report output in multi-column format or a page of data with one line per column value, set the initial_output_style to either TABLE or FORM, e.g.

            $q->initial_output_style = "FORM";

To provide a refresh button set the following :-

            $q->show_refresh_button = true;


Reporting by user

Quite often you want to produce reports that show records relevant to the logged in user. This is especially relevant to an embedded solution. To do this you need to provide the currently logged on user in the external_user property. Then to make use of the user in your queries use the {FRAMEWORK_USER} notation. For example in your calling script put :-

To provide a refresh button set the following :-

   
            $q->external_user = $user;
            $q->execute();
and in your main query :-
   
            SELECT x, y FROM table WHERE user = {FRAMEWORK_USER}


Passing criteria parameters within embedded reports

One way of passing parameters reports is to use the "MANUAL_" method mechanism of passing parameters within the $_REQUEST record. A better way when embedding reportico or generating custom reportico scritps is to use the initial_execution_parameters array property. Just biuld this array up with the key of the criteria name ( as specified in the report criteria definitions ) and the criteria value you want used witihn the report query. For date ranges use the "-" notation and for multiple options for a list or lookup type criteria specify the values with comma separated values.

The following example runs a report for specified countries and covers the dates between the start of 2013 and today :-

            $q->initial_execution_parameters = array();
            $q->initial_execution_parameters["country"] = "Italy,Australia";
            $q->initial_execution_parameters["invoice_dates"] = "2013-01-01-TODAY";
            $q->execute();


Connecting to a framework or CMS database

Reportico can be embedded into PHP frameworks and CMS. In this case you may want to use the database connection settings from the framework rather than having to specify them again in your project definition. To achieve this, when you create to configure your project, you need to choose the "framework" database driver option. Then in your calling script, before the Reportico execute() call, you need to specify the following databse constants ( quite often CMSs or frameworks provide functions to access these values :-

    define('SW_FRAMEWORK_DB_DRIVER','<DATABASETYPE>'); e.g. pdo_mysql, pdo_pgsql, pdo_mssql etc
    define('SW_FRAMEWORK_DB_USER', $myframework->getuser());
    define('SW_FRAMEWORK_DB_PASSWORD',$myframework->getPassword());
    define('SW_FRAMEWORK_DB_HOST',$myframework->getHostName()); // Use ip:port to specifiy a non standard port
    define('SW_FRAMEWORK_DB_DATABASE',$myframework->getDatabase());
    $q->execute();


Turning on AJAX Reportico operation

In AJAX mode, all button presses are made as an AJAX call meaning that there is no full page refresh performed. This makes its operation look nicer when embedded in complex web pages. It also allows it to work alongside other web apps in a page.

To include reportico in this fashion you need to set a Reportico property alongside the other paramters. Just set For example :-

            $q->reportico_ajax_mode = true;


Namespaces - running more than one Reportico report on a single web page

It is possible to embedded reportico so that it generates several instances on a single page. You could for example chain report output together or use the hide and show options to run several reports with graphs to present only the graphs in a kind of dashboard.

To do this you need to use the namespace property to ensure that successive embedded reports do not get their sessions confused. You also need to create a new instance of reportico for each successive report to avoid other conflicts.

Note that reportico_ajax_mode is set to true. If you want to allow the user to interact wih more than one report on a page ( enter criteria, select from menus ) then you need this option to avoid full screen refreshes.

Note that currently you cannot chain together reports from different projects, this will be addressed in a future release.

This example chains together two reprts in graph mode, note the use of the namespace property :-

    require_once('<PATHTOREPORTICO>/reportico.php');
    
    // Run first report
    $q = new reportico();
    $q->allow_debug = true;
    $q->reportico_ajax_mode = true;
    $q->initial_project = "myproject";
    $q->initial_project_password = "password";
    $q->initial_report = "graph1.xml";
    $q->initial_execute_mode = "EXECUTE";
    $q->initial_show_detail = "hide";
    $q->initial_show_graph = "show";
    $q->initial_show_group_headers = "hide";
    $q->initial_show_group_trailers = "hide";
    $q->initial_show_column_headers = "hide";
    $q->initial_show_criteria = "hide";
    $q->access_mode = "REPORTOUTPUT";
    $q->embedded_report = true;
    $q->session_namespace = "GRAPH1";
    $q->show_refresh_button = true;
    $q->execute();

    // Run second report
    $q = new reportico();
    $q->allow_debug = true;
    $q->reportico_ajax_mode = true;
    $q->initial_project = "myproject";
    $q->initial_project_password = "password";
    $q->initial_report = "graph2.xml";
    $q->initial_execute_mode = "EXECUTE";
    $q->initial_show_detail = "hide";
    $q->initial_show_graph = "show";
    $q->initial_show_group_headers = "hide";
    $q->initial_show_group_trailers = "hide";
    $q->initial_show_column_headers = "hide";
    $q->initial_show_criteria = "hide";
    $q->access_mode = "REPORTOUTPUT";
    $q->embedded_report = true;
    $q->session_namespace = "GRAPH2";
    $q->show_refresh_button = true;
    $q->execute();


Using external parameters and variables within reports

If you want to pick up external system parameters such session variables or constants in tour reports you can set them in the main run.php or your own calling script. For example you might want to pass a user name,a user role or a site id. Just pass in

    $q->user_parameters["your_parameter_name"] = "your parameter value";

Then you can pick up in Reportico SQL queries using the construct {USER_PARAM,your_parameter_name}.


Prev Up Next
Reportico Installation Structure Reportico User Manual Reportico Security

Documentation generated on Fri, 26 Jul 2013 20:58:43 +0100 by phpDocumentor 1.4.3