Page Functions

Sometimes, when a page is accessed you want to perform some action. For instance, you might have a button that turns ON or OFF a led or a relay. Webbino has a mechanism for this, called Page Functions. It allows you to associate a function to a page, so that it gets called before the actual content is sent to the client.

The function can do anything, it has access to any parameters passed in the URL through the classic GET mechanism and it can even block the loading of the page, establishing an Access Control mechanism.

The LedControl example shows how to do all of this (except Access Control).

Code

As usual, I will only comment about the differences with respect to SimpleServer. Please see First Steps and Replacement Tags for any clarifications.

HttpStatusCode ledToggle (HTTPRequestParser& request) {
	char *param;

	param = request.get_parameter (F("state"));
	if (strlen (param) > 0) {
		if (strcmp_P (param, PSTR ("on")) == 0) {
			ledState = true;
			digitalWrite (ledPin, LED_ACTIVE_LEVEL);
		} else {
			ledState = false;
			digitalWrite (ledPin, !LED_ACTIVE_LEVEL);
		}
	}

	return HTTP_OK;
}

This is a Page Function. It will be called just before the associated page (which we'll declare later) is sent to the client. It is called with an HTTPRequestParser object that can be used to retrieve the value of any parameter that was passed in the URL request string. For instance, the page can be called as:

http://10.0.0.1/index.html?state=on

We can find out the value assigned to the state parameter through the request.get_parameter() function. In this case, param will contain on and can be used in comparisons so that the function knows what to do.

An important aspect is that the function shall return the HTTP status code that will be send to the client in the response. If we want the page to be loaded normally we can just return HTTP_OK, otherwise any of the values declared in HttpStatusCode can be returned.

FlashFileFuncAssoc (indexAss, index_html_name, ledToggle);

FileFuncAssociationArray associations[] PROGMEM = {
	&indexAss,
	NULL
};

This is pretty similar to what we did for the Replacement Tags: we associate the Page Function to the page filename (by using the name it was given by the Flash Storage Conversion Script) and make a list of all the association handles. Again, the list MUST be ended with a NULL entry.

webserver.associateFunctions (associations);

Again, this is the only line that changes in the setup() function and it is similiar to what we did for the Replacement Tags: we tell the webserver to enable the Page Functions functionality by passing the list of associations.

Not using FlashStorage?

If you are not using the FlashStorage, you can still use Page Functions, with just a slight syntax change:

FileFuncAssoc (indexAss, "/index.html", ledToggle);

If you do the page-function association like this, it will work with all the other content storages (including the SdStorage). See the LedControl_LittleFS example for reference.