☰ Menu

submit_data(skicall)

The minimum version is:

    def submit_data(skicall):
        return

This function is called when a responder wishes to submit data for processing in some manner. This function typically should populate a PageData object with widgfields as keys, and values to insert into the fields.

This framework often refers to the key tuple (widgetname,fieldname) as a widgfield.

Using the skiadmin facility a responder is chosen from a list of responders by yourself, and added to this site like any other page. Each responder has a different functionality. Certain responders call this submit_data function. Typically a client web browser would make a call to a responder, which (after start_call is called) would then call your submit_data function. Responders generally are set with a target ident - generally the ident of a template page, which will have its widgets populated by any data you set in the PageData object.

For example, if you are returning a template page with a widget 'displaydata' and with a field 'hide' which you want to set to True, you would use:

    pd = PageData()
    pd['displaydata','hide'] = True
    pd['otherwidgets', 'otherfields'] = 'Other values'
    # You may also have a section in the page, with a section alias of "mysection"
    sd = SectionData("mysection")
    sd['anotherwidget', 'widgetfield'] = "Text displayed on widget"
    # And then update pd with this section data
    pd.update(sd)
    # and finally, you would set the pd into skicall using update
    skicall.update(pd)

The template page returned will then have its widget fields set accordingly.

The responder calling submit_data() will specify what it wants returned from submit_data in its documentation.

Most responders require 'None' to be returned, but, for example, the LogIn responder requires a session string.

On returning from submit_data the call will be passed to the responder's target page, which could typically be a template page (in which case your end_call function will be called next) or it could be another responder. If required a GoTo exception could be raised to jump elsewhere, or a FailPage exception could be raised to jump to the responders failure page with an error message.

It is possible for one responder to pass the call to another, therefore submit_data could be called multiple times within a single call.

The submit_data function can inspect the skicall object's attributes to decide how to handle the call.

For example skicall.ident_list which is the list of such responder idents called - the first item being the responder ident called by the user, the last entry being the responder ident that called submit_data.

Each ident in the list is a tuple of the form ('projname', pagenumber).

So skicall.ident_list[-1][1] will give the ident number of the responder calling this submit_data function.

skicall.submit_dict is a dictionary which may be submitted by the responder calling submit_data. The dictionary contents depends on the responder, and are documented for each responder type in the skiadmin pages.

skicall.call_data is a dictionary which you can populate with your own data during the progress of the call. If you wish to clear it, use skicall.call_data.clear(). Typically a responder would be used to pass submitted form data into this call_data dictionary prior to submit_data being called.

When creating a responder that calls submit_data, you will have the option to place one or more strings in the responder's 'submit_list'. These will then be available as the attribute skicall.submit_list, and you could inspect the list to decide which responder called. For example:

def submit_data(skicall):
    if skicall.submit_list[0] == "gethelp":
        .... call help function
    elif skicall.submit_list[0] == "anotherfunc":
        .... call another function
    elif ....

Alternatively you could use the use_submit_list decorator, to route the call to a function of your own choice

Decorator use_submit_list

The decorator use_submit_list can be imported:

from skipole import use_submit_list

It can then be used to decorate your submit_data function like:

@use_submit_list
def submit_data(skicall):
    raise ServerError(message=f"Responder {skicall.ident_list[-1][1]} does not have a correct submit list set")

The effect of this decorator is to inspect the skicall.submit_list attribute, (which you set in the calling responder) and if it contains nothing, or a single element only - it does nothing, submit_data runs as normal, in the above example, it raises an error.

However if skicall.submit_list contains more than one string, it expects the strings to be ordered as ['module_name', 'function_name'] - or ['package_name', 'module_name', 'function_name'].

It then uses these names to call the specified function instead of submit_data. This can be convenient. When you create a responder that calls 'submit_data' - you set the responder submit list to call the appropriate function in your code.

If you are providing a complex tree of packages and modules to handle the submit_data calls, this avoids the need to import them all into your top script, since the decorator will do the importing according to the submit_list.

Your own modules would typically have an import statement providing the PageData and exception classes, and your target functions should accept a single 'skicall' parameter:

from skipole import FailPage, GoTo, ValidateError, ServerError, ServeFile, PageData, SectionData

def function_name(skicall):
    ....  your code 

You do not have to use this decorator, if you prefer to route functionality some other way, then that is your choice.