/**
@class Valence_PHP_Toolkit.VvOut
 The VvOut class contains various PHP methods that simplify sending data back to the browser.
*/

/**
@method execSqlToJson
 Executes an SQL statement and sends the results in JSON format to the browser.

@param {array (required)} VvOut An array of options

###Valid keys for VvOut are:

 - `rootName` - The name of the root specified in the front-end data store. If left blank, will default to "dataRoot" (optional);
 - `totalProperty` - If specified this value is used as the field name of the totalCount. If blank then the total row count is returned as "totalCount" (optional).
 - `autoCount` - If set to true then execSqlToJson attempts to create an SQL statement automatically from the primary statement to return the total count of records, ignoring any paging limits. If autoCount returns incorrect results in your situation, then you should set autoCount to false and instead pass a specific countSql statement as the third parameter to execSqlToJson. If autoCount is false and no countSql is passed, then no count is performed (optional).
 - `applySorters` - If set to true, sort fields/directions (as passed by the front-end, usually a grid component) will automatically be applied to the SQL statement. (optional).
 - `applyPaging`  - If set to true, "start" and "limit" parameters passed by an Ext JS paging grid component will be used to automatically modify the passed sql select statement to facilitate paging. (optional).
 - `JSONP` - Set to true to format the response in JSONP. (optional).
 - `success` - If set to true then a true/false success key will be included in the JSON response. (optional).
 - `embed` Additional free-form JSON text to be embedded into the JSON response;

@param {string (required)} sql A string containing the sql statement to run.

@param {string (optional)} countSql A string representing the specific sql statement to run that will return the total count.

@return
 There is no response to the calling function from execSqlToJson. The response goes directly to the browser.
 VvOut::execSqlToJson utilizes VvDb::execSql. If an error occurs during execution of VvDb::execSql then VvOut::execSqlToJson
 will return that error response to the browser including an sqlstate and sqlmsg which can be used to display an error message
 to the user.

##PHP Example 1

    // execute a simple sql statement to send a list of state counts to the browser grouped by state

    // set up vvOut options
    $vvOut = array(
        rootName => 'states'
    );

    // set up sql statement
    $stmt = 'select cstate, count(*) as statecount from democmast group by cstate';

    // execute sql statement and send back results directly to the browser
    VvOut::execSqlToJson($vvOut, $stmt);

##PHP Example 2

    // same as Example 1, but with autoCount turned on so that a count of records will be returned in the response

    // set up vvOut options
    $vvOut = array(
        rootName => 'states',
        autoCount => true
    );

    // set up sql statement
    $stmt = 'select cstate, count(*) as statecount from democmast group by cstate';

    // execute sql statement and send back results directly to the browser
    VvOut::execSqlToJson($vvOut, $stmt);

##PHP Example 3

    // same as Example 2, but we have determined that autoCount isn't reliable with using sql grouping or
    // maybe we want to compute the total count in a different way than autoCount

    // set up vvOut options
    $vvOut = array(
        rootName => 'states',
        autoCount => false
    );

    // set up sql statement
    $stmt = 'select cstate, count as statecount from democmast group by cstate';

    // set up sql count statement
    $countStmt = 'select count(*) from democmast';


    // execute sql statement and send back results directly to the browser
    VvOut::execSqlToJson($vvOut, $stmt, $countStmt);


 */

/**
@method toJsonPair
 This is a convenience method to allow simple PHP key/value pair arrays to be sent to the browser as JSON-formatted strings.
 This method is significantly different from its RPG counterpart.  The RPG vvOut_toJsonPair requires a pseudo-JSON string
 format to be passed.  With PHP, since we have the ability to use simple key/value pair arrays, we take this as the input instead.

@param {array} array

An array of key/value pairs that toJsonPair will convert to JSON and send to the browser.

@param {string (optional)} type A type to set the content header on the response to the browser (optional).

Defaults to JSON which sets the content header to 'text/json'.

##PHP Example

    // send back success message
    if ($results['success']) {
        VvOut::toJsonPair(array(
            success => 'true',
            msg => 'Ticket '.$ticketNo.' saved.'
        ));
    }

*/

/**
@method data
 Sends a string of data to the browser. The string must be formatted manually.

@param {string (required)} data The string to be passed to the browser.

@param {string(optional)} type A type to set the content header on the response to the browser (optional).

Defaults to JSON which sets the content header to 'text/json'.

###Other valid types using Valence built-in constants are:

 - `JSON` (text/json)
 - `JSONP` (text/javascript)
 - `XML` (text/xml)
 - `XMLAPP` (application/xml)
 - `CSV` (text/csv)
 - `JSONTREE` (text/jsontree)
 - `HTML` (text/html)

You can also pass any string value as a type, for example you can pass JSON (no quotes) or 'text/json' (with quotes) and these are equivalent.

@return {null} No information is returned to the calling function. Response is sent directly to the browser.

##PHP Example 1

    // send back manually-formatted message
    VvOut::data('{"success":false,"msg":"Customer 124 not valid."}');

##PHP Example 2

    // send back manually-formatted HTML
    VvOut::data('<html><head><title>TEST</title></head><body>Test</body></html>',HTML);


 */