start_call(called_ident, skicall)

The minimum version is:

    def start_call(called_ident, skicall):
        return called_ident

When a call is received by the server, this function is called.

called_ident is normally the ident of the page being called, it is a tuple (proj_ident, pagenumber) - with proj_ident is usually the project name, but could be the value set with the proj_ident argument of the WSGIApplication class. A proj_ident different to the project name is used where a sub project is added to a root project several times, each instance needing a unique proj_ident. The pagenumber is the unique integer page number. If the ident of the called page cannot be determined (the path called does not relate to a page) then called_ident will be None.

skicall is the call object described here.

This function should normally return the called_ident value.

If any tests you set here, which could include testing received cookie values, are ok, then the function would normally return the called_ident given in the argument which is that of the page being called.

Possible return values which you may choose to use are:

If you wish to handle the call via another page, return a full ident tuple or ident number (if the page is in this project) or label of a page to jump to. You could, for example, use this feature to direct the call to a log in page. A label is a string, optionally set in the admin session, which references a page ident or URL, used instead of page idents.

If the ident returned is that of a responder page, then depending on the responder, (or sequence of responders) further function calls may be made to the submit_data function, if not a responder (for example a template page) then the function end_call will be called next, and then the template page will be sent to the client.

If start_call returns None, the 'URL NOT FOUND' page will be automatically returned to the client.

If a string url is returned, then a redirector page will be sent to the client. A url would not normally be used to redirect to a page within the project, but could be used to redirect to an external site.

If a ServeFile exception is raised, with the path to a local server file (not a url) - then that server file will be sent to the client. In this case, the submit_data and end_call functions will not be called.

Also note the skicall.map_url_to_server() method, which can be used to map a url folder to a folder of static files.

skicall.map_url_to_server(urlfolder, serverfolder)

Generally called in the start_call function. Maps a url folder such as "/projecturl/special/css" to a server folder such as "/home/user/thisproject/css"
if a call is made to, say "/projecturl/special/css/myfile.css" this function will return a pathlib.Path object to the file "/home/user/thisproject/css/myfile.css" if such a file exists. If not then None is returned. If a ServeFile exception is raised with such a pathlib.Path, then the framework will serve the file.
An example of usage is:

    def start_call(called_ident, skicall):
        servedfile = skicall.map_url_to_server("special/css", "/home/user/thisproject/css")
        if servedfile:
            raise ServeFile(servedfile)
        return called_ident

Note: If the given urlfolder starts with a "/", it is an absolute url, if it does not, as in the above example, then it will be relative, with the project url prepended. Using relative paths makes the code more portable, particularly if this project is to become a sub-project added to a root which may change its project url.