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.
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. |
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. |
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.
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.
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.
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.
lSuccess = fwJSON.Read(cJsonString, @Result)
The JSON string to be deserialized.
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.
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.
|
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.
cJsonString = fwJSON.Write(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").
Character: The data value, passed to the function, expressed in JSON format.
|
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.
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).
cJsonString = fwJSON.WriteCursor([WorkArea | TableAlias], [NumRecords])
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.
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.
Character: The data value, passed to the function, expressed in JSON format.
|
The above code may return a string that looks like the following:
{ |
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.