component.h File Reference

Reusable render units composed on top of the HTML element builder. More...

#include <cwist/core/html/builder.h>
#include <stddef.h>

Include dependency graph for component.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Typedefs
typedef struct cwist_html_component	cwist_html_component_t
typedef cwist_html_element_t *(*	cwist_html_component_render_fn) (const void *props, cwist_html_element_t **children, size_t child_count)
	Render callback for a component.

Functions
cwist_html_component_t *	cwist_html_component_create (const char *name, cwist_html_component_render_fn render_fn)
	Create a component.
void	cwist_html_component_destroy (cwist_html_component_t *comp)
	Destroy a component. Elements it already produced are unaffected.
const char *	cwist_html_component_name (const cwist_html_component_t *comp)
	Return the name the component was created with.
cwist_html_element_t *	cwist_html_component_instantiate (cwist_html_component_t *comp, const void *props, cwist_html_element_t **children, size_t child_count)
	Render one instance of a component.

Detailed Description

Reusable render units composed on top of the HTML element builder.

A component pairs a name with a render function. Instantiating it runs the render function over caller-supplied props and child elements and yields a single root cwist_html_element_t, which is owned and destroyed exactly like any element returned by cwist_html_element_create().

Definition in file component.h.

Typedef Documentation

cwist_html_component_render_fn

typedef cwist_html_element_t *(* cwist_html_component_render_fn) (const void *props, cwist_html_element_t **children, size_t child_count)

Render callback for a component.

Builds and returns one root element, or NULL on failure.

The callback owns every element in children. Each one must end up either in the returned tree (attached with cwist_html_element_add_child(), or returned as the root itself) or destroyed by the callback, on success and on failure alike. On failure, destroying a partially built tree also releases the children already attached to it, so only the unattached ones still need an explicit cwist_html_element_destroy().

Parameters

props	Caller-defined properties, passed through unchanged (may be NULL).
children	Child elements handed to this instance (NULL when child_count is 0). Entries may be NULL.
child_count	Number of entries in children.

Definition at line 41 of file component.h.

cwist_html_component_t

typedef struct cwist_html_component cwist_html_component_t

Opaque component handle.

Definition at line 22 of file component.h.

Function Documentation

cwist_html_component_create()

cwist_html_component_t * cwist_html_component_create	(	const char *	name,
		cwist_html_component_render_fn	render_fn
	)

Create a component.

Parameters

name	Non-empty component name; copied. Also a natural seed for cwist_css_scope_init().
render_fn	Render callback; required.

Returns

New component, or NULL on invalid arguments or allocation failure.

Create a component.

Parameters

name	Non-empty component name; copied into the new component.
render_fn	Render function invoked by cwist_html_component_instantiate().

Returns

New component on success, NULL if arguments are invalid or allocation fails. Caller owns the returned component and must release it with cwist_html_component_destroy().

Definition at line 22 of file component.c.

References cwist_alloc(), cwist_free(), and cwist_strdup().

cwist_html_component_destroy()

void cwist_html_component_destroy

(

cwist_html_component_t *

comp

)

Destroy a component. Elements it already produced are unaffected.

Parameters

comp	Component to release. NULL is ignored.

Destroy a component. Elements it already produced are unaffected.

Parameters

comp	Component to destroy; NULL is accepted and does nothing. Must not be used after this call.

Definition at line 44 of file component.c.

References cwist_free().

cwist_html_component_instantiate()

cwist_html_element_t * cwist_html_component_instantiate	(	cwist_html_component_t *	comp,
		const void *	props,
		cwist_html_element_t **	children,
		size_t	child_count
	)

Render one instance of a component.

The caller gives up ownership of every element in children: they are handed to the render function (see cwist_html_component_render_fn), or destroyed here when comp is NULL. The caller must not touch them after this call. Each element must be listed once and must not be part of another element's tree (including another entry's).

Parameters

comp	Component to render.
props	Properties forwarded to the render function (may be NULL).
children	Child elements for this instance; may be NULL only when child_count is 0. Entries may be NULL.
child_count	Number of entries in children.

Returns

New element tree owned by the caller (destroy it with cwist_html_element_destroy() or hand it to a parent with cwist_html_element_add_child()), or NULL on failure. NULL is also returned, without calling the render function, when children is NULL but child_count is not 0; nothing is released in that case.

Render one instance of a component.

Parameters

comp	Component whose render function is invoked; may be NULL.
props	Opaque props forwarded to the render function.
children	Child elements forwarded to the render function. When comp is NULL they are destroyed here instead, since no render function takes ownership of them.
child_count	Number of entries in children.

Returns

Rendered element tree, or NULL if arguments are invalid or the render function fails. Ownership follows the render function's contract.

Definition at line 71 of file component.c.

References cwist_html_element_destroy().

Referenced by cwist_http_response_set_view().

cwist_html_component_name()

const char * cwist_html_component_name

(

const cwist_html_component_t *

comp

)

Return the name the component was created with.

Returns

Component-owned string, or NULL when comp is NULL.

Return the name the component was created with.

Parameters

comp	Component to query; may be NULL.

Returns

The component's name, or NULL if comp is NULL.

Definition at line 55 of file component.c.