body_builder Class Reference

class body_builder is the root class of object generating HTML body More...

#include <body_builder.hpp>

Inheritance diagram for body_builder:

Public Member Functions
	body_builder ()
	constructor
	body_builder (const body_builder &ref)
	copy constructor
	body_builder (body_builder &&ref) noexcept=delete
	move constructor
body_builder &	operator= (const body_builder &ref)
	assignment operator drops all existing children
body_builder &	operator= (body_builder &&ref) noexcept=delete
	move operator
virtual	~body_builder ()
	the (virtual) destructor
void	set_prefix (const chemin &prefix)
void	adopt (body_builder *obj)
bool	is_adopted () const
	whether the object has currently a parent (= is adopted)
void	foresake (body_builder *obj)
void	set_visible (bool mode)
	ask for the object to become visible in HTML page or temporarily hidden
bool	get_visible () const
	returns the current visible status of the object
bool	get_visible_recursively () const
	return the effective visible status of an object taking into account all of ancestors that adopted it
void	add_css_class (const std::string &name)
	set this object with a additional css_class (assuming it is defined in a css_library available for this object)
void	add_css_class (const css_class_group &cg)
	set this object with an additional set of css_classes (assuming they are all defined in a css_library available for this object)
bool	has_css_class (const std::string &name) const
	check the presence of the given class name
void	remove_css_class (const std::string &name)
	remove the provided css_class name from the list of css_class names this object has been assigned to
void	remove_css_class (const css_class_group &cg)
	remove the provided css_class_group from the list
void	clear_css_classes ()
	clear the whole list of css_class names
const std::set< std::string > &	get_css_classes_as_a_set () const
	provide the list of css_class names that this object has been set with
css_class_group	get_css_class_group () const
	provide the list of css_class names as a css_class_group
std::string	get_css_classes (const std::string &extra="") const
	return the class_name as inlined css, suitable to be added in a html marker
void	define_css_class_in_library (const css_class &csscl)
void	define_css_class_in_library (const std::string &name, const css &cssdef)
bool	is_css_class_defined_in_library (const std::string &name) const
	check whether a css_class of given name already exists in a reachable css_library
std::string	get_body_part (const chemin &path, const request &req)
void	ignore_body_changed_from_my_children (bool mode)
	ignore my_body_part_has_changed() invoked from adopted children and myself
bool	get_ignore_body_changed_from_my_children () const
	get the current status of ignore_body_changed_from_my_children()
void	set_no_CR (bool no_cr=true)
	ask for the implementation not to add a new line after this control
