html_response.c File Reference

Page, fragment, out-of-band and redirect answers for HTML handlers. More...

#include <cwist/net/http/html_response.h>
#include <cjson/cJSON.h>
#include <string.h>
#include <strings.h>

Include dependency graph for html_response.c:

Go to the source code of this file.

Functions
bool	cwist_http_request_wants_fragment (const cwist_http_request *req)
	Determine whether the client requested an HTML fragment only.
const char *	cwist_http_request_fragment_target (const cwist_http_request *req)
	Get the identifier of the fragment region the client wants updated.
int	cwist_http_response_set_html (cwist_http_response *res, cwist_html_element_t *root, bool document)
	Set the response body to the rendered HTML of root.
int	cwist_http_response_set_view (const cwist_http_request *req, cwist_http_response *res, cwist_html_element_t *content, cwist_html_component_t *layout, const void *layout_props)
	Set the response body from content, wrapping it in layout for full pages.
int	cwist_http_response_add_oob (const cwist_http_request *req, cwist_http_response *res, cwist_html_element_t *el)
	Append an out-of-band swapped element to the response body.
int	cwist_http_response_html_redirect (const cwist_http_request *req, cwist_http_response *res, const char *location)
	Redirect an HTML request to location, using htmx headers when applicable.

Detailed Description

Page, fragment, out-of-band and redirect answers for HTML handlers.

Definition in file html_response.c.

Function Documentation

cwist_http_request_fragment_target()

const char * cwist_http_request_fragment_target

(

const cwist_http_request *

req

)

Get the identifier of the fragment region the client wants updated.

The element id the client will swap the fragment into, if it said.

Parameters

req	Request to inspect; may be NULL.

Returns

The Turbo-Frame id when present, otherwise the HX-Target header when present, or NULL when the client did not request a fragment or no target was given. The pointer is owned by the request.

Definition at line 57 of file html_response.c.

References cap, and cwist_http_request_wants_fragment().

cwist_http_request_wants_fragment()

bool cwist_http_request_wants_fragment

(

const cwist_http_request *

req

)

Determine whether the client requested an HTML fragment only.

Whether the client asked for a fragment instead of a full page.

A fragment is requested when the htmx HX-Request header is "true" (and it is not a history restore) or when a non-empty Turbo-Frame header is set.

Parameters

req	Request to inspect; may be NULL.

Returns

true if only a fragment of the page should be returned.

Definition at line 43 of file html_response.c.

References cap.

Referenced by cwist_http_request_fragment_target(), cwist_http_response_add_oob(), and cwist_http_response_set_view().

cwist_http_response_add_oob()

int cwist_http_response_add_oob	(	const cwist_http_request *	req,
		cwist_http_response *	res,
		cwist_html_element_t *	el
	)

Append an out-of-band swapped element to the response body.

Append an out-of-band element to a fragment response.

The element must have an "id" attribute. When the client requested a full page the element is dropped (a full page already contains the region) and success is reported. Otherwise an hx-swap-oob="true" attribute is added if missing and the element is rendered and appended to the body. Takes ownership of el in all cases.

Parameters

req	Request used to decide whether an OOB update applies.
res	Response whose body the rendered element is appended to.
el	Element to append; consumed regardless of the result.

Returns

0 on success (including the dropped full-page case), -1 if the response cannot hold HTML, the element has no id, or rendering or appending fails.

Definition at line 226 of file html_response.c.

References cwist_http_response::body, cap, cwist_error_dispose(), cwist_html_element_add_attr(), cwist_html_element_destroy(), cwist_http_request_wants_fragment(), cwist_sstring_append(), cwist_sstring_destroy(), and cwist_sstring::data.

cwist_http_response_html_redirect()

int cwist_http_response_html_redirect	(	const cwist_http_request *	req,
		cwist_http_response *	res,
		const char *	location
	)

Redirect an HTML request to location, using htmx headers when applicable.

Redirect in a way both plain navigation and fragment clients follow.

For htmx requests (HX-Request: true) the status stays 200 and the target is sent via the HX-Redirect header; otherwise a 303 See Other response with a Location header is produced. Any previous Location and HX-Redirect headers are removed and the body is cleared.

Parameters

req	Request used to decide between htmx and regular redirects.
res	Response to modify.
location	Redirect target; must be non-empty and free of control bytes.

Returns

0 on success, -1 if the response cannot hold HTML, the location is invalid, or header/body updates fail.

Definition at line 282 of file html_response.c.

References cwist_http_response::body, cap, cwist_error_dispose(), cwist_http_header_remove(), CWIST_HTTP_OK, CWIST_HTTP_SEE_OTHER, cwist_sstring_assign(), cwist_http_response::headers, and cwist_http_response::status_code.

cwist_http_response_set_html()

int cwist_http_response_set_html	(	cwist_http_response *	res,
		cwist_html_element_t *	root,
		bool	document
	)

Set the response body to the rendered HTML of root.

Render an element tree into the response body as HTML.

Always takes ownership of root and destroys it. On success the Content-Type header is set to text/html; charset=utf-8.

Parameters

res	Response whose body is replaced.
root	Element tree to render; consumed regardless of the result.
document	When true, render as a full document with a doctype.

Returns

0 on success, -1 if the response cannot hold an HTML body, the element is NULL, or rendering/assignment fails.

Definition at line 141 of file html_response.c.

References cwist_http_response::body, cap, cwist_error_dispose(), cwist_html_element_destroy(), cwist_sstring_assign_len(), and cwist_sstring_destroy().

Referenced by cwist_http_response_set_view().

cwist_http_response_set_view()

int cwist_http_response_set_view	(	const cwist_http_request *	req,
		cwist_http_response *	res,
		cwist_html_element_t *	content,
		cwist_html_component_t *	layout,
		const void *	layout_props
	)

Set the response body from content, wrapping it in layout for full pages.

Answer with a fragment or a full page, depending on the request.

When the client requested a fragment, content is rendered alone; otherwise it is embedded into the layout component (or rendered as a full document when no layout is given). Takes ownership of content in all cases. On success a Vary header for fragment-negotiation is appended.

Parameters

req	Request used to decide between fragment and full-page rendering.
res	Response whose body is replaced.
content	Element tree for the page content; consumed regardless of the result.
layout	Optional layout component that wraps content; may be NULL.
layout_props	Props passed to the layout component.

Returns

0 on success, -1 if the response cannot hold HTML, content is NULL, or rendering fails.

Definition at line 178 of file html_response.c.

References cap, cwist_html_component_instantiate(), cwist_html_element_destroy(), CWIST_HTML_FRAGMENT_VARY, cwist_http_request_wants_fragment(), and cwist_http_response_set_html().