Programmer's Guide to the wftk: getting and setting values

[ wftk documentation home ] [ wftk programmer's guide home ]

Values

Arbitrary named values may be associated with a datasheet. In the prototype, I allowed values to be associated with tasks as well, but it didn't really make a lot of sense, because then you'd have to think about visibility and namespace issues. So instead, each process is a namespace, and that's that.

In addition to the plain old get and set functions you'd expect, we've got a few extra functions. The value interpreter in wftk_value_interpret can express a format in the context of a function. Dollar signs and curly brackets in the format delimit the names of values, so that the format

${Product} request
will resolve to "Chair request" if the named value "Product" contains the value "Chair".

In addition to a name and a value, a data item may have a storage and a type. These two attributes tell wftk which adaptor to use in order to store the value and format HTML input fields, respectively. Yes, the wftk will build HTML fields for you, both in blank and filled forms (the blanks are used for a brand-new elicitation of a data item, whereas the filled fields are used to present a value for editing.)

Functions

int    wftk_value_list      (void * session, XML * datasheet, XML * list);
const char * wftk_value_get (void * session, XML * datasheet, const char * name);
int    wftk_value_get_num   (void * session, XML * datasheet, const char * name);
int    wftk_value_set       (void * session, XML * datasheet, const char * name, const char * value);
int    wftk_value_set_num   (void * session, XML * datasheet, const char * name, int value);
int    wftk_value_isnull    (void * session, XML * datasheet, const char * name);
int    wftk_value_makenull  (void * session, XML * datasheet, const char * name);
int    wftk_value_interpret (void * session, XML * datasheet, const char * spec, char * buffer, int bufsize);
int    wftk_value_settype   (void * session, XML * datasheet, const char * name, const char * type);
int    wftk_value_define    (void * session, XML * datasheet, const char * name, const char * storage);
XML  * wftk_value_html      (void * session, XML * datasheet, const char * name);
XML  * wftk_value_htmlblank (void * session, XML * datasheet, const char * name);

Details

wftk_value_list returns int
void * session,
XML * datasheet,
XML * list
Like other list functions, the wftk_value_list function takes a list structure which is filled out by appending detail item descriptions to it. In this case, the detail items are values defined in the datasheet. At the moment, no filtration is done, so there's a limited utility to this function.

wftk_value_get returns const char *
void * session,
XML * datasheet,
const char * name
Returns a character pointer to the named value. This pointer is constant because you may not change the value; use wftk_value_set instead.

wftk_value_getnum returns int
void * session,
XML * datasheet,
const char * name
If you know your value is numeric, you might want to skip the conversion step and use this function instead of wftk_value_get.

wftk_value_set returns int
void * session,
XML * datasheet,
const char * name,
const char * value
Sets the named value to the given value. Note that only simple strings are supported at the moment; eventually we'll want to be able to store arbitrary XML (or arrays, etc.) in datasheets, but we'll cross that bridge when we come to it. The wftk_value_set function can't be assumed to store the value until a wftk_process_save call is made; this allows you to make several value assignments in one batch if you're using some expensive variable storage (like a database), but it does force a little more overhead in coding.

wftk_value_setnum returns int
void * session,
XML * datasheet,
const char * name,
int value
Uses the given integer value to set the named variable. Again, it saves you a conversion step if you're working with numbers instead of arbitrary strings.

wftk_value_isnull returns int
void * session,
XML * datasheet,
const char * name
Returns a flag as to whether the named value is NULL. Just as in SQL, a NULL value is different from a zero or a blank string, and should be construed as an "I don't know" value.

wftk_value_makenull returns int
void * session,
XML * datasheet,
const char * name
Forces the named value to be a NULL value. This will persist until the next time the value is set to a non-NULL value.

wftk_value_interpret returns int
void * session,
XML * datasheet,
const char * spec,
char * buffer,
int bufsize
Formats a string using data references from the datasheet. All values are retrieved via wftk_value_get (see above), so pseudovariables and data storage and types are respected. Values are retrieved by name by marking with a $ and enclosing in curly braces {}. An example was given above: ${Product} order, if the value named "Product" contains the value "Chair", is interpreted to Chair order. Simple.

Once the value gets to the given bufsize, copying stops. Obviously, it'd be nice if we were to do something more flexible at some point, which would grow a buffer as needed. Wait for wftk v1.1, I guess.

wftk_value_settype returns int
void * session,
XML * datasheet,
const char * name,
const char * typename
Sets the type of the named variable to the given type. The type name references a datatype adaptor, of course, so you can write your own. The type of a variable is used to format it as a plaintext string and is also used to build HTML to present it or elicit it.

wftk_value_define returns int
void * session,
XML * datasheet,
const char * name,
const char * storage
Sets the storage location of a value. The default is storage in the datasheet. Again, a datastore adaptor is used to manage each storage type.

wftk_value_html returns XML *
void * session,
XML * datasheet,
const char * name
Builds an XML-ized HTML input field for a given value. The datatype adaptor takes care of this, actually. The XML in question is of the format described in the XMLAPI xml_writehtml function (no coincidence, as you simply pass the XML to xml_writehtml in order to write the XML.)

wftk_value_htmlblank returns XML *
void * session,
XML * datasheet,
const char * name
Formats a blank HTML field to elicit a value for the variable in question. Again, the datatype adaptor takes care of this.





Copyright (c) 2001 Vivtek. Please see the licensing terms for more information.