fwJSON Object

Description

JSON (JavaScript Object Notation) is a lightweight text-based data interchange format. It is easy for humans to read and write and is easy for machines to parse and generate. JSON is based on a subset of the JavaScript programming language, which makes it ideal for use in client-side JavaScript code. As a result, JSON is the most wide-spread mechanism for exchanging data between the browser and the server in Ajax applications. For details on JSON, please refer to the official JSON site.

FoxWeb's fwJSON object provides methods for serializing VFP variables, including arrays and objects, as well as tables and cursors to JSON strings and vice-versa.

Properties

Beautify Determines whether JSON strings, produced by the Write and WriteCursor methods are indented for readability.
ExcludedProperties List of object properties that are omitted from JSON strings, produced by the Write method.
LastError Contains a text description of the last error encountered by the various methods of the fwJSON object.

Methods

Read Deserializes a JSON string into a VFP data value.
Write Serializes a VFP data value into a JSON string.
WriteCursor Serializes a VFP table, or cursor into a JSON string.

Beautify Property

Description

The Beautify property determines whether JSON strings, produced by the Write and WriteCursor methods are split into multiple lines and indented for readability purposes. By default this property is set to .F. to minimize the size of the data that travels over the Internet during Ajax requests. This property is read/write.


ExcludedProperties Property

Description

The ExcludedProperties property contains a comma-separated list of object properties that are omitted from JSON strings, produced by the Write method. If the object being serialized is based on the VFP's Custom class, then the following properties are omitted by default, so there is no need to include them in ExcludedProperties: Application, BaseClass, Class, ClassLibrary, Comment, ControlCount, Controls, Height, HelpContextId, Left, Name, Objects, Parent, ParentClass, Picture, Tag, Top, WhatsThisHelpId, Width. This property is read/write.


LastError Property

Description

The LastError property gets populated with a text description of the last error encountered by the Read the fwJSON object. Use it to determine the cause of the problem when the Read method returns .F.. This property is read-only.


Read Method

Description

The fwJSON.Read method converts (deserializes) a JSON string into a VFP data value. It is typically used to parse JSON-encoded values that are received from browser-side JavaScript programs.

Syntax

lSuccess = fwJSON.Read(cJsonString, @Result)

Parameters

cJsonString

The JSON string to be deserialized.

Result

This argument must be passed by reference (include "@" before the variable name) and gets populated with the resulting VFP data value. Depending on the JSON string, the data type of the result can be character, numeric, logical. The result may also be an array of the above data types, or an object. Finally, the value may also be null. The JSON specification does not define literal formatting for date and time data, so the result will never contain date, or datetime values.

Return Value

Logical: Indicates whether the method was successful in parsing the JSON string. In case of failure, the LastError property will be populated with the error message.

Example

<%
LOCAL Employee
IF NOT fwJSON.Read(Request.Form(), @Employee)
    * Handle parsing error condition
    ERROR fwJSON.LastError
ELSE
    * Process Result variable
    INSERT INTO employee (FirstName, LastName, Phone) ;
        VALUES (Employee.FirstName, Employee.LastName, Employee.Phone)
ENDIF
%>

Write Method

Description

The fwJSON.Write method serializes a VFP data value into a JSON string. It is typically used in Ajax applications to return data to browser-side JavaScript programs.

Syntax

cJsonString = fwJSON.Write(DataValue)

Parameters

DataValue

The data value to be serialized. This value can be in any of VFP's primitive data types and can also be an object, or array. Date and datetime values are converted to strings in the form YYYY-MM-DDTHH:mm:SS (for example the date of July 22, 2007, 6:52 PM will be serialized to the string "2007-07-22T18:52:00").

Return Value

Character: The data value, passed to the function, expressed in JSON format.

Example

<%
LOCAL oResponse
* Create VFP object from scratch
oResponse = CREATEOBJECT("custom")
ADDPROPERTY(oResponse, "FirstName")
ADDPROPERTY(oResponse, "LastName")
ADDPROPERTY(oResponse, "Phone")
* Populate object properties
oResponse.FirstName = "Mike"
oResponse.LastName = "Collins"
oResponse.Phone = "(123) 456-9999"
* Set the content type to text/plain to prevent some Ajax frameworks from complaining
Response.ContentType = "text/plain"
Response.Write(fwJSON.Write(oResponse))
%>

Remarks

If the parameter passed to this method contains any objects based on the fwCursor class, these are serialized in the return value, in the same format produced by the WriteCursor method.


WriteCursor Method

Description

The fwJSON.WriteCursor method serializes a VFP table, or cursor into a JSON string. The table is expressed as an object with single property, named rows, holding an array of objects. Each row object has properties corresponding to the fields of that row (see example below).

Syntax

cJsonString = fwJSON.WriteCursor([WorkArea | TableAlias], [NumRecords])

Parameters

WorkArea | TableAlias

Optional argument, indicating the work area, or alias of the table/cursor to be serialized. The table/cursor must be open at the time of the call. If this argument is not passed, then WriteCursor will serialize the table/cursor in the currently selected work area.

NumRecords

Optional argument, specifying the number of records to output and has a default value is 0. If NumRecords is 0, all records are output. If NumRecords is greater than the number of records remaining in the table, all remaining records are output.

Return Value

Character: The data value, passed to the function, expressed in JSON format.

Example

<%
SELECT * FROM employee WHERE LastName LIKE "Johnson" INTO CURSOR SomePeople
IF RECCOUNT() > 0
    * Set the content type to text/plain to prevent some Ajax frameworks from complaining
    Response.ContentType = "text/plain"
    Response.Write(fwJSON.WriteCursor())
ENDIF
USE IN SomePeople
%>

The above code may return a string that looks like the following:

{
    "rows":[
        {
            "FirstName":"Mike",
            "LastName":"Johnson",
            "Phone":"(123) 123-1234"
        },
        {
            "FirstName":"Andy",
            "LastName":"Johnson",
            "Phone":"(999) 999-9999"
        }
    ]
}

Remarks

If you would like to return multiple cursors, or include additional data with your data set, you should use the Write method in conjunction with the fwCursor class.


© Aegis Group