From a87bbe22a7db9d3ac9e201f1de9e0c6e0b50c38a Mon Sep 17 00:00:00 2001 From: Jeremy Dorn Date: Mon, 2 Jul 2012 20:23:31 -0700 Subject: [PATCH] Added installation instructions and documentation on the pre-defined Filters. --- README.md | 211 ++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 205 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index a207939d..9193f76b 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ A light weight, extendable, PHP reporting framework for managing and displaying Major features include: * Display a report from any data source that can output tabular data (SQL, MongoDB, PHP, etc.) -* Output reports in HTML, XML, CSV, JSON, or pretty much any other format +* Output reports in HTML, XML, CSV, JSON, or your own custom format * Add customizable parameters to a report (e.g. start date and end date) * Support for graphs and charts with the Google Data Visualization API * Easily switch between database environments (e.g. Production, Staging, and Dev) @@ -122,6 +122,30 @@ Now, we'll dig into the various report headers available, the different output f and how to extend the Php Reports Framework to make it your own. +Installation Instructions +================= + +First, download a pre-packaged zip or tar file or get the latest code from git: + +``` +git clone git://github.com/jdorn/php-reports.git +cd php-reports +git submodule init +git submodule update +``` + +Then, set up the config file that defines things like database connections, file paths, etc. + +You can use the sample config as a starting point if you want. + +``` +cp config/config.php.sample config/config.php +``` + +The config settings are commented and should be pretty self explanatory. + +After that, it's time to make some reports! Detailed report documentation is below. + Detailed Documentation ================= @@ -153,6 +177,18 @@ Many headers also have a shortcut syntax for one or more common use cases. declarations are also possible with single quoted values and unquoted or single quoted strings. +Here's an example SQL report: + +```sql +-- This is the report name +-- HEADERNAME: { +-- "param1": "value1" +-- } +-- HEADERNAME2: shortcut, syntax + +SELECT * FROM ... +``` + VariableHeader ------------- @@ -167,8 +203,9 @@ Used to prompt a user for a value before running a report. * "text" (the default) * "select" (dropdown list) * "textarea" - * "date" (will be parsed with strtotime and turned into "YYYY-MM-DD HH:MM:SS" format) -* __options__ If the variable type is "select", this should be an array of choices. + * "date" (will be parsed with strtotime) +* __format__ If type is "date", this specifies the date format to convert to. It defaults to "YYYY-MM-DD HH:MM:SS". +* __options__ If the type is "select", this should be an array of choices. * __default__ The default value for the variable. * __empty__ If set to true, the report will run even if the value is empty. * __multiple__ If set to true, multiple values can be chosen. @@ -404,9 +441,9 @@ a string or date column followed by one or more number columns. Histograms requ ### JSON Format * __columns__ An array of columns to use in the chart. Columns can be specified by column number (starting at 1) or column name. Defaults to all columns in order. * __type__ The type of chart. Possible values are: - * LineChart - * GeoChart - * AnnotatedTimeline + * LineChart (the default) + * GeoChart (map) + * AnnotatedTimeline (similar to Google Finance) * BarChart * ColumnChart * __title__ An optional title for the chart @@ -439,3 +476,165 @@ CHART: { } ``` This will display a histogram of product prices. Data will be broken up into 10 buckets and displayed as a column chart. + +Filters +=================== + +Filters modify data in a column after running a report, but before displaying it. + +All Filter classes extend FilterBase. + +Filters are applied with the FILTER header as follows: + +``` +FILTER: { + "filter": "geoip", + "column": 1, + "params": {} +} +``` + +For the 1st column in every row, the following will be called. + +``` +$value = geoipFilter::filter($value, $params); +``` + +A column can have more than 1 filter and they will be applied in the order they appear in the headers. + +htmlFilter +----------------- +This marks a column as containing html data. Normally all report data is escaped before outputting. This filter turns off escaping. + +This filter has no parameters. + +``` +FILTER: { + "filter": "html", + "column": "My Data" +} +``` + +If a column contains: + +```html +Data +``` + +It would normally be output as: + +```html +<strong>Data</strong> +``` + +After the htmlFilter is applied, it will output in it's original format and you will be able to see the bold text. + +preFilter +----------------- +This wraps a column's contents in pre tags. It is useful if you want to preserve white space in a column. + +This filter has no parameters. + +``` +FILTER: { + "filter": "pre", + "column": 2 +} +``` + +hideFilter +----------------- +This removes a column from a report. This is useful if you want to use some columns just as a source of data for charts. + +This filter has no parameters. + +``` +FILTER: { + "filter": "hide", + "column": 3 +} +``` + +geoipFilter +------------------ +This converts ip addresses into human readable locations. It requires the geoip php extension to work. + +This filter has no parameters. + +``` +FILTER: { + "filter": "geoip", + "column": "ip" +} +``` + +This will convert: +``` +173.194.33.3 +``` +Into: +``` +Mountain View, CA +``` + +classFilter +-------------------- +Add a css class to the column. + +``` +FILTER: { + "filter": "class", + "column": 1, + "params": { + "class": "right" + } +} +``` + +There are a couple of pre-defined css classes that are useful, but feel free to add your own to the template. +* right (right aligned) +* center (center justified) + +barFilter +--------------------- +Turns a numeric column into a horizontal bar chart. All bars will be scaled to the highest value in the column. + +``` +FILTER: { + "filter": "bar", + "column": 2, + "params": { + "width": 300 + } +} +``` + +The 'width' parameter specified the maximum bar width in pixels. It defaults to 200px. + +linkFilter +---------------------- +Turns a column into a link. The value of the column is used as the href. + +``` +FILTER: { + "filter": "link", + "column": 1, + "params": { + "display": "View", + "blank": true + } +} +``` + +This will turn the following: +``` +http://localhost/product/view/1/ +``` +Into: +``` +View +``` + +By default, the 'display' parameter is set to the href value. + +The 'blank' parameter, if set to true, will open the link in a new window. The default is false. \ No newline at end of file