Hi Jason,
I think your issue is that you have 4 arguments and you need 5. If you look at the snippet from app/config/assets/hope.html:
newClient.onclick = function() {
odkTables.addRowWithSurvey(null,
'femaleClients',
'screenClient',
null,
null);
}
The formatting hides it a bit, but the 5 args are actually (null, 'femaleClients, 'screenClient, null, null);
That first argument is the dispatchStruct, as you have noticed. The dispatchStruct is used to trigger the action callback and pass data to the callback function.
The dispatchStruct is any (stringified) JSON object you want. ODK doesn’t actually do anything with it, just checks if it is null.
- If dispatchStruct is null, then there is no callback function triggered.
- If dispatchStruct is anothing non-null, then a callback function is triggered.
I will provide example code for this workflow below. First, the function call:
var callSurvey() {
var dispatchStr = JSON.stringify( { "myKey": "myVal"} );
odkTables.addRowWithSurvey(dispatchStruct, tableId, formId, null, null);
}
Next we’ll see how to register for the callback. Assume the function “display” is the first function called when your js file loads.
var display = function() {
// Register the callback function listener
odkCommon.registerListener(function() {
actionCBFn();
});
// Trigger the callback function in case the callback event occurred
// before this loaded
actionCBFn();
// Start your actual load logic here
odkData.getViewData(cbSuccess, cbFailure);
...
}
// Handles callback events from odkCommon.doAction calls.
// Note that most odkTables functions are wrappers for doAction calls
function actionCBFn() {
// Check if there is an action queued to be handled
var action = odkCommon.viewFirstQueuedAction();
if (action === null || action === undefined) {
// The queue is empty. No pending actions
return;
}
var dispatchStr = JSON.parse(action.dispatchStruct);
if (dispatchStr === null || dispatchStr === undefined) {
// This should never happen, if the dispatchStruct is null
// then this callback shouldn't be triggered
console.log('Error: missing dispatch struct');
return;
}
// Parse your dispatch struct here and perform your follow up
var value = dispatchStr["myKey"];
// Do some work with the retrieved value
...
// Now that we are done with handling the callback, we need to
// remove it from the queue. This does not happen unless you
// explicitly remove it. All subsequent calls will queue up behind
odkCommon.removeFirstQueuedAction();
}
As you can see, the value of the dispatchStruct is used exclusively by user level code. If you have more than one function triggering callbacks, it is usually a good idea to add some meta information about the caller to filter out where this callback came from.
One example in which this might be useful is to open a detail view of the row you just created in survey, after it is created. Another possibility would be to add another row to another table depending on responses from the first.
In the short term I’d recommend you pass a null dispatchStruct and see if it fixes your issue. Hopefully that helps, but please let me know if you continue to get this error.
EDIT: I wanted to add, if you want to trigger a callback but don’t need to send any particular values you can pass an empty (non-null) object as a dispatch struct and it will still trigger the callback.
-Jeff