void	assign_anchor (bool mode)
	assign an anchor to this object (the object's inherited_get_body_part() will be wrapped into an HTML anchor: )
std::string	get_assigned_anchor () const
	return the anchor value that has been assiged to this object (without the leading #)
virtual void	bind_to_anchor (const std::string &val)
	ask inherited components to use this anchor in case they redirect to an new URL or generate new URLs within their body part.

Protected Member Functions
virtual std::string	inherited_get_body_part (const chemin &path, const request &req)=0
	implementation of get_body_part() method for inherited classes
void	my_body_part_has_changed ()
	let a class record a change in what inherited_get_body_part() would return if it was called again with the same request
virtual void	my_visibility_has_changed ()
	available for inherited class to be informed when their visibility changes
bool	has_my_body_part_changed () const
	obtain the body_part changed status
chemin	get_path () const
	return the path of 'this' according to its descent in the body_builder tree of adopted children
std::string	get_recorded_name () const
void	store_css_library ()
	this creates a css_library accessible from adopted objects to hold html class definitions
bool	has_local_css_library () const
	return true if this object has a css_library locally stored (not from a adopter object)
std::unique_ptr< css_library > &	lookup_css_library () const
	lookup toward registered parent body_builder object for the closest stored css_library
std::string	get_body_part_from_target_child (const chemin &path, const request &req)
std::string	get_body_part_from_all_children (const chemin &path, const request &req)
virtual void	path_has_changed ()
	For inherited classes, called when the path has changed,.
virtual void	has_adopted (body_builder *obj)
	Be informed that a new child has been adopted.
virtual void	will_foresake (body_builder *obj)
	Be informed that a child is about to be foresaken.
virtual void	has_been_adopted_by (body_builder *obj)
	Be informed that we have been adopted by obj, our new parent.
virtual void	will_be_foresaken_by (body_builder *obj)
	Be informed that we are about to be foresaken by obj, our soon former parent.
virtual void	css_classes_have_changed ()
	Be informed about css class modification.
virtual void	new_css_library_available ()
unsigned int	size () const
	access to adopted childs
body_builder *	operator[] (unsigned int i)
	access to adopted childs
body_builder *	get_parent () const
	return the parent object or nullptr if no object has adopted this object
template<class T >
void	closest_ancestor_of_type (T *&ancestor)
	access to the closest ancestor (parent) matching (dynamic_cast) the provided type
void	orphan_all_children ()
	orphan all adopted children
bool	get_no_CR () const
	true if it has been requested no to add Carriage Return after the HTML object

Detailed Description

class body_builder is the root class of object generating HTML body

• the inherited_get_body_part() method let inherited class define what is the HTML body to be generated based on the request passed in argument. Also passed in argument is the path, which is comes from the URI of the request. From the outside, this is the get_body_part() that is to be used it implements a caching layout over inherited_get_body_part(), manage visibility() attribute. About the caching layout, an inherited class can flush cache and force a new evaluation of its generated body by calling my_body_part_has_changed().
• A body_builder object is expected to be located at given path of the requested URL and this let define its behavior according to the path of the request and its own place in the path tree. This place is defined by the adoption() mechanism:
• body_builder objects can adopt other body_builder object creating a tree topology of body_builder. The path of an object adopted by a parent object is a subdirectory of the parent's path. It is a unique name randomly chosen by the parent at adoption time. See get_path(), get_recorded_name()
• the visibility property of an body_builder let it keep its place in the path and adoption tree without returning any HTML code temporarily, this is set using set_visible() method and managed inside get_body_part()
• the get_body_part() of a parent can thus rely on the get_body_part() of its adopted children, this is the freedom of the parent class do decide how to compose or ignore its childen and the possible HTML code they can return, but several method are provided for common tasks: get_body_part_from_target_child() as well as get_body_part_from_all_children().
• Several protected hooks and methods are provided for inherited class to be informed of their adoption or foresake: has_adopted() has_been_adopted_by(), will_foresake(), will_be_foresaken_by()
• the class also handle the CSS components associated to HTML objects or to child objects by mean of a css_library (usually only present in the root object of the tree) and accessible by any children to store CSS class name+definition and refer to them when needed. See store_css_library(), has_local_css_library(), lookup_css_library() and new_css_library_available() to manage and access to a css_library global to the adoption tree. See add_css_class() has_css_class() remove_css_class() clear_css_classes() get_css_classes_as_a_set(), get_css_class_group(), get_css_classes() to assign one or more css classes to a body_builder inherited object. See define_css_class_in_library() to associate a CSS class name to its definition and store this in the closest css_library available in the adoption tree (it is advised to only have one at the root of the tree)
• objects of this class also produce HTML code referring to what should be displayed on on the browser (get_body_part())

  Note

  more details about css. body_builder object can be associated to the name of one or more css_class or css_class_group at any time, those are just labels. The class definition is stored in a css_library. If a body_builder object has created a css_library (calling store_css_library()) all its adopted body_builder objects can access it and upload their class definitions using lookup_css_library(). a class can be informed of the availability of a css_library overriding the protected method new_css_library_available() and implement there the css class definition they or their components have been associated to by mean of add_css_class(). Last from the outside of a class it is possible to define a css_class using the public method define_css_class_in_library(), but for this to work a css_library must be reachable in an ancestors (in regard to the adoption relationship) of this object.

Constructor & Destructor Documentation

body_builder() [1/2]

body_builder::body_builder

(

const body_builder &

ref

)

copy constructor

Note

the created object cannot have any equivalent children as the source may have, because those are not memory managed by the body_builder class but by a derived class. This is thus the duty or derived class to rebuild a children equivalent tree if that makes sense. The newly created object should however stay orphaned (no parent), even if the source had a parent. This will ease copy-construction of derived class having body_builder inherited objects as fields and children.

body_builder() [2/2]

body_builder::body_builder ( body_builder &&  ref )

deletenoexcept

move constructor

Note

if move operation (constructor or assignment) have to be implemented in the future, care should be taken not to copy parent and children pointer values but to have source object foresaken() from parent and new one adopted() by the same parent, as source and moved objects have different addresses. Children adoption should also be taken care the same as parent children would change due to the move operation. Worse as the child-parent relationship is independent from the memory allocation responsibility of children objects, this is the inherited classes that should manage the move operation of the children to the their own field and reset the parent-child relationship accordingly

Member Function Documentation

adopt()

void body_builder::adopt

(

body_builder *

obj

)

Common interface for classes that have to ask other body_builder to contribute in building their body_part()

this call is not mandatory, but let a body_builder object the possibility to rely on the set of body_builder available protected routines to recursively build the body part from the list of adopted children. An object can only have one parent.

Note

this call semantic is that the adopted object becomes a child of the body_builder. The adopted child stays managed by its real parent, the adoption relationship builds a tree of dependant objects using one another to provide a body_part (see get_body_part() method). this tree is automatically broken when an object is destroyed, in that way all recorded children exist (the recorded addresses always points to real existing objects)

assign_anchor()

void body_builder::assign_anchor

(

bool

mode

)

assign an anchor to this object (the object's inherited_get_body_part() will be wrapped into an HTML anchor: )

The objective is for page updates to stay scrolled down with the corresponding body builder object at the top of the viewport when the URL ends by "#value". The value is selected by the body builder class to provide unicity between all objects having been assigned an anchor.

Parameters

[in]

mode

if true an anchor is assigned to the object and inserted before its body builder part. If set to false (which is the default), no anchor is inserted before the body builder part of the object.

Note

see_also get_anchor()

bind_to_anchor()

virtual void body_builder::bind_to_anchor ( const std::string &  val )

inlinevirtual

ask inherited components to use this anchor in case they redirect to an new URL or generate new URLs within their body part.

Reimplemented in guichet, html_button, html_ciphering, html_compression_params, html_double_button, html_entrepot, html_entrepot_landing, html_form_fieldset, html_fsa_scope, html_mask_form_filename, html_mask_form_path, html_slicing, html_url, and html_form.

closest_ancestor_of_type()

template<class T >

void body_builder::closest_ancestor_of_type ( T *&  ancestor )

inlineprotected

access to the closest ancestor (parent) matching (dynamic_cast) the provided type

Parameters

[in]

ancestor

point to the found ancestor if found (points to nullptr else)

css_classes_have_changed()

virtual void body_builder::css_classes_have_changed ( )

inlineprotectedvirtual

Be informed about css class modification.

Reimplemented in html_button, html_ciphering, html_compression_params, html_derouleur, html_double_button, html_entrepot, html_entrepot_landing, html_form_radio, html_mask_form_filename, html_mask_form_path, and html_slicing.

define_css_class_in_library()

void body_builder::define_css_class_in_library

(

const css_class &

csscl

)

add a css definition on a css_library reachable by this object

Note

so far this object does not use it, a call to add_css_class must also be done

the provided css class name must not already exist (exception raised else)

foresake()

void body_builder::foresake

(

body_builder *

obj

)

Common interface for class that have to ask other body_builder to provide their own body_part()

this call is not mandatory, it is the opposite action of adopt(). After this call the given object is no more sollicited to build a body part.

Note

if the requested object is not known an exception is thrown

get_assigned_anchor()

std::string body_builder::get_assigned_anchor ( ) const

inline

return the anchor value that has been assiged to this object (without the leading #)

Note

an empty string is returned if no anchor has been assigned (see assign_anchor() above)

get_body_part()

string body_builder::get_body_part	(	const chemin &	path,
		const request &	req
	)

ask the object to provide a part of the body to answer the request

Parameters

[in]	path	is the full path, but the path.index points to the asked object name
[in]	req	is the request to be answered, the uri's path part targets the choice of child to use for the sub-response

Returns

the body part to be send in the response (html code or other depending on the request) as defined by inherited_get_body_part()

Note

if path is an empty list only this object "body_builder" object can be used to answer, no child object can be invoked by mean of its name.

when going down to the leaf of the tree, the path get shorter by removing the first items one at each step. Empty path means the object itself

the inherited class should take the visible status in consideration when returning HTML from this call

get_body_part_from_all_children()

string body_builder::get_body_part_from_all_children ( const chemin &  path, const request &  req  )

protected

let a parent obtain the body part from all children in the order the have been adopted

Parameters

[in]	path	is the body_builder path, it can be empty. If not the front member is poped from the target even if the poped part of the path does not match the name of the consulted child object
[in]	req	this is the request exactly as received from the get_body_part call

Note

if the object is not visible, this call will return an empty string

get_body_part_from_target_child()

string body_builder::get_body_part_from_target_child ( const chemin &  path, const request &  req  )

protected

let a parent obtain the body part from one of its children given its official name and seen the path of the request

Parameters

[in]	path	is the path exactly as received from the get_body_part call: the first member is the name of a child object.
[in]	req	is the request exactly as received from the get_body_part call

Note

it is typically called from the parent get_body_part() method

if path is an empty list, the call fails (throwing an exception) as no no further name is available to find an child object to return its body part. In consequence, the caller must check whether the path is empty() or not before invoking this method

if the object is not visible, this call will return an empty string

get_css_classes()

string body_builder::get_css_classes

(

const std::string &

extra = ""

)

const

return the class_name as inlined css, suitable to be added in a html marker

Parameters

[in]

extra

a space sperated list of additional classes to add beside the ones assigned to this object. The use case for extra parameter is to temporarily add a css class without having the object considered modified (and his inherited_get_body_part() re-evaluated).

Note

the returned string if not empty is of the form: class="<classname> <classname>..."

get_recorded_name()

string body_builder::get_recorded_name ( ) const

protected

returns the name of 'this' if it has been adopted by a parent body_builder object

Note

, an empty string is returned if the object has not been adopted

get_visible()

bool body_builder::get_visible ( ) const

inline

returns the current visible status of the object

Note

if the object is adopted by another object that is not visible, this first object will have get_visible() returning true (while its parent will return false) but will not be effectively visible to the user. See get_visible_recursively().

has_adopted()

virtual void body_builder::has_adopted ( body_builder *  obj )

inlineprotectedvirtual

Be informed that a new child has been adopted.

Reimplemented in html_form_fieldset, html_hr, html_label, html_level, html_tooltip, and html_void.

has_my_body_part_changed()

bool body_builder::has_my_body_part_changed ( ) const

inlineprotected

obtain the body_part changed status

Note

this is also set when adopted component triggered my_body_part_has_changed()

ignore_body_changed_from_my_children()

void body_builder::ignore_body_changed_from_my_children ( bool  mode )

inline

ignore my_body_part_has_changed() invoked from adopted children and myself

some object (like html_statistics) are ever changing, but rely on some component that will trigger my_body_part_has_changed() to reflect the new value, leading the parent (here html_statistics) to be recorded as changed and the cycle is complete this process never ends. This call avoids propagating any future body_changed status toward the parents and set the caller as if it was a static, never changing, object.

inherited_get_body_part()

virtual std::string body_builder::inherited_get_body_part ( const chemin &  path, const request &  req  )

protectedpure virtual

implementation of get_body_part() method for inherited classes

Note

this method defines what the class will return from the public method body_builder::get_body_part() which also make some housekeeping at body_builder level. In particular, the body_builder class record the "body_changed" status that is reset before calling inherited_get_body_part() and modified by the inherited class when they call the my_body_part_has_changed(). get_body_part() also caches the result of inherited_get_body_part() to avoid calling inherited_get_body_part() if for the same request it has not signaled (calling my_body_part_has_changed()) that for example an event lead its status to change and would require inherited_get_body_part() to be reevaluated

Implemented in arriere_boutique< T >, arriere_boutique< html_ciphering >, arriere_boutique< html_compression_params >, arriere_boutique< html_entrepot_landing >, arriere_boutique< html_form_overwrite_action >, arriere_boutique< html_form_sig_block_size >, arriere_boutique< html_mask_form_filename >, arriere_boutique< html_mask_form_path >, arriere_boutique< html_options_compare >, arriere_boutique< html_options_create >, arriere_boutique< html_options_extract >, arriere_boutique< html_options_isolate >, arriere_boutique< html_options_merge >, arriere_boutique< html_options_read >, arriere_boutique< html_options_repair >, arriere_boutique< html_options_test >, arriere_boutique< html_slicing >, guichet, html_aiguille, html_archive_compare, html_archive_create, html_archive_extract, html_archive_isolate, html_archive_merge, html_archive_read, html_archive_repair, html_bibliotheque, html_button, html_ciphering, html_compression_params, html_datetime, html_derouleur, html_dir_tree, html_div, html_double_button, html_entrepot, html_entrepot_landing, html_fichier, html_focus, html_form, html_form_dynamic_table, html_form_fieldset, html_form_gnupg_list, html_form_ignore_as_symlink, html_form_input, html_form_input_file, html_form_mask_bool, html_form_mask_expression, html_form_mask_file, html_form_mask_subdir, html_form_overwrite_action, html_form_overwrite_base_criterium, html_form_overwrite_combining_criterium, html_form_radio, html_form_same_fs, html_form_select, html_form_sig_block_size, html_fsa_scope, html_hr, html_image, html_label, html_legend, html_level, html_libdar_running_page, html_libdar_running_popup, html_mask_form_filename, html_mask_form_path, html_menu, html_options_compare, html_options_create, html_options_extract, html_options_isolate, html_options_list, html_options_merge, html_options_read, html_options_repair, html_options_test, html_over_guichet, html_page, html_popup, html_select_file, html_slicing, html_span, html_statistics, html_table, html_tabs, html_text, html_url, html_void, html_web_user_interaction, and saisie.

lookup_css_library()

unique_ptr< css_library > & body_builder::lookup_css_library ( ) const

protected

lookup toward registered parent body_builder object for the closest stored css_library

Note

if neither the present object nor any of its parent stores an css_library, the returned unique_ptr is false (points to nullptr), else it points to the found css_library

my_body_part_has_changed()

void body_builder::my_body_part_has_changed ( )

protected

let a class record a change in what inherited_get_body_part() would return if it was called again with the same request

method provided to inherited class to signal a change since the previous time inherited_get_body_part() has changed. This should not concern changes that are triggered by a call to inherited_get_body_part():

Note

A typical use case is when an body_builder is an actor on an event generated by another body_builder. If the first (actor) has its inherited_get_body_part() evaluated before the one of the event generator, when the inherited_get_body_part() is evaluated event leads to modify the first body_builder status and leads the already returned inherited_get_body_part() value to be wrong/obsolete. Having my_body_part_has_changed() invoked from the actor::on_event() method solves this dependency as get_body_part() will relaunch the evaluation of such objects that signaled they have changed.

my_visibility_has_changed()

virtual void body_builder::my_visibility_has_changed ( )

inlineprotectedvirtual

available for inherited class to be informed when their visibility changes

Reimplemented in html_libdar_running_popup, html_void, and html_web_user_interaction.

new_css_library_available()

virtual void body_builder::new_css_library_available ( )

inlineprotectedvirtual

this is a trigger, ran when a css_library becomes available in a parent or "this"

Note

this may also be triggered upon adoption by a object having acces to a css_library

Reimplemented in arriere_boutique< T >, arriere_boutique< html_ciphering >, arriere_boutique< html_compression_params >, arriere_boutique< html_entrepot_landing >, arriere_boutique< html_form_overwrite_action >, arriere_boutique< html_form_sig_block_size >, arriere_boutique< html_mask_form_filename >, arriere_boutique< html_mask_form_path >, arriere_boutique< html_options_compare >, arriere_boutique< html_options_create >, arriere_boutique< html_options_extract >, arriere_boutique< html_options_isolate >, arriere_boutique< html_options_merge >, arriere_boutique< html_options_read >, arriere_boutique< html_options_repair >, arriere_boutique< html_options_test >, arriere_boutique< html_slicing >, guichet, html_archive_compare, html_archive_create, html_archive_extract, html_archive_isolate, html_archive_merge, html_archive_read, html_archive_repair, html_bibliotheque, html_ciphering, html_compression_params, html_demo, html_derouleur, html_dir_tree, html_disconnect, html_entrepot, html_entrepot_landing, html_error, html_form_dynamic_table, html_form_gnupg_list, html_form_ignore_as_symlink, html_form_input, html_form_input_file, html_form_input_unit, html_form_mask_bool, html_form_mask_expression, html_form_mask_file, html_form_mask_subdir, html_form_overwrite_combining_criterium, html_form_overwrite_conditional_action, html_form_radio, html_form_same_fs, html_form_sig_block_size, html_listing_page, html_menu, html_options_compare, html_options_create, html_options_extract, html_options_isolate, html_options_list, html_options_merge, html_options_read, html_options_repair, html_options_test, html_popup, html_select_file, html_slicing, html_statistics, html_summary_page, html_tabs, html_tooltip, html_version, html_web_user_interaction, html_yes_no_box, and saisie.

operator=() [1/2]

body_builder & body_builder::operator= ( body_builder &&  ref )

deletenoexcept

move operator

Note

see the note of the move constructor

operator=() [2/2]

body_builder & body_builder::operator=

(

const body_builder &

ref

)

assignment operator drops all existing children

Note

see the note of the copy constructor

path_has_changed()

virtual void body_builder::path_has_changed ( )

inlineprotectedvirtual

For inherited classes, called when the path has changed,.

Note

tipically this is when this object has been adopted or foresaken

Reimplemented in html_button.

set_no_CR()

void body_builder::set_no_CR

(

bool

no_cr = true

)

ask for the implementation not to add a new line after this control

Note

originally set_no_CR() had no argument, but it was needed to revert to get back the Carriage Return (CR) after a component, where from the added argument, which sound to be a double negation to get the default behavior.

set_prefix()

void body_builder::set_prefix

(

const chemin &

prefix

)

set the root path at which this object will be located in the URL path

Note

this is only used if this object has no parent

set_visible()

void body_builder::set_visible

(

bool

mode

)

ask for the object to become visible in HTML page or temporarily hidden

Note

an object which as its visible property set to false still has its inherited_get_body_part() method evaluated when calling get_body_part(), though get_body_part does not return its output. The reason of doing that way is to keep hidden components being updated under the scene and ready to show at any time.

store_css_library()

void body_builder::store_css_library ( )

inlineprotected

this creates a css_library accessible from adopted objects to hold html class definitions

Note

a child object, directly or indirectly (grand child, aso) will be able to access and populate this css_library using the lookup_css_library() method

avoid calling store_css_library() from a class constructor, this would break inherited class automatic be informed thanks to the new_css_library_available() method

will_foresake()

virtual void body_builder::will_foresake ( body_builder *  obj )

inlineprotectedvirtual

Be informed that a child is about to be foresaken.

Reimplemented in html_focus, html_level, and html_void.

---

The documentation for this class was generated from the following files:

• body_builder.hpp
• body_builder.cpp