Because _DateTimeTextBox.getValue/setValue return/expect a Date value, they are incompatible with the intended use of Form.getValues/setValues to allow serialisation of a form's control values. The Book of Dojo and the actual source documentation say that Form.getValues generates a JSON structure from form values and Form.setValues fills in form values from a JSON structure - in fact they actually generate/use a JavaScript object structure suitable for conversion to/from JSON, you still need to call dojo.toJson/fromJson. Theoretically you can use this to save complex form based queries to a database or cookie, or to submit to a web service.
However, the _DateTimeTextBox.getValue/setValue methods break this in two ways.
Firstly assigning a JavaScript Date object to one of the elements of the structure breaks the JSON conversion - dojo.toJson creates an empty JSON "object", so your actual date value is lost. If you then call dojo.fromJson on the generated JSON string and attempt to pass it back to setValues, an "Object doesn't support this property or method" error is thrown. Obviously there are ways around this, e.g. converting the Date to a string before converting to JSON and the string back to a Date before calling setValues, but it should not be necessary.
The second is more subtle, and caused me to have to extend DateTextBox for my application. It has to do with the way null or unset values are handled. If no value has been set, Form.getValues is passed an undefined value by getValue. This serializes to JSON OK, as "Mydate": undefined, and de-serializes back to an undefined value. However when setValues passes this on to _DateTimeTextBox.setValue, it is essentially ignored - if there is already a value set in the control, it remains there rather than being unset as you would expect (and this is true whether it has been converted to and from JSON, or the value retrieved by getValues is supplied directly back to setValues).
There is already a Trac ticket #6827 logged relating to the second point (not by me), but before I add my two cents worth to that, or log a new ticket, I thought we should perhaps discuss the issue, and try to come up with useful suggestions.
My feeling is that if Form.getValues/setValues are supposed to be there to allow conversion to/from JSON, then the values retrieved need to be in an acceptable format (i.e string, for dates etc.). This means that either the _DateTimeTextBox.getValue needs to return a string value, or Form.getValues needs to call a different method - toString or serialize or perhaps a new getSerializableValue method. Given that being able to retrieve the actual Date object value is useful at times, having getValues call some other method is perhaps more suitable. Similarly setValues needs to able to call a method that can accept a string value, rather than expecting a Date object. (This also implies that perhaps there should be a deserialize method parallel to the serialize method.)
Form serialize/deserialize
Hi Wombat,
So, the thing about Javascript object structure vs. JSON is just a mistake in the documentation... Form is meant to return and take a javascript Object.
It's true that dojo.toJson() and dojo.fromJson() fall over with dates, which is why the test files have a hack:
// make dojo.toJson() print dates correctly (this feels a bit dirty) Date.prototype.json = function(){ return dojo.date.stamp.toISOString(this, {selector: 'date'});};(I'm not sure how the reverse conversion works right now.)
I agree it's a hackish solution but OTOH I'm reluctant to change DateTextBox or Form's behavior, both because of backwards-compatibility issues and because there's nothing wrong with the current behavior... the real issue is with dojo.toJson() and dojo.fromJson().
Trac is down right now so I can't look at that ticket, but is it one I filed saying for getValue() to return null not undefined? setValue(null) should definitely clear the Date value (and probably setValue(undefined) should do the same thing), but if there's a bug (like you said), then we just need to fix it.
We've also talked about setValue() taking either a Date or a String (in ISO format), but just haven't gotten around to implementing it.
=========
Bill Keese
Project Lead (aka BDFL) of Dijit
I think it is that ticket
Bill,
Thanks for the swift reply. I think it is the same ticket (like you, I can't get in to check). I can confirm that setValue(undefined), which is what the current code results in, does not clear the Date value, but setValue(null) does.
If getValues/setValues were meant to use Javascript objects rather than JSON-compatible structures, then I suppose just a small correction to the documentation is in order. It's a shame from my point of view, because the conversion to JSON served my purposes well (I'm allowing users to build fairly complex database queries, and store the query for later re-use). As I said, I have got around the Date object issue by converting to string before converting to JSON (essentially the same idea as your test page hack), and a reverse conversion when loading back, and got around the setValue(undefined) issue by extending DateTextBox to do what I want (probably not suitable for general use).
I can understand that you don't want to break existing code. Perhaps I should log an enhancement request for additional methods to serialize and de-serialize to JSON?
BTW, I think it would be difficult to come up with a reverse conversion that you could just attach to the Date prototype - you need some sort of external knowledge to know that you need to convert the string to a Date.
tickets
I fixed the API doc for setValues/getValues (see [13954]) and filed #6922 to be more explicit about the form problem you mentioned.
As for the heart of the issue, your suggestion of getSerializableValue()/setSerialiazableValue(), it seems reasonable (ie, less hackish than what we have now), please file an enhancement request for that.
As per:
I think the external knowledge is contained w/in the form itself, since the form know that the specified name corresponds to a DateTextBox widget.
=========
Bill Keese
Project Lead (aka BDFL) of Dijit
Enhancement request logged
Thanks Bill.
I have logged ticket #6924 for the enhancement request.
I agree that the Form should know that it is a DateTextBox, and so for the suggested enhancement the deserialization should not be a problem (although presumably it would actually be the widget itself that knew what to do with the string representation). I was rather meaning that the hack you provided very nicely modifies the Date prototype to ensure a consistent conversion to string for any Date object in a toJson call, but there is no easy way to provide a reverse function for fromJson to use to automatically create a Date object in a more general case. It is always going to require the extra knowledge from somewhere that it should be converted, and that cannot be encoded in the JSON itself without some sort of extension to the standard.