Static helper class that provides methods for dealing with reports.

Provides several generally useful methods and also includes resource management.

package Client

 Methods

Method to link up the external css or js files associated with a set of code.

add_resource(string $resource) 
InheritedStatic

This is normally called internally by the control methods to ensure the required files are linked into the page so does not need to be called directly. However it can be useful when writing custom code that uses one of these standard libraries such as jQuery. Ensures each file is only linked once.

inherited_from \helper_base::add_resource()

Parameters

$resource

string

Name of resource to link. The following options are available:

  • jquery
  • openlayers
  • graticule
  • clearLayer
  • addrowtogrid
  • indiciaMapPanel
  • indiciaMapEdit
  • georeference_google_search_api
  • google_search
  • locationFinder
  • createPersonalSites
  • autocomplete
  • indicia_locks
  • jquery_cookie
  • jquery_ui
  • jquery_ui_fr
  • jquery_form
  • json
  • reportPicker
  • treeview
  • treeview_async
  • googlemaps
  • multimap
  • virtualearth
  • google_search
  • fancybox
  • flickr
  • treeBrowser
  • defaultStylesheet
  • validation
  • plupload
  • jqplot
  • jqplot_bar
  • jqplot_pie
  • jqplot_category_axis_renderer
  • jqplot_trendline
  • reportgrid
  • tabs
  • wizardprogress
  • spatialReports
  • jsonwidget
  • timeentry
  • verification

Internal method to build a control from its options array and its template.

apply_template(string $template, array $options) 
InheritedStatic

Outputs the prefix template, a label (if in the options), a control, the control's errors and a suffix template.

inherited_from \helper_base::apply_template()

Parameters

$template

string

Name of the control template, from the global $indicia_templates variable.

$options

array

Options array containing the control replacement values for the templates. Options can contain a setting for prefixTemplate or suffixTemplate to override the standard templates.

Takes an associative array and converts it to a list of params for a query string.

array_to_query_string(array $array, boolean $encodeValues) : string
InheritedStatic

This is like http_build_query but it does not url encode the & separator, and gives control over urlencoding the array values.

inherited_from \helper_base::array_to_query_string()

Parameters

$array

array

Associative array to convert.

$encodeValues

boolean

Default false. Set to true to URL encode the values being added to the string.

Returns

stringThe query string.

Parameters forms are a quick way of specifying a simple form used to specify the input parameters for a process.

build_params_form(array $options, boolean $hasVisibleContent) 
InheritedStatic

Returns the HTML required for a parameters form, e.g. the form defined for input of report parameters or the default values for a csv import.

link used for report output, id of the report instance on the page if relevant, so that controls can be given unique ids. </li> <li><b>form</b><br/> Associative array defining the form content. </li> <li><b>readAuth</b><br/> Read authorisation array. </li> <li><b>fieldNamePrefix</b><br/> Optional prefix for form field names. </li> <li><b>defaults</b><br/> Associative array of default values for each form element. </li> <li><b>paramsToHide</b><br/> An optional array of parameter names for parameters that should be added to the form output as hidden inputs rather than visible controls. <li><b>paramsToExclude</b><br/> An optional array of parameter names for parameters that should be skipped in the form output despite being in the form definition. </li> <li><b>presetParams</b><br/> Optional array of param names and values that have a fixed value and are therefore output only as a hidden control. </li> <li><b>inlineMapTools</b><br/> Defaults to false. If true, then map drawing parameter tools are embedded into the report parameters form. If false, then the map drawing tools are added to a toolbar at the top of the map. </li> <li><b>helpText</b><br/> Defaults to true. Set to false to disable helpText being displayed alongside controls, useful for building compact versions of simple parameter forms. </li> <li><b>nocache</b><br/> Set to true to disable caching of lookups. </li> </ul>
inherited_from \helper_base::build_params_form()

Parameters

$options

array

Options array with the following possibilities:

<

ul>

  • form
    Associative array defining the form structure. The structure is the same as described for fixed_values_form in a Warehouse model.

  • $hasVisibleContent

    boolean

    On completion, this is set to true if there are visible controls in the params form. If not, then it may be appropriate to skip the displaying of this params form since it is not necessary.

    Returns a span containing any validation errors active on the form for the control with the supplied ID.

    check_errors(string $fieldname, boolean $plaintext) 
    InheritedStatic
    inherited_from \helper_base::check_errors()

    Parameters

    $fieldname

    string

    Fieldname of the control to retrieve errors for.

    $plaintext

    boolean

    Set to true to return just the error text, otherwise it is wrapped in a span.

    Returns the client helper folder path, relative to the root folder.

    client_helper_path() 
    InheritedStatic
    inherited_from \helper_base::client_helper_path()

    This method allows JavaScript and CSS links to be created and placed in the <head> of the HTML file rather than using dump_javascript which must be called after the form is built.

    dump_header(\$resources $resources) : string
    InheritedStatic

    The advantage of dump_javascript is that it intelligently builds the required links depending on what is on your form. dump_header is not intelligent because the form is not built yet, but placing links in the header leads to cleaner code which validates better.

    inherited_from \helper_base::dump_header()

    Parameters

    $resources

    \$resources

    List of resources to include in the header. The available options are described in the documentation for the add_resource method. The default for this is jquery_ui and defaultStylesheet.

    Returns

    stringText to place in the head section of the html file.

    Helper function to collect javascript code in a single location.

    dump_javascript() : string
    InheritedStatic

    Should be called at the end of each HTML page which uses the data entry helper so output all JavaScript required by previous calls.

    link http://code.google.com/p/indicia/wiki/TutorialBuildingBasicPage#Build_a_data_entry_page
    inherited_from \helper_base::dump_javascript()

    Returns

    stringJavaScript to insert into the page for all the controls added to the page so far.

    Call the enable_validation method to turn on client-side validation for any controls with validation rules defined.

    enable_validation(string $form_id) 
    InheritedStatic

    To specify validation on each control, set the control's options array to contain a 'validation' entry. This must be set to an array of validation rules in Indicia validation format. For example, 'validation' => array('required', 'email').

    inherited_from \helper_base::enable_validation()

    Parameters

    $form_id

    string

    @form_id Id of the form the validation is being attached to.

    Explodes a value on several lines into an array split on the lines.

    explode_lines(string $value) : array
    InheritedStatic

    Tolerates any line ending.

    inherited_from \helper_base::explode_lines()

    Parameters

    $value

    string

    A multi-line string to be split.

    Returns

    arrayAn array with one entry per line in $value.

    Explodes a value with key=value several lines into an array split on the lines.

    explode_lines_key_value_pairs(string $value) : array
    InheritedStatic

    Tolerates any line ending.

    inherited_from \helper_base::explode_lines_key_value_pairs()

    Parameters

    $value

    string

    A multi-line string to be split.

    Returns

    arrayAn associative array with one entry per line in $value. Array keys are the items before the = on each line, and values are the data after the = on each line.

    Outputs the content of a report using freeform text templates to create output as required, as opposed to the report_grid which forces a table based output.

    freeform_report(array $options) 
    Static

    Has a header and footer plus any number of bands which are output once per row, or once each time a particular field value changes (i.e. acting as a header band).

    Parameters

    $options

    array

    Options array with the following possibilities:

    • mode
      Pass report to retrieve the underlying data from a report, or direct for an Indicia table or view. Default is report.
    • readAuth
      Read authorisation tokens.
    • dataSource
      Name of the report file or table/view(s) to retrieve underlying data.
    • class
      CSS class to apply to the outer div. Default is banded-report.
    • reportGroup
      When joining multiple reports together, this can be used on a report that has autoParamsForm set to false to bind the report to the parameters form from a different report by giving both report controls the same reportGroup string. This will only work when all parameters required by this report are covered by the other report's parameters form.
    • rememberParamsReportGroup
      Enter any value in this parameter to allow the report to save its parameters for the next time the report is loaded. The parameters are saved site wide, so if several reports share the same value and the same report group then the parameter settings will be shared across the reports even if they are on different pages of the site. For example if several reports on the site have an ownData boolean parameter which filters the data to the user's own data, this can be set so that the reports all share the setting. This functionality requires cookies to be enabled on the browser.
    • header
      Text to output as the header of the report.
    • footer
      Text to output as the footer of the report.
    • bands
      Array of bands to output per row. Each band is itself an array, with at least an item called 'content' which contains an HTML template for the output of the band. The template can contain replacements for each field value in the row, e.g. the replacement {survey} is replaced with the value of the field called survey. In addition, the band array can contain a triggerFields element, which contains an array of the names of fields which act as triggers for the band to be output. The band will then only be output once at the beginning of the report, then once each time one of the named trigger fields' values change. Therefore when using trigger fields the band acts as a group header band.
    • sharing Assuming the report has been written to take account of website sharing agreements, set this to define the task you are performing with the report and therefore the type of sharing to allow. Options are reporting (default), verification, moderation, peer_review, data_flow, website (this website only) or me (my data only).
    • UserId If sharing=me, then this must contain the Indicia user ID of the user to return data for.

    Internal function to find the path to the root of the site, including the trailing slash.

    getRootFolder() 
    InheritedStatic
    inherited_from \helper_base::getRootFolder()

    Retrieves a token and inserts it into a data entry form which authenticates that the form was submitted by this website.

    get_auth(string $website_id, string $password) 
    InheritedStatic
    inherited_from \helper_base::get_auth()

    Parameters

    $website_id

    string

    Indicia ID for the website.

    $password

    string

    Indicia password for the website.

    Retrieves a read token and passes it back as an array suitable to drop into the 'extraParams' options for an Ajax call.

    get_read_auth(string $website_id, string $password) 
    InheritedStatic
    inherited_from \helper_base::get_read_auth()

    Parameters

    $website_id

    string

    Indicia ID for the website.

    $password

    string

    Indicia password for the website.

    Retrieves read and write nonce tokens from the warehouse.

    get_read_write_auth(string $website_id, string $password) : \Returns
    InheritedStatic
    inherited_from \helper_base::get_read_write_auth()

    Parameters

    $website_id

    string

    Indicia ID for the website.

    $password

    string

    Indicia password for the website.

    Returns

    \Returnsan array containing: 'read' => the read authorisation array, 'write' => the write authorisation input controls to insert into your form. 'write_tokens' => the write authorisation array, if needed as separate tokens rather than just placing in form.

    Method that retrieves the data from a report or a table/view, ready to display in a chart or grid.

    get_report_data(array $options, string $extra) : object
    Static

    Respects the filters and columns $_GET variables generated by a grid's filter form when JavaScript is disabled.

    Parameters

    $options

    array

    Options array with the following possibilities:

    • mode
      Defaults to report, which means report data is being loaded. Set to direct to load data directly from an entity's view.
    • dataSource
      Name of the report or entity being queried.
    • readAuth
      Read authentication tokens.
    • filters
      Array of key value pairs to include as a filter against the data.
    • extraParams
      Array of additional key value pairs to attach to the request.
    • linkOnly
      Pass true to return a link to the report data request rather than the data itself. Default false.
    • sharing Assuming the report has been written to take account of website sharing agreements, set this to define the task you are performing with the report and therefore the type of sharing to allow. Options are reporting (default), verification, moderation, peer_review, data_flow, website (this website only) or me (my data only).
    • UserId If sharing=me, then this must contain the Indicia user ID of the user to return data for.
    • caching If true, then the response will be cached and the cached copy used for future calls. Default false.

    $extra

    string

    Any additional parameters to append to the request URL, for example orderby, limit or offset.

    Returns

    objectIf linkOnly is set in the options, returns the link string, otherwise returns the response as an array.

    List of external resources including stylesheets and js files used by the data entry helper class.

    get_resources() 
    InheritedStatic
    inherited_from \helper_base::get_resources()

    A utility function for building the inline script content which should be inserted into a page from the javaascript, late javascript and onload javascript.

    get_scripts(string $javascript, string $late_javascript, string $onload_javascript, bool $includeWrapper) 
    InheritedStatic

    Can optionally include the script tags wrapper around the script generated.

    inherited_from \helper_base::get_scripts()

    Parameters

    $javascript

    string

    JavaScript to run when the page is ready, i.e. in $(document).ready.

    $late_javascript

    string

    JavaScript to run at the end of $(document).ready.

    $onload_javascript

    string

    JavaScript to run in the window.onLoad handler which comes later in the page load process.

    $includeWrapper

    bool

    If true then includes script tags around the script.

    Utility function to load a list of terms from a termlist.

    get_termlist_terms(array $auth, mixed $termlist, array $filter) : array
    InheritedStatic
    inherited_from \helper_base::get_termlist_terms()

    Parameters

    $auth

    array

    Read authorisation array.

    $termlist

    mixed

    Either the id or external_key of the termlist to load.

    $filter

    array

    List of the terms that are required, or null for all terms.

    Returns

    arrayOutput of the Warehouse data services request for the terms.

    Calculates the folder that submitted images end up in according to the helper_config.

    get_uploaded_image_folder() 
    InheritedStatic
    inherited_from \helper_base::get_uploaded_image_folder()

    Sends a POST using the cUrl library.

    http_post(string $url, string $postargs, boolean $output_errors) : array
    InheritedStatic
    inherited_from \helper_base::http_post()

    Parameters

    $url

    string

    The URL the POST request is sent to.

    $postargs

    string

    Arguments to include in the POST data.

    $output_errors

    boolean

    Set to false to prevent echoing of errors. Defaults to true.

    Returns

    arrayAn array with a result element set to true or false for successful or failed posts respectively. The output is returned in an output element in the array. If there is an error, then an errorno element gives the cUrl error number (as generated by the cUrl library used for the post).

    Applies a output template to an array.

    mergeParamsIntoTemplate(array $params, string $template, boolean $useTemplateAsIs, boolean $allowHtml, boolean $allowEscapeQuotes) : string
    InheritedStatic

    This is used to build the output for each item in a list, such as a species checklist grid or a radio group.

    inherited_from \helper_base::mergeParamsIntoTemplate()

    Parameters

    $params

    array

    Array holding the parameters to merge into the template.

    $template

    string

    Name of the template to use, or actual template text if $useTemplateAsIs is set to true.

    $useTemplateAsIs

    boolean

    If true then the template parameter contains the actual template text, otherwise it is the name of a template in the $indicia_templates array. Default false.

    $allowHtml

    boolean

    If true then HTML is emitted as is from the parameter values inserted into the template, otherwise they are escaped.

    $allowEscapeQuotes

    boolean

    If true then parameter names can be suffixes -esape-quote, -escape-dblquote, -escape-htmlquote or -escape-htmldblquote to insert backslashes or html entities into the replacements for string escaping.

    Returns

    stringHTML for the item label

    Calculates the relative path to the client_helpers folder from wherever the current PHP script is.

    relative_client_helper_path() 
    InheritedStatic
    inherited_from \helper_base::relative_client_helper_path()

    <p>Outputs a calendar grid that loads the content of a report.</p> <p>The grid supports a pagination header (year by year).

    report_calendar_grid(array $options) 
    Static

    If you need 2 grids on one page, then you must define a different id in the options for each grid.

    The grid operation has NOT been AJAXified.

    todo Future Enhancements? Allow restriction to month.

    Parameters

    $options

    array

    Options array with the following possibilities:

    • year
      The year to output the calendar for. Default is this year.
    • id
      Optional unique identifier for the grid's container div. This is required if there is more than one grid on a single web page to allow separation of the page and sort $_GET parameters in the URLs generated.
    • mode
      Pass report for a report, or direct for an Indicia table or view. Default is report.
    • readAuth
      Read authorisation tokens.
    • dataSource
      Name of the report file or table/view. when used, any user_id must refer to the CMS user ID, not the Indicia User.
    • view When loading from a view, specify list, gv or detail to determine which view variant is loaded. Default is list.
    • extraParams
      Array of additional key value pairs to attach to the request. This should include fixed values which cannot be changed by the user and therefore are not needed in the parameters form.
    • paramDefaults Optional associative array of parameter default values. Default values appear in the parameter form and can be overridden.
    • includeWeekNumber Should a Week Number column be included in the grid? Defaults to false.
    • weekstart Defines the first day of the week. There are 2 options.
      '. weekday= where is a number between 1 (for Monday) and 7 (for Sunday). Default is 'weekday=7' date=MMM-DD where MMM-DD is a month/day combination: e.g. choosing Apr-1 will start each week on the day of the week on which the 1st of April occurs.
    • weekOneContains Defines week one as the week which contains this date. Format should be MMM-DD, which is a month/day combination: e.g. choosing Apr-1 will define week one as being the week containing the 1st of April. Defaults to the 1st of January.
    • weekNumberFilter Restrict displayed weeks to between 2 weeks defined by their week numbers. Colon separated. Leaving an empty value means the end of the year. Examples: "1:30" - Weeks one to thirty inclusive. "4:" - Week four onwards. ":5" - Upto and including week five.
    • viewPreviousIfTooEarly Boolean. When using week filters, it is possible to bring up a calendar for this year which is entirely in the future. This option will cause the display of the previous year.
    • newURL The URL to invoke when selecting a date which does not have a previous sample associated with it. To the end of this will be appended "

    <p>Outputs a calendar based summary grid that loads the content of a report.</p> <p>If you need 2 grids on one page, then you must define a different id in the options for each grid.</p> <p>The grid operation has NOT been AJAXified.

    report_calendar_summary(array $options) 
    Static

    There is no download option.

    todo : Future Enhancements? Allow restriction to month.

    Parameters

    $options

    array

    Options array with the following possibilities:

    • id
      Optional unique identifier for the grid's container div. This is required if there is more than one grid on a single web page to allow separation of the page and sort $_GET parameters in the URLs generated.
    • mode
      Pass report for a report, or direct for an Indicia table or view. Default is report.
    • readAuth
      Read authorisation tokens.
    • dataSource
      Name of the report file or table/view. when used, any user_id must refer to the CMS user ID, not the Indicia User.
    • view When loading from a view, specify list, gv or detail to determine which view variant is loaded. Default is list.
    • extraParams
      Array of additional key value pairs to attach to the request. This should include fixed values which cannot be changed by the user and therefore are not needed in the parameters form.
    • paramDefaults Optional associative array of parameter default values. Default values appear in the parameter form and can be overridden.
    • tableHeaders Defines which week column headers should be included: date, number or both
    • weekstart Defines the first day of the week. There are 2 options.
      '. weekday= where is a number between 1 (for Monday) and 7 (for Sunday). Default is 'weekday=7' date=MMM-DD where MMM-DD is a month/day combination: e.g. choosing Apr-1 will start each week on the day of the week on which the 1st of April occurs.
    • weekOneContains Defines week one as the week which contains this date. Format should be MMM-DD, which is a month/day combination: e.g. choosing Apr-1 will define week one as being the week containing the 1st of April. Defaults to the 1st of January.
    • weekNumberFilter Restrict displayed weeks to between 2 weeks defined by their week numbers. Colon separated. Leaving an empty value means the end of the year. Examples: "1:30" - Weeks one to thirty inclusive. "4:" - Week four onwards. ":5" - Upto and including week five.
    • rowGroupColumn The column in the report which is used as the vertical axis on the grid.
    • countColumn OPTIONAL: The column in the report which contains the count for this occurrence. If omitted then the default is to assume one occurrence = count of 1
    • includeChartItemSeries Defaults to true. Include a series for each item in the report output.
    • includeChartTotalSeries Defaults to true. Include a series for the total of each item in the report output.

    <p>Outputs a div that contains a chart.</p> <p>The chart is rendered by the jqplot plugin.</p> <p>The chart loads its data from a report, table or view indicated by the dataSource parameter, and the method of loading is indicated by xValues, xLabels and yValues.

    report_chart(array $options) 
    Static

    Each of these can be an array to define a multi-series chart. The largest array from these 4 options defines the total series count. If an option is not an array, or the array is smaller than the total series count, then the last option is used to fill in the missing values. For example, by setting:<br/> 'dataSource' => array('report_1', 'report_2'),<br/> 'yValues' => 'count',<br/> 'xLabels' => 'month'<br/> then you get a chart of count by month, with 2 series' loaded separately from report 1 and report 2. Alternatively you can use a single report, with 2 different columns for count to define the 2 series:<br/> 'dataSource' => 'combined_report',<br/> 'yValues' => array('count_1','count_2'),<br/> 'xLabels' => 'month'<br/> The latter is obviuosly slightly more efficient as only a single report is run. Pie charts will always revert to a single series.

    For summary reports, the user can optionally setup clicking functionality so that another report is called when the user clicks on the chart.

    todo look at the ReportEngine to check it is not prone to SQL injection (eg. offset, limit).
    link http://www.jqplot.com/docs/files/jqplot-core-js.html#Series
    link http://www.jqplot.com/docs/files/jqplot-core-js.html#Axis
    link http://www.jqplot.com/docs/files/plugins/jqplot-barRenderer-js.html
    link http://www.jqplot.com/docs/files/plugins/jqplot-lineRenderer-js.html
    link http://www.jqplot.com/docs/files/plugins/jqplot-pieRenderer-js.html
    link http://www.jqplot.com/docs/files/jqplot-core-js.html#Legend

    Parameters

    $options

    array

    Options array with the following possibilities:

    • mode
      Pass report to retrieve the underlying chart data from a report, or direct for an Indicia table or view. Default is report.
    • readAuth
      Read authorisation tokens.
    • dataSource
      Name of the report file or table/view(s) to retrieve underlying data. Can be an array for multi-series charts.
    • class
      CSS class to apply to the outer div.
    • headerClass
      CSS class to apply to the box containing the header.
    • reportGroup
      When joining multiple reports together, this can be used on a report that has autoParamsForm set to false to bind the report to the parameters form from a different report by giving both report controls the same reportGroup string. This will only work when all parameters required by this report are covered by the other report's parameters form.
    • rememberParamsReportGroup
      Enter any value in this parameter to allow the report to save its parameters for the next time the report is loaded. The parameters are saved site wide, so if several reports share the same value and the same report group then the parameter settings will be shared across the reports even if they are on different pages of the site. For example if several reports on the site have an ownData boolean parameter which filters the data to the user's own data, this can be set so that the reports all share the setting. This functionality requires cookies to be enabled on the browser.
    • height
      Chart height in pixels.
    • width
      Chart width in pixels.
    • chartType
      Currently supports line, bar or pie.
    • rendererOptions
      Associative array of options to pass to the jqplot renderer.
    • legendOptions
      Associative array of options to pass to the jqplot legend. For more information see links below.
    • seriesOptions
      For line and bar charts, associative array of options to pass to the jqplot series. For example:
      'seriesOptions' => array(array('label'=>'My first series','label'=>'My 2nd series'))
      For more information see links below.
    • axesOptions
      For line and bar charts, associative array of options to pass to the jqplot axes. For example:
      'axesOptions' => array('yaxis'=>array('min' => 0, 'max' => '3', 'tickInterval' => 1))
      For more information see links below.
    • yValues
      Report or table field name(s) which contains the data values for the y-axis (or the pie segment sizes). Can be an array for multi-series charts.
    • xValues
      Report or table field name(s) which contains the data values for the x-axis. Only used where the x-axis has a numerical value rather than showing arbitrary categories. Can be an array for multi-series charts.
    • xLabels
      When the x-axis shows arbitrary category names (e.g. a bar chart), then this indicates the report or view/table field(s) which contains the labels. Also used for pie chart segment names. Can be an array for multi-series charts.
    • sharing Assuming the report has been written to take account of website sharing agreements, set this to define the task you are performing with the report and therefore the type of sharing to allow. Options are reporting (default), verification, moderation, peer_review, data_flow, website (this website only) or me (my data only).
    • UserId If sharing=me, then this must contain the Indicia user ID of the user to return data for.
    • linkToReportPath Allows drill down into reports. Holds the URL of the report that is called when the user clicks on a chart data item. When this is not set, the report click functionality is disabled.
    • linkToReportParam Holds the input parameter to be passed to the report that is called when the user clicks on a chart data item. The input parameter's full unique identifier is required, which consists of the report group name (defaults to report) followed by a hyphen, then the report parameter name defined in the report XML file, for example "report-location_id" works for the location_id report parameter for a report in the report group "report". When this is not set, the report click functionality is disabled.

    <p>Outputs a grid that loads the content of a report or Indicia table.</p> <p>The grid supports a simple pagination footer as well as column title sorting through PHP.

    report_grid(array $options) 
    Static

    If used as a PHP grid, note that the current web page will reload when you page or sort the grid, with the same $_GET parameters but no $_POST information. If you need 2 grids on one page, then you must define a different id in the options for each grid.

    For summary reports, the user can optionally setup clicking functionality so that another report is called when the user clicks on the grid.

    The grid operation will be handled by AJAX calls when possible to avoid reloading the web page.

    todo Allow additional params to filter by table column or report parameters
    todo Display a filter form for direct mode
    todo For report mode, provide an AJAX/PHP button that can load the report from parameters in a form on the page.

    Parameters

    $options

    array

    Options array with the following possibilities:

    • id
      Optional unique identifier for the grid's container div. This is required if there is more than one grid on a single web page to allow separation of the page and sort $_GET parameters in the URLs generated.
    • reportGroup
      When joining multiple reports together, this can be used on a report that has autoParamsForm set to false to bind the report to the parameters form from a different report by giving both report controls the same reportGroup string. This will only work when all parameters required by this report are covered by the other report's parameters form.
    • rememberParamsReportGroup
      Enter any value in this parameter to allow the report to save its parameters for the next time the report is loaded. The parameters are saved site wide, so if several reports share the same value and the same report group then the parameter settings will be shared across the reports even if they are on different pages of the site. For example if several reports on the site have an ownData boolean parameter which filters the data to the user's own data, this can be set so that the reports all share the setting. This functionality requires cookies to be enabled on the browser.
    • mode
      Pass report for a report, or direct for an Indicia table or view. Default is report.
    • readAuth
      Read authorisation tokens.
    • dataSource
      Name of the report file or singular form of the table/view.
    • view When loading from a view, specify list, gv or detail to determine which view variant is loaded. Default is list.
    • itemsPerPage
      Number of rows to display per page. Defaults to 20.
    • columns
      Optional. Specify a list of the columns you want to output if you need more control over the columns, for example to specify the order, change the caption or build a column with a configurable data display using a template. Pass an array to this option, with each array entry containing an associative array that specifies the information about the column represented by the position within the array. The associative array for the column can contain the following keys: - fieldname: name of the field to output in this column. Does not need to be specified when using the template option. - display: caption of the column, which defaults to the fieldname if not specified - actions: list of action buttons to add to each grid row. Each button is defined by a sub-array containing values for caption, visibility_field, url, urlParams, class, img and javascript. The visibility field is an optional name of a field in the data which contains true or false to define the visibility of this action. The javascript, url and urlParams values can all use the field names from the report in braces as substitutions, for example {id} is replaced by the value of the field called id in the respective row. In addition, the url can use {currentUrl} to represent the current page's URL, {rootFolder} to represent the folder on the server that the current PHP page is running from, and {imageFolder} for the image upload folder. Because the javascript may pass the field values as parameters to functions, there are escaped versions of each of the replacements available for the javascript action type. Add -escape-quote or -escape-dblquote to the fieldname for quote escaping, or -escape-htmlquote/-escape-htmldblquote for escaping quotes in HTML attributes. For example this would be valid in the action javascript: foo("{bar-escape-dblquote}"); even if the field value contains a double quote which would have broken the syntax. Set img to the path to an image to use an image for the action instead of a text caption - the caption then becomes the image's title. The image path can contain {rootFolder} to be replaced by the root folder of the site, in this case it excludes the path parameter used in Drupal when dirty URLs are used (since this is a direct link to a URL). - visible: true or false, defaults to true - template: allows you to create columns that contain dynamic content using a template, rather than just the output of a field. The template text can contain fieldnames in braces, which will be replaced by the respective field values. Add -escape-quote or -escape-dblquote to the fieldname for quote escaping, or -escape-htmlquote/-escape-htmldblquote for escaping quotes in HTML attributes. Note that template columns cannot be sorted by clicking grid headers. An example array for the columns option is: array( array('fieldname' => 'survey', 'display' => 'Survey Title'), array('display' => 'action', 'template' => 'Edit'), array('display' => 'Actions', 'actions' => array( array('caption' => 'edit', 'url'=>'{currentUrl}', 'urlParams'=>array('survey_id'=>'{id}')) )) ) - json: set to true if the column contains a json string object with properties that can be decoded to give strings that can be used as replacements in a template. For example, a column is returned from a report with fieldname='data', json=true and containing a data value '{"species":"Arnica montana","date":"14/04/2004"}'. A second column with fieldname='comment' contains the value 'Growing on a mountain pasture'. A third column is setup in the report with template set to '
      {species} was recorded on {date}.
      {comment}
      '. The json data and the second column's raw value are all available in the template replacements, so the output is set to '
      Arnice montana was recorded on 14/04/2004.
      Growing on a mountain pasture
      ' template - img: set to true if the column contains a path to an image (relative to the warehouse upload folder). If so then the path is replaced by an image thumbnail with a fancybox zoom to the full image. Multiple images can be included by separating each path with a comma.
    • rowId Optional. Names the field in the data that contains the unique identifier for each row. If set, then the elements have their id attributes set to row + this field value, e.g. row37. This is used to allow synchronisation of the selected table rows with a report map output showing the same data.
    • includeAllColumns Defaults to true. If true, then any columns in the report, view or table which are not in the columns option array are automatically added to the grid after any columns specified in the columns option array. Therefore the default state for a report_grid control is to include all the report, view or table columns in their default state, since the columns array will be empty.
    • headers Should a header row be included? Defaults to true.
    • galleryColCount If set to a value greater than one, then each grid row will contain more than one record of data from the database, allowing a gallery style view to be built. Defaults to 1.
    • autoParamsForm Defaults to true. If true, then if a report requires parameters, a parameters input form will be auto-generated at the top of the grid. If set to false, then it is possible to manually build a parameters entry HTML form if you follow the following guidelines. First, you need to specify the id option for the report grid, so that your grid has a reproducable id. Next, the form you want associated with the grid must itself have the same id, but with the addition of params on the end. E.g. if the call to report_grid specifies the option 'id' to be 'my-grid' then the parameters form must be called 'my-grid-params'. Finally the input controls which define each parameter must have the name 'param-id-' followed by the actual parameter name, replacing id with the grid id. So, in our example, a parameter called survey will need an input or select control with the name attribute set to 'param-my-grid-survey'. The submit button for the form should have the method set to "get" and should post back to the same page. As a final alternative, if parameters are required by the report but some can be hard coded then those may be added to the filters array.
    • fieldsetClass
      Optional. Class name(s) to add to fieldsets generated by the auto parameters form.
    • filters
      Array of key value pairs to include as a filter against the data.
    • extraParams
      Array of additional key value pairs to attach to the request. This should include fixed values which cannot be changed by the user and therefore are not needed in the parameters form.
    • paramDefaults Optional associative array of parameter default values. Default values appear in the parameter form and can be overridden.
    • paramsOnly Defaults to false. If true, then this method will only return the parameters form, not the grid content. autoParamsForm is ignored if this flag is set.
    • ignoreParams Array that can be set to a list of the report parameter names that should not be included in the parameters form. Useful when using paramsOnly=true to display a parameters entry form, but the system has default values for some of the parameters which the user does not need to be asked about. Can also be used to provide parameter values that can be overridden only via a URL parameter.
    • completeParamsForm Defaults to true. If false, the control HTML is returned for the params form without being wrapped in a
      and without the Run Report button, allowing it to be embedded into another form.
    • paramsFormButtonCaption Caption of the button to run the report on the report parameters form. Defaults to Run Report. This caption is localised when appropriate.
    • paramsInMapToolbar If set to true, then the parameters for this report are not output, but are passed to a map_panel control (which must therefore exist on the same web page) and are output as part of the map's toolbar.
    • footer Additional HTML to include in the report footer area. {currentUrl} is replaced by the current page's URL, {rootFolder} is replaced by the folder on the server that the current PHP page is running from.
    • downloadLink Should a download link be included in the report footer? Defaults to false.
    • sharing Assuming the report has been written to take account of website sharing agreements, set this to define the task you are performing with the report and therefore the type of sharing to allow. Options are reporting (default), verification, moderation, peer_review, data_flow, website (this website only) or me (my data only).
    • UserId If sharing=me, then this must contain the Indicia user ID of the user to return data for.
    • sendOutputToMap Default false. If set to true, then the records visible on the current page are drawn onto a map. This is different to the report_map method when linked to a report_grid, which loads its own report data for display on a map, just using the same input parameters as other reports. In this case the report_grid's report data is used to draw the features on the map, so only 1 report request is made.
    • zoomMapToOutput Default true. When combined with sendOutputToMap=true, defines that the map will automatically zoom to show the records.
    • rowClass A CSS class to add to each row in the grid. Can include field value replacements in braces, e.g. {certainty} to construct classes from field values, e.g. to colour rows in the grid according to the data.
    • callback Set to the name of a JavaScript function that should already exist which will be called each time the grid reloads (e.g. when paginating or sorting).
    • linkToReportPath Allows drill down into reports. Holds the URL of the report that is called when the user clicks on a report row. When this is not set, the report click functionality is disabled.
    • linkToReportParam Holds the input parameter to be passed to the report that is called when the user clicks on a report row. The input parameter's full unique identifier is required, which consists of the report group name (defaults to report) followed by a hyphen, then the report parameter name defined in the report XML file, for example "report-location_id" works for the location_id report parameter for a report in the report group "report". When this is not set, the report click functionality is disabled.
    • ajax If true, then the first page of records is loaded via an AJAX call after the initial page load, otherwise they are loaded using PHP during page build. This means the grid load will be delayed till after the rest of the page, speeding up the load time of the rest of the page. If used on a tabbed output then the report will load when the tab is first viewed. Default false.

    Function to output a report onto a map rather than a grid.

    report_map(array $options) 
    Static

    Because there are many options for the map, this method does not generate the map itself, rather it sends the output of the report onto a map_panel output elsewhere on the page. Like the report_grid, this can output a parameters form or can be set to use the parameters form from another output report (e.g. another call to report_grid, allowing both a grid and map of the same data to be generated). The report definition must contain a single column which is configured as a mappable column or the report must specify a parameterised CQL query to draw the map using WMS.

    Parameters

    $options

    array

    Options array with the following possibilities:

    • id
      Optional unique identifier for the report. This is required if there is more than one different report (grid, chart or map) on a single web page to allow separation of the page and sort $_GET parameters in the URLs generated.
    • reportGroup
      When joining multiple reports together, this can be used on a report that has autoParamsForm set to false to bind the report to the parameters form from a different report by giving both report controls the same reportGroup string. This will only work when all parameters required by this report are covered by the other report's parameters form.
    • rememberParamsReportGroup
      Enter any value in this parameter to allow the report to save its parameters for the next time the report is loaded. The parameters are saved site wide, so if several reports share the same value and the same report group then the parameter settings will be shared across the reports even if they are on different pages of the site. For example if several reports on the site have an ownData boolean parameter which filters the data to the user's own data, this can be set so that the reports all share the setting. This functionality requires cookies to be enabled on the browser.
    • mode
      Pass report for a report, or direct for an Indicia table or view. Default is report.
    • readAuth
      Read authorisation tokens.
    • dataSource
      Name of the report file or table/view.
    • autoParamsForm Defaults to true. If true, then if a report requires parameters, a parameters input form will be auto-generated at the top of the grid. If set to false, then it is possible to manually build a parameters entry HTML form if you follow the following guidelines. First, you need to specify the id option for the report grid, so that your grid has a reproducable id. Next, the form you want associated with the grid must itself have the same id, but with the addition of params on the end. E.g. if the call to report_grid specifies the option 'id' to be 'my-grid' then the parameters form must be called 'my-grid-params'. Finally the input controls which define each parameter must have the name 'param-id-' followed by the actual parameter name, replacing id with the grid id. So, in our example, a parameter called survey will need an input or select control with the name attribute set to 'param-my-grid-survey'. The submit button for the form should have the method set to "get" and should post back to the same page. As a final alternative, if parameters are required by the report but some can be hard coded then those may be added to the filters array.
    • filters
      Array of key value pairs to include as a filter against the data.
    • extraParams
      Array of additional key value pairs to attach to the request.
    • paramDefaults Optional associative array of parameter default values.
    • paramsOnly Defaults to false. If true, then this method will only return the parameters form, not the grid content. autoParamsForm is ignored if this flag is set.
    • ignoreParams Array that can be set to a list of the report parameter names that should not be included in the parameters form. Useful when using paramsOnly=true to display a parameters entry form, but the system has default values for some of the parameters which the user does not need to be asked about.
    • completeParamsForm Defaults to true. If false, the control HTML is returned for the params form without being wrapped in a and without the Run Report button, allowing it to be embedded into another form.
    • paramsFormButtonCaption Caption of the button to run the report on the report parameters form. Defaults to Run Report. This caption is localised when appropriate.
    • geoserverLayer For improved mapping performance, specify a layer on GeoServer which has the same attributes and output as the report file. Then the report map can output the contents of this layer filtered by the report parameters, rather than build a layer from the report data.
    • geoserverLayerStyle Optional name of the SLD file available on GeoServer which is to be applied to the GeoServer layer.
    • cqlTemplate Use with the geoserver_layer to provide a template for the CQL to filter the layer according to the parameters of the report. For example, if you are using the report called map_occurrences_by_survey then you can set the geoserver_layer to the indicia:detail_occurrences layer and set this to INTERSECTS(geom, #searchArea#) AND survey_id=#survey#.
    • proxy
      URL of a proxy on the local server to direct GeoServer WMS requests to. This proxy must be able to cache filters in the same way as the iform_proxy Drupal module.
    • clickable
      Set to true to enable clicking on the data points to see the underlying data. Default true.
    • clickableLayersOutputMode
      Set popup, div or report to display popups, output data to a div, or filter associated reports when clicking on data points with the query tool selected.
    • clickableLayersOutputDiv
      Set to the id of a div to display the clicked data in, or leave blank to display a popup.
    • clickableLayersOutputColumns
      An associated array of column field names with column titles as the values which defines the columns that are output when clicking on a data point. If ommitted, then all available columns are output using their original field names.
    • displaySymbol
    • Symbol to display instead of the actual polygon. The symbol is displayed at the centre of the polygon. If not set then defaults to output the original polygon. Allowed values are circle, square, star, x, cross, triangle.
    • valueOutput Allows definition of how a data value in the report output is used to change the output of each symbol. This allows symbol size, colour and/or opacity to be used to provide an indication of data values. Provide an array of entries. The key of the entries should match the style parameter you want to control which should be one of fillOpacity, fillColor, strokeOpacity, strokeWidth or strokeColor. If using displaySymbol to render symbols rather than polygons then pointRadius (the symbol size) and rotation are also available. If the report defines labels (using the feature_style attribute of a column to define a column that outputs labels), then fontSize, fontColor and fontOpacity are also available. Each array entry is a sub-array with associative array values set for the following: "from" is the start value of the range of output values (e.g. the minimum opacity or first colour in a range). "to" is the end value of the range of output values (e.g. the maximum opacity or last colour in a range). "valueField" is the name of the numeric field in the report output to be used to control display. "minValue" is the data value that equates to the output value specified by "from". This can be a fieldname if wrapped in braces. "maxValue" is the data value that equates to the output value specified by "from". This can be a fieldname if wrapped in braces. The following example maps a field called value (with minvalue and maxvalue also output by the report) to a range of colours from blue to red. array( 'fillColor'=>array( 'from'=>'#00FF00', 'to' => '#ff0000', 'valueField' => 'value', 'minValue'=> '{minvalue}', 'maxValue'=> '{maxvalue}' ) )
    • sharing Assuming the report has been written to take account of website sharing agreements, set this to define the task you are performing with the report and therefore the type of sharing to allow. Options are reporting (default), verification, moderation, peer_review, data_flow, website (this website only) or me (my data only).
    • UserId If sharing=me, then this must contain the Indicia user ID of the user to return data for.
    • rowId Optional. Set this to the name of a field in the report to define which field is being used to define the feature ID created on the map layer. For example this can be used in conjunction with rowId on a report grid to allow a report's rows to be linked to the associated features.
    • ajax Optional. Set to true to load the records onto the map using an AJAX request after the initial page load. Not relevant for GeoServer layers. Note that when ajax loading the map, the map will not automatically zoom to the layer extent.
    • zoomMapToOutput Default true. Defines that the map will automatically zoom to show the records.

    Control which outputs a treeview of the reports available on the warehouse, with radio buttons for selecting a report.

    report_picker(array $options) 
    Static

    The title and description of the currently selected report are displayed alongside.

    Parameters

    $options

    array

    Options array which accepts the following standard options: id, fieldname, class, default, readAuth.

    If required, setup jQuery validation.

    setup_jquery_validation_js() 
    InheritedStatic

    This JavaScript must be added at the end of form preparation otherwise we would not know all the control messages. It will normally be called by dump_javascript automatically, but is exposed here as a public method since the iform Drupal module does not call dump_javascript, but is responsible for adding JavaScript to the page via drupal_add_js.

    inherited_from \helper_base::setup_jquery_validation_js()

    Protected function to create a cache file provided it does not already exist.

    _cacheResponse(string $file, array $response, array $options) 
    InheritedStatic
    inherited_from \helper_base::_cacheResponse()

    Parameters

    $file

    string

    Cache file to be removed, includes path - will be false if no caching to take place

    $response

    array

    http_post return value

    $options

    array

    Options array : contents used to tag what this data is.

    Protected function to generate a filename to be used as the cache file for this data

    _getCacheFileName(string $path, array $options, \number $timeout) : string
    InheritedStatic
    inherited_from \helper_base::_getCacheFileName()

    Parameters

    $path

    string

    directory path for file

    $options

    array

    Options array : contents are used along with md5 to generate the filename.

    $timeout

    \number
    • will be false if no caching to take place

    Returns

    stringfilename, else FALSE if data is not to be cached.

    Protected function to fetch a validated timeout value from passed in options array

    _getCacheTimeOut(array $options) : \Timeout
    InheritedStatic
    inherited_from \helper_base::_getCacheTimeOut()

    Parameters

    $options

    array

    Options array with the following possibilities:

    • cachetimeout
      Optional. The length in seconds before the cache times out and is refetched.

    Returns

    \Timeoutin number of seconds, else FALSE if data is not to be cached.

    Protected function to return the cached data stored in the specified local file.

    _getCachedResponse(string $file, \number $timeout, array $options) : array
    InheritedStatic
    inherited_from \helper_base::_getCachedResponse()

    Parameters

    $file

    string

    Cache file to be used, includes path

    $timeout

    \number
    • will be false if no caching to take place

    $options

    array

    Options array : contents used to confirm what this data is.

    Returns

    arrayequivalent of call to http_post, else FALSE if data is not to be cached.

    Protected function to remove a cache file if it has timed out.

    _timeOutCacheFile(string $file, \number $timeout) 
    InheritedStatic
    inherited_from \helper_base::_timeOutCacheFile()

    Parameters

    $file

    string

    Cache file to be removed, includes path

    $timeout

    \number
    • will be false if no caching to take place

    Takes a template string (e.g.

    apply_replacements_to_template(string $template, string $options) 
    InheritedStatic

    <

    div id="{id}">) and replaces the tokens with the equivalent values looked up from the $options array.

    inherited_from \helper_base::apply_replacements_to_template()

    Parameters

    $template

    string

    The templatable string.

    $options

    string

    The array of items which can be merged into the template.

    Returns a static template which is either a default template or one specified in the options

    apply_static_template(string $name, array $options) : string
    InheritedStatic
    inherited_from \helper_base::apply_static_template()

    Parameters

    $name

    string

    The static template type. e.g. prefix or suffix.

    $options

    array

    Array of options which may contain a template name.

    Returns

    stringTemplate value.

    Converts the validation rules in an options array into a string that can be used as the control class, to trigger the jQuery validation plugin.

    build_validation_class(\$options. $options) : string
    InheritedStatic
    inherited_from \helper_base::build_validation_class()

    Parameters

    $options

    \$options.

    Control options array. For validation to be applied should contain a validation entry, containing a single validation string or an array of strings.

    Returns

    stringThe validation rules formatted as a class.

    Returns templated help text for a control, but only if the position matches the $helpTextPos value, and the $options array contains a helpText entry.

    get_help_text(array $options, string $pos) : string
    InheritedStatic
    inherited_from \helper_base::get_help_text()

    Parameters

    $options

    array

    Control's options array. Can specify the class for the help text item using option helpTextClass.

    $pos

    string

    Either before or after. Defines the position that is being requested.

    Returns

    stringTemplated help text, or nothing.

    Internal implementation of the dump_javascript method which takes the javascript and resources list as flexible parameters, rather that using the globals.

    internal_dump_resources(array $resources) 
    InheritedStatic
    access private
    inherited_from \helper_base::internal_dump_resources()

    Parameters

    $resources

    array

    List of resources to include.

    Returns a string where characters have been escaped for use in jQuery selectors

    jq_esc(string $name) : string
    InheritedStatic
    inherited_from \helper_base::jq_esc()

    Parameters

    $name

    string

    The string to be escaped.

    Returns

    stringescaped name.

    Takes a file that has been uploaded to the client website upload folder, and moves it to the warehouse upload folder using the data services.

    send_file_to_warehouse(string $path, boolean $persist_auth, array $readAuth, string $service) : string
    InheritedStatic
    inherited_from \helper_base::send_file_to_warehouse()

    Parameters

    $path

    string

    Path to the file to upload, relative to the interim image path folder (normally the client_helpers/upload folder.

    $persist_auth

    boolean

    Allows the write nonce to be preserved after sending the file, useful when several files are being uploaded.

    $readAuth

    array

    readAuth Read authorisation tokens, if not supplied then the $_POST array should contain them.

    $service

    string

    Path to the service URL used. Default is data/handle_media, but could be import/upload_csv.

    Returns

    stringError message, or true if successful.

    Inserts into the page javascript a function for loading features onto the map as a result of report output.

    addFeaturesLoadingJs(string $addFeaturesJs, string $defsettings, string $selsettings, string $styleFns, boolean $zoomToExtent) 
    Static

    Parameters

    $addFeaturesJs

    string

    JavaScript which creates the list of features.

    $defsettings

    string

    Default style settings.

    $selsettings

    string

    Selected item style settings.

    $styleFns

    string

    JavaScript snippet which places any style functions required into the context parameter when creating a Style.

    $zoomToExtent

    boolean

    If true, then the map will zoom to show the extent of the features added.

    Creates the HTML for the advanced version of the pager.

    advanced_pager(array $options, array $sortAndPageUrlParams, array $response, string $pagLinkUrl) : string
    Static

    Parameters

    $options

    array

    Report options array.

    $sortAndPageUrlParams

    array

    Current parameters for the page and sort order.

    $response

    array

    Response from the call to reporting services, which we are paginating.

    $pagLinkUrl

    string

    The basic URL used to construct page reload links in the pager.

    Returns

    stringThe HTML for the advanced paginator.

    Method to format a control error message inside a templated span.

    apply_error_template(string $error, string $fieldname) 
    InheritedStatic
    inherited_from \helper_base::apply_error_template()

    Parameters

    $error

    string

    The error message.

    $fieldname

    string

    The name of the field which the error is being attached to.

    Checks through the options array for the chart to look for any jqPlot plugins that have been referred to so should be included.

    check_for_jqplot_plugins(Array $options) 
    Static

    Currently only scans for the trendline and category_axis_rendered plugins.

    Parameters

    $options

    Array

    Chart control's options array

    When loading records from a view, put a simple filter parameters form at the top as the view does not specify any parameters.

    get_direct_mode_params_form(array $options) 
    Static

    Parameters

    $options

    array

    Options passed to the report control, which should contain the column definitions.

    Returns a control to insert onto a parameters form.

    get_params_form_control(string $key, array $info, array $options, array $tools) : string
    InheritedStatic
    inherited_from \helper_base::get_params_form_control()

    Parameters

    $key

    string

    The unique identifier of this control.

    $info

    array

    Configuration options for the parameter as defined in the report, including the description, display (label), default and datatype.

    $options

    array

    Control options array

    $tools

    array

    Any tools to be embedded in the map toolbar are returned in this parameter rather than as the return result of the function.

    Returns

    stringThe HTML for the form parameter.

    Internal method to safely find the value of a preset parameter.

    get_preset_param(array $options, string $name) 
    InheritedStatic

    Returns empty string if not defined.

    inherited_from \helper_base::get_preset_param()

    Parameters

    $options

    array

    The options array, containing a presetParams entry that the parameter should be found in.

    $name

    string

    The key identifying the preset parameter to look for.

    Applies the defaults to the options array passed to a report_calendar_grid.

    get_report_calendar_grid_options(array $options) 
    Static

    Parameters

    $options

    array

    Options array passed to the control.

    Works out the page URL param names for this report calendar grid, and also gets their current values.

    get_report_calendar_grid_page_url_params(\$options $options) : array
    Static

    Note there is no need to sort for the calender grid.

    Parameters

    $options

    \$options

    Control options array

    Returns

    arrayContains the page params, as an assoc array. Each array value is an array containing name & value.

    Applies defaults to the options array passed to a report calendar summary control.

    get_report_calendar_summary_options(array $options) : array
    Static

    Parameters

    $options

    array

    Options array passed to the control.

    Returns

    arrayThe processed options array.

    Retrieve the HTML for the actions in a grid row.

    get_report_grid_actions(array $actions, array $row, string $pathParam) 
    Static

    Parameters

    $actions

    array

    List of the action definitions to convert to HTML.

    $row

    array

    The content of the row loaded from the database.

    $pathParam

    string

    Set to the name of a URL param used to pass the path to this page. E.g. in Drupal with clean urls disabled, this is set to q. Otherwise leave empty.

    Returns the parameters for the report grid data services call which are embedded in the query string or default param value data.

    get_report_grid_current_param_values($options) : Array
    Static

    Parameters

    $options

    Returns

    ArrayAssociative array of parameters.

    Apply the defaults to the options for the report grid.

    get_report_grid_options(array $options) 
    Static

    Parameters

    $options

    array

    Array of control options.

    Private function that builds a parameters form according to a parameterRequest recieved when calling a report.

    get_report_grid_parameters_form($response, $options, $params) : string
    Static

    If the autoParamsForm is false then an empty string is returned.

    Parameters

    $response

    $options

    $params

    Returns

    stringHTML for the form.

    Works out the orderby, sortdir and page URL param names for this report grid, and also gets their current values.

    get_report_grid_sort_page_url_params(\$options $options) : array
    Static

    Parameters

    $options

    \$options

    Control options array

    Returns

    arrayContains the orderby, sortdir and page params, as an assoc array. Each array value is an array containing name & value.

    Outputs a single level of the hierarchy of available reports, then iterates into sub- folders.

    get_report_list_level(string $fieldname, string $default, array $list) : \HTML
    Static
    access private

    Parameters

    $fieldname

    string

    The fieldname for the report_picker control (=HTML form value)

    $default

    string

    Name of the report to be initially selected

    $list

    array

    Array of the reports and folders within the level to be output.

    Returns

    \HTMLfor the unordered list containing the level.

    Generates the extra URL parameters that need to be appended to a report service call request, in order to include the sorting and pagination parameters.

    get_report_sorting_paging_params(array $options, array $sortAndPageUrlParams) : string
    Static

    Parameters

    $options

    array

    @options Options array sent to the report.

    $sortAndPageUrlParams

    array

    @sortAndPageUrlParams Paging and sorting info returned from a call to get_report_grid_sort_page_url_params.

    Returns

    stringSnippet of URL containing the required URL parameters.

    Output pagination links.

    output_pager(array $options, string $pageUrl, array $sortAndPageUrlParams, array $response) : string
    Static

    Parameters

    $options

    array

    Report options array.

    $pageUrl

    string

    The URL of the page to reload when paginating (normally the current page). Only used when JavaScript is disabled.

    $sortAndPageUrlParams

    array

    Current parameters for the page and sort order.

    $response

    array

    Response from the call to reporting services, which we are paginating.

    Returns

    stringThe HTML for the paginator.

    Returns the parameters form for a report, only if it is needed because there are parameters without preset values to fill in.

    params_form_if_required(array $response, array $options, string $currentParamValues) 
    Static

    Parameters

    $response

    array

    Response from the call to the report services, which may contain a parameter request.

    $options

    array

    Array of report options.

    $currentParamValues

    string

    Array of current parameter values, e.g. the contents of a submitted parameters form.

    Build a url suitable for inclusion in the links for the report calendar grid column pagination bar.

    report_calendar_grid_get_reload_url(array $pageUrlParams) : string
    Static

    This effectively re-builds the current page's URL, but drops the query string parameters that indicate the year and site. Note there is no need to sort for the calender grid.

    Parameters

    $pageUrlParams

    array

    List pagination parameters which should be excluded.

    Returns

    string

    Creates an array of week numbers which have a record for the provided location.

    report_calendar_summary_initLocation(array $records, integer $locationID) 
    Static

    Parameters

    $records

    array

    Records to scan through.

    $locationID

    integer

    ID of the location to check for.

    report_calendar_summary_processEstimates()

    report_calendar_summary_processEstimates(array $summaryArray, array $locationArray, integer $numSamples, integer $minWeekNo, integer $maxWeekNo, string $taxon, array $options) 
    Static
    todo : document this method

    Parameters

    $summaryArray

    array

    $locationArray

    array

    $numSamples

    integer

    $minWeekNo

    integer

    $maxWeekNo

    integer

    $taxon

    string

    $options

    array

    Add any columns that don't have a column definition to the end of the columns list, by first building an array of the column names of the columns we did specify, then adding any missing fields from the results to the end of the options['columns'] array.

    report_grid_get_columns($response, $options) : \unknown_type
    Static

    Parameters

    $response

    $options

    Returns

    \unknown_type

    Build a url suitable for inclusion in the links for the report grid column headings or pagination bar.

    report_grid_get_reload_url(array $sortAndPageUrlParams) : \unknown_type
    Static

    This effectively re-builds the current page's URL, but drops the query string parameters that indicate the sort order and page number.

    Parameters

    $sortAndPageUrlParams

    array

    List of the sorting and pagination parameters which should be excluded.

    Returns

    \unknown_type

    Requests the data for a report from the reporting services.

    request_report(array $response, array $options, array $currentParamValues, boolean $wantCount, string $extras) 
    Static

    Parameters

    $response

    array

    Data to be returned.

    $options

    array

    Options array defining the report request.

    $currentParamValues

    array

    Array of current parameter values, e.g. the contents of parameters form.

    $wantCount

    boolean

    Set to true if a count of total results (ignoring limit) is required in the response.

    $extras

    string

    Set any additional URL filters if required, e.g. taxon_list_id=1 to filter for taxon list 1.

    Creates the HTML for the simple version of the pager.

    simple_pager(array $options, array $sortAndPageUrlParams, array $response, string $pagLinkUrl) : string
    Static

    Parameters

    $options

    array

    Report options array.

    $sortAndPageUrlParams

    array

    Current parameters for the page and sort order.

    $response

    array

    Response from the call to reporting services, which we are paginating.

    $pagLinkUrl

    string

    The basic URL used to construct page reload links in the pager.

    Returns

    stringThe HTML for the simple paginator.

     Properties

     

    <p>Number of recent files allowed in the cache which the cache will not bother clearing during a deletion operation. They will be refreshed occasionally when requested anyway.</p>

    $cache_allowed_file_count : integer
    Inherited
    inherited_from \helper_base::$$cache_allowed_file_count
     

    <p>On average, every 1 in $cache_chance_purge times the Warehouse is called for data, all files older than 5 times the cache_timeout will be purged, apart from the most recent $cache_allowed_file_count files.</p>

    $cache_chance_purge : integer
    Inherited
    inherited_from \helper_base::$$cache_chance_purge
     

    <p>On average, every 1 in $cache_chance_expire times the Warehouse is called for data which is cached but older than the cache timeout, the cached data will be refreshed. This introduces a random element to cache refreshes so that no single form load event is responsible for refreshing all cached content.</p>

    $cache_chance_refresh_file : integer
    Inherited
    inherited_from \helper_base::$$cache_chance_refresh_file
     

    <p>Length of time in seconds after which cached Warehouse responses will start to expire.</p>

    $cache_timeout : integer
    Inherited
    inherited_from \helper_base::$$cache_timeout
     

    <p>Path to Indicia CSS folder. If not specified, then it is calculated from the Warehouse $base_url. This path should be a full path on the server (starting with '/' exluding the domain).</p>

    $css_path : string
    Inherited
    inherited_from \helper_base::$$css_path
     

    <p>of default validation rules to apply to the controls on the form if the built in client side validation is used (with the jQuery validation plugin). This array can be replaced if required.</p>

    $default_validation_rules : Array
    Inherited
    inherited_from \helper_base::$$default_validation_rules
     

    <p>List of resources that have already been dumped out, so we don't duplicate them. For example, if the site template includes JQuery set $dumped_resources[]='jquery'.</p>

    $dumped_resources : array
    Inherited
    inherited_from \helper_base::$$dumped_resources
     

    <p>Form Mode. Initially unset indicating new input, but can be set to ERRORS or RELOAD.</p>

    $form_mode : string
    Inherited
    inherited_from \helper_base::$$form_mode
     

    <p>Helptext positioning. Determines where the information is displayed when helpText is defined for a control. Options are before, after.</p>

    $helpTextPos : string
    Inherited
    inherited_from \helper_base::$$helpTextPos
     

    <p>Path to Indicia Images folder.</p>

    $images_path : string
    Inherited
    inherited_from \helper_base::$$images_path
     

    <p>Flag set to true if returning content for an AJAX request. This allows the javascript to be returned direct rather than embedding in document.ready and window.onload handlers.</p>

    $is_ajax : boolean
    Inherited
    inherited_from \helper_base::$$is_ajax
     

    <p>JavaScript text to be emitted after the data entry form. Each control that needs custom JavaScript can append the script to this variable.</p>

    $javascript : string
    Inherited
    inherited_from \helper_base::$$javascript
     

    <p>Path to Indicia JavaScript folder. If not specified, then it is calculated from the Warehouse $base_url. This path should be a full path on the server (starting with '/' exluding the domain).</p>

    $js_path : string
    Inherited
    inherited_from \helper_base::$$js_path
     

    <p>JavaScript text to be emitted after the data entry form and all other JavaScript.</p>

    $late_javascript : string
    Inherited
    inherited_from \helper_base::$$late_javascript
     

    <p>Setting to completely disable loading from the cache</p>

    $nocache : boolean
    Inherited
    inherited_from \helper_base::$$nocache
     

    <p>JavaScript text to be emitted during window.onload.</p>

    $onload_javascript : string
    Inherited
    inherited_from \helper_base::$$onload_javascript
     

    <p>List of resources that have been identified as required by the controls used. This defines the JavaScript and stylesheets that must be added to the page. Each entry is an array containing stylesheets and javascript sub-arrays. This has public access so the Drupal module can perform Drupal specific resource output.</p>

    $required_resources : Array
    Inherited
    inherited_from \helper_base::$$required_resources
     

    <p>List of all available resources known. Each resource is named, and contains a sub array of deps (dependencies), stylesheets and javascripts.</p>

    $resource_list : Array
    Inherited
    inherited_from \helper_base::$$resource_list
     

    <p>Name of the form which has been set up for jQuery validation, if any.</p>

    $validated_form_id : array
    Inherited
    inherited_from \helper_base::$$validated_form_id
     

    <p>List of all error messages returned from an attempt to save.</p>

    $validation_errors : array
    Inherited
    inherited_from \helper_base::$$validation_errors
     

    <p>List of messages defined to pass to the validation plugin.</p>

    $validation_messages : array
    Inherited
    inherited_from \helper_base::$$validation_messages
     

    List of methods used to report a validation failure.

    $validation_mode : array
    Inherited

    Options are message, message, hint, icon, colour, inline. The inline option specifies that the message should appear on the same line as the control. Otherwise it goes on the next line, indented by the label width. Because in many cases, controls on an Indicia form occupy the full available width, it is often more appropriate to place error messages on the next line so this is the default behaviour.

    inherited_from \helper_base::$$validation_mode
     

    <p>Path to proxy script for calls to the warehouse (optional, allows the warehouse to sit behind a firewall only accessible from the server).</p>

    $warehouse_proxy : string
    Inherited
    inherited_from \helper_base::$$warehouse_proxy
     

    <p>Are we linking in the default stylesheet? Handled sligtly different to the others so it can be added to the end of the list, allowing our CSS to override other stuff.</p>

    $default_styles : Boolean
    Inherited
    inherited_from \helper_base::$$default_styles
     

    <p>List of error messages that have been displayed, so we don't duplicate them when dumping any remaining ones at the end.</p>

    $displayed_errors : array
    Inherited
    inherited_from \helper_base::$$displayed_errors
     

    Array of html attributes.

    $html_attributes 
    Inherited

    When replacing items in a template, these get automatically wrapped. E.g. a template replacement for the class will be converted to class="value". The key is the parameter name, and the value is the html attribute it will be wrapped into.

    inherited_from \helper_base::$$html_attributes
     

    <p>indicates if any form controls have specified the lockable option. If so, we will need to output some javascript.</p>

    $using_locking : Boolean
    Inherited
    inherited_from \helper_base::$$using_locking
     

    <p>Website ID, stored here to assist with caching.</p>

    $website_id : integer
    Inherited
    inherited_from \helper_base::$$website_id