z_context (zotonic_core v1.0.0-rc.14)

Request context for Zotonic request evaluation.

Link to this section Summary

Functions

Make the url an absolute url by prepending the hostname.
Add the value of multiple request parameter arguments
Add the value of a request parameter argument Always filter the #upload{} arguments to prevent upload of non-temp files.
Return the current client id (if any)
Return the current client bridge topic (if any)
Fetch the cookie domain, defaults to 'undefined' which will equal the domain to the domain of the current request.
Return the Content-Security-Policy nonce for the request.
Fetch the database driver module for this site
Fetch the pid of the database worker pool for this site
Depickle a context for restoring from a database
Depickle a context, return the site name.
Ensure that the logger metadata for this site and process is set.
Ensure that we have parsed the query string, fetch body if necessary. If this is a POST then the session/page-session might be continued after this call.
Return the first fallback language of the Context
Fetch the value of the context variable Key, return undefined when Key is not found.
Fetch the value of the context variable Key, return Default when Key is not found.
Return a proplist with all context variables.
Get the resource module handling the request.
Read a cookie value from the current request.
Read all cookie values with a certain key from the current request.
Return the cowmachine request data of the context
Get a request parameter, either from the query string or the post body. Post body has precedence over the query string. Note that this can also be populated from a JSON MQTT call, and as such contain arbitrary data.
Get a request parameter, either from the query string or the post body. Post body has precedence over the query string.
Get all parameters.
Get the all the parameters with the same name, returns the empty list when non found.
Get all query/post args, filter the zotonic internal args.
Get all query/post args, transformed into a map.
Get all query/post args, transformed into a map. Removes Zotonic vars and the dispatcher '*' variable.
Fetch a query parameter and perform the validation connected to the parameter. An exception {not_validated, Key} is thrown when there was no validator, when the validator is invalid or when the validation failed.
Fetch all arguments starting with a 'q'. This is used for queries.
Get a request header. The header MUST be in lower case.
Return the request path
Return the cowmachine request data of the context
Get a response header
Get the state cookie and decode it.
Return the preferred hostname from the site configuration
Return the hostname (and port) for http from the site configuration
Return the hostname (and port) for https from the site configuration
Set the cowmachine request data of the context
Check if the current context is a request context
Check if the current context has an active MQTT session. This is never true for the first request.
Check if the URL is an URL of the local site
Check if the preferred protocol of the site is https (always true)
Return the selected language of the Context
Set the logger metadata for the current site or context.
Set the logger metadata, add the current site or context
Return a new empty context, no request is initialized.
Create a new context record for a site with a certain language
Create a new context used when testing parts of zotonic
Pickle a context for storing in the database
Make the context safe to use in a async message. This removes render_state and the db transaction.
Cleanup a context so that it can be used exclusively for database connections
Cleanup a context for cacheable scomp handling. Resets most the render_state to prevent duplicating between different (cached) renderings.
Minimal prune, for ensuring that the context can safely used in two processes
Keep the tempfiles alive by attaching the current process to its monitors
Delete the state cookie.
Return the unique random session id for the current client auth. This session_id is re-assigned when the authentication of a client changes.
Set the value of the context variables to all {Key, Value} properties.
Set the value of the context variable Key to Value

Merge a context with client information into a request context. This is used to merge a client context obtained from a MQTT ticket into the contex of an out of band MQTT post.

Set a cookie value with default options.
Set a cookie value with cookie options.
Set Cross-Origin Resource Sharing (CORS) headers. The caller must specify default headers to be used in case there are no observers for the #cors_headers{} notification.
Set the Content-Security-Policy nonce for the request.
Set the cowmachine request data of the context
Set the language of the context, either an atom (language) or a list (language and fallback languages)
Some user agents have too aggressive client side caching. These headers prevent the caching of content on the user agent iff the content generated has a session. You can prevent addition of these headers by not calling z_context:ensure_session/1, or z_context:ensure_all/1.
Set the noindex header if the config is set, or the webmachine resource opt is set.
Set the noindex header if the config is set, the webmachine resource opt is set or Force is set.
Set the value of multiple request parameter arguments
Set the value of a request parameter argument Always filter the #upload{} arguments to prevent upload of non-temp files.
Replace all parameters.
Add metrics data to the Cowboy request, will be added to the metrics notifications.
Set the cowmachine request data of the context
Set resource specific headers. Examples are the non-informational resource uri and WebSub headers.
Set a response header for the request in the context.
Set multiple response headers for the request in the context.
Set security related headers. This can be modified by observing the 'security_headers' notification.
Set the cotonic session id. Mostly used when on a request with a cotonic session id in the cookie.
Set a cookie on the user-agent, holding secret information. The state cookie is used during OAuth key exchanges, against csrf attacks.
Set the timezone of the context.
Maps the site in the request to a site in the sites folder.
Fetch the protocol for absolute urls referring to the site (always https).
Ensure that an URL is an URL to the current site. If not then return the URL of the homepage. If the URL is not a fragment then the returned URL is always sanitized and absolute.
Return the secret used to encode the state cookie.
Return the selected timezone of the Context; defaults to the site's timezone
Return the site's configured timezone.
Filter all Zotonic and dispatcher vars from a map.

Link to this section Functions

Link to this function

abs_url(Url, Context)

-spec abs_url(undefined | iodata(), z:context()) -> binary().
Make the url an absolute url by prepending the hostname.
Link to this function

add_q(KVs, Context)

-spec add_q(list(), z:context()) -> z:context().
Add the value of multiple request parameter arguments
Link to this function

add_q(Key, Upload, Context)

-spec add_q(binary() | string() | atom(), z:qvalue(), z:context()) -> z:context().
Add the value of a request parameter argument Always filter the #upload{} arguments to prevent upload of non-temp files.
Link to this function

client_id(Context)

-spec client_id(z:context()) -> {ok, binary()} | {error, no_client}.
Return the current client id (if any)
Link to this function

client_topic(Context)

-spec client_topic(z:context()) -> {ok, mqtt_sessions:topic()} | {error, no_client}.
Return the current client bridge topic (if any)
Link to this function

csp_nonce(Context)

-spec csp_nonce(z:context()) -> binary().
Return the Content-Security-Policy nonce for the request.
Link to this function

db_driver(Context)

-spec db_driver(z:context()) -> atom().
Fetch the database driver module for this site
Link to this function

db_pool(Context)

-spec db_pool(z:context()) -> atom().
Fetch the pid of the database worker pool for this site
-spec depickle(tuple()) -> z:context().
Depickle a context for restoring from a database
Link to this function

depickle_site(_)

-spec depickle_site(tuple()) -> z:context().
Depickle a context, return the site name.
Link to this function

ensure_logger_md(Context)

-spec ensure_logger_md(z:context() | atom()) -> ok.
Ensure that the logger metadata for this site and process is set.
Link to this function

ensure_qs(Context)

Ensure that we have parsed the query string, fetch body if necessary. If this is a POST then the session/page-session might be continued after this call.
Link to this function

fallback_language(Context)

-spec fallback_language(z:context()) -> atom().
Return the first fallback language of the Context
Link to this function

get(Key, Context)

-spec get(atom(), z:context()) -> term() | undefined.
Fetch the value of the context variable Key, return undefined when Key is not found.
Link to this function

get(Key, Context, Default)

-spec get(atom(), z:context(), term()) -> term().
Fetch the value of the context variable Key, return Default when Key is not found.
Link to this function

get_all(Context)

-spec get_all(z:context()) -> list().
Return a proplist with all context variables.
Link to this function

get_controller_module(Context)

-spec get_controller_module(z:context()) -> atom() | undefined.
Get the resource module handling the request.
Link to this function

get_cookie(Key, Context)

-spec get_cookie(binary(), z:context()) -> binary() | undefined.
Read a cookie value from the current request.
Link to this function

get_cookies(Key, Context)

-spec get_cookies(binary(), z:context()) -> [binary()].
Read all cookie values with a certain key from the current request.
Link to this function

get_envdata(Context)

-spec get_envdata(z:context()) -> cowboy_middleware:env() | undefined.
Return the cowmachine request data of the context
Link to this function

get_q(Keys, Context)

-spec get_q(string() | atom() | binary() | list(), z:context()) -> undefined | z:qvalue().
Get a request parameter, either from the query string or the post body. Post body has precedence over the query string. Note that this can also be populated from a JSON MQTT call, and as such contain arbitrary data.
Link to this function

get_q(Key, Context, Default)

-spec get_q(binary() | string() | atom(), z:context(), term()) -> z:qvalue().
Get a request parameter, either from the query string or the post body. Post body has precedence over the query string.
Link to this function

get_q_all(Context)

-spec get_q_all(z:context()) -> [{binary(), z:qvalue()}].
Get all parameters.
Link to this function

get_q_all(Key, Context)

-spec get_q_all(string() | atom() | binary(), z:context()) -> [z:qvalue()].
Get the all the parameters with the same name, returns the empty list when non found.
Link to this function

get_q_all_noz(Context)

-spec get_q_all_noz(z:context()) -> [{binary(), z:qvalue()}].
Get all query/post args, filter the zotonic internal args.
Link to this function

get_q_map(Context)

-spec get_q_map(z:context()) -> map().
Get all query/post args, transformed into a map.
Link to this function

get_q_map_noz(Context)

-spec get_q_map_noz(z:context()) -> map().
Get all query/post args, transformed into a map. Removes Zotonic vars and the dispatcher '*' variable.
Link to this function

get_q_validated(Keys, Context)

-spec get_q_validated(string() | atom() | binary(), z:context()) -> z:qvalue() | undefined.
Fetch a query parameter and perform the validation connected to the parameter. An exception {not_validated, Key} is thrown when there was no validator, when the validator is invalid or when the validation failed.
Link to this function

get_qargs(Context)

-spec get_qargs(z:context()) -> [{binary(), z:qvalue()}].
Fetch all arguments starting with a 'q'. This is used for queries.
Link to this function

get_render_state(Context)

-spec get_render_state(z:context()) -> z_render:render_state() | undefined.
Link to this function

get_req_header(Header, Context)

-spec get_req_header(binary(), z:context()) -> binary() | undefined.
Get a request header. The header MUST be in lower case.
Link to this function

get_req_path(Context)

-spec get_req_path(z:context()) -> binary().
Return the request path
Link to this function

get_reqdata(Context)

-spec get_reqdata(z:context()) -> cowboy_req:req() | undefined.
Return the cowmachine request data of the context
Link to this function

get_resp_header(Header, Context)

-spec get_resp_header(binary(), z:context()) -> binary() | undefined.
Get a response header
Link to this function

get_state_cookie(Context)

-spec get_state_cookie(z:context()) -> {ok, term()} | {error, term()}.
Get the state cookie and decode it.
Link to this function

hostname(Context)

-spec hostname(z:context()) -> binary().
Return the preferred hostname from the site configuration
Link to this function

hostname_port(Context)

-spec hostname_port(z:context()) -> binary() | undefined.
Return the hostname (and port) for http from the site configuration
Link to this function

hostname_ssl_port(Context)

-spec hostname_ssl_port(z:context()) -> binary() | undefined.
Return the hostname (and port) for https from the site configuration
Link to this function

init_cowdata(Req, Env, Context)

-spec init_cowdata(cowboy_req:req(), cowboy_middleware:env(), z:context()) -> z:context().
Set the cowmachine request data of the context
Link to this function

is_request(Context)

-spec is_request(z:context()) -> boolean().
Check if the current context is a request context
Link to this function

is_session(Context)

-spec is_session(z:context()) -> boolean().
Check if the current context has an active MQTT session. This is never true for the first request.
Link to this function

is_site_url(Url, Context)

-spec is_site_url(undefined | string() | binary(), z:context()) -> boolean().
Check if the URL is an URL of the local site
Link to this function

is_ssl_site(Context)

-spec is_ssl_site(z:context()) -> boolean().
Check if the preferred protocol of the site is https (always true)
Link to this function

is_zotonic_arg(_)

-spec is_zotonic_arg(binary()) -> boolean().
Link to this function

language(Context)

-spec language(z:context()) -> atom().
Return the selected language of the Context
Link to this function

logger_md(Site)

-spec logger_md(z:context() | atom()) -> ok.
Set the logger metadata for the current site or context.
Link to this function

logger_md(MetaData, Context)

-spec logger_md(map() | list(), z:context()) -> ok.
Set the logger metadata, add the current site or context
-spec new(z:context() | atom() | cowboy_req:req()) -> z:context().
Return a new empty context, no request is initialized.
Link to this function

new(Site, Language)

-spec new(Site :: atom(), Language :: atom()) -> z:context().
Create a new context record for a site with a certain language
Link to this function

new(Site, Language, Timezone)

-spec new(Site :: atom(), Language :: atom(), Timezone :: binary()) -> z:context().
Create a new context used when testing parts of zotonic
Link to this function

output(MixedHtml, Context)

-spec output(MixedHtml :: term(), z:context()) -> {iolist(), z:context()}.
Link to this function

pickle(Context)

-spec pickle(z:context()) -> tuple().
Pickle a context for storing in the database
Link to this function

prune_for_async(Context)

-spec prune_for_async(z:context()) -> z:context().
Make the context safe to use in a async message. This removes render_state and the db transaction.
Link to this function

prune_for_database(Context)

-spec prune_for_database(z:context()) -> z:context().
Cleanup a context so that it can be used exclusively for database connections
Link to this function

prune_for_scomp(Context)

-spec prune_for_scomp(z:context()) -> z:context().
Cleanup a context for cacheable scomp handling. Resets most the render_state to prevent duplicating between different (cached) renderings.
Link to this function

prune_for_spawn(Context)

-spec prune_for_spawn(z:context()) -> z:context().
Minimal prune, for ensuring that the context can safely used in two processes
Link to this function

q_upload_keepalive(_, Context)

-spec q_upload_keepalive(boolean(), z:context()) -> ok.
Keep the tempfiles alive by attaching the current process to its monitors
Link to this function

reset_state_cookie(Context)

-spec reset_state_cookie(z:context()) -> z:context().
Delete the state cookie.
Link to this function

session_id(Context)

-spec session_id(z:context()) -> {ok, binary()} | {error, no_session}.
Return the unique random session id for the current client auth. This session_id is re-assigned when the authentication of a client changes.
Link to this function

set(PropList, Context)

-spec set(proplists:proplist(), z:context()) -> z:context().
Set the value of the context variables to all {Key, Value} properties.
Link to this function

set(Key, Value, Context)

-spec set(atom(), term(), z:context()) -> z:context().
Set the value of the context variable Key to Value
Link to this function

set_client_context(ClientContext, ReqContext)

-spec set_client_context(ClientContext :: z:context(), ReqContext :: z:context()) -> z:context().

Merge a context with client information into a request context. This is used to merge a client context obtained from a MQTT ticket into the contex of an out of band MQTT post.

Access control, timezone, language and client information is copied over from the client context to the request context.
Link to this function

set_controller_module(Module, Context)

-spec set_controller_module(Module :: atom(), z:context()) -> z:context().
Link to this function

set_cookie(Key, Value, Context)

-spec set_cookie(binary(), binary(), z:context()) -> z:context().
Set a cookie value with default options.
Link to this function

set_cookie(Key, Value, Options, Context)

-spec set_cookie(binary(), binary(), list(), z:context()) -> z:context().
Set a cookie value with cookie options.
Link to this function

set_cors_headers(Default, Context)

-spec set_cors_headers([{binary(), binary()}], z:context()) -> z:context().
Set Cross-Origin Resource Sharing (CORS) headers. The caller must specify default headers to be used in case there are no observers for the #cors_headers{} notification.
Link to this function

set_csp_nonce(Context)

-spec set_csp_nonce(z:context()) -> z:context().
Set the Content-Security-Policy nonce for the request.
Link to this function

set_envdata(Env, Context)

-spec set_envdata(cowboy_middleware:env() | undefined, z:context()) -> z:context().
Set the cowmachine request data of the context
Link to this function

set_language(Lang, Context)

-spec set_language(atom() | binary() | string() | list(), z:context()) -> z:context().
Set the language of the context, either an atom (language) or a list (language and fallback languages)
Link to this function

set_nocache_headers(Context)

-spec set_nocache_headers(z:context()) -> z:context().
Some user agents have too aggressive client side caching. These headers prevent the caching of content on the user agent iff the content generated has a session. You can prevent addition of these headers by not calling z_context:ensure_session/1, or z_context:ensure_all/1.
Link to this function

set_noindex_header(Context)

-spec set_noindex_header(z:context()) -> z:context().
Set the noindex header if the config is set, or the webmachine resource opt is set.
Link to this function

set_noindex_header(Force, Context)

-spec set_noindex_header(Force :: term(), z:context()) -> z:context().
Set the noindex header if the config is set, the webmachine resource opt is set or Force is set.
Link to this function

set_q(KVs, Context)

-spec set_q([{binary() | string() | atom(), z:qvalue()}] | map(), z:context()) -> z:context().
Set the value of multiple request parameter arguments
Link to this function

set_q(Key, Upload, Context)

-spec set_q(binary() | string() | atom(), z:qvalue(), z:context()) -> z:context().
Set the value of a request parameter argument Always filter the #upload{} arguments to prevent upload of non-temp files.
Link to this function

set_q_all(QArgs, Context)

-spec set_q_all([{binary(), z:qvalue()}], z:context()) -> z:context().
Replace all parameters.
Link to this function

set_render_state(RS, Context)

-spec set_render_state(z_render:render_state() | undefined, z:context()) -> z:context().
Link to this function

set_req_metrics(Metrics, Context)

-spec set_req_metrics(map(), z:context()) -> ok.
Add metrics data to the Cowboy request, will be added to the metrics notifications.
Link to this function

set_reqdata(Req, Context)

-spec set_reqdata(cowboy_req:req() | undefined, z:context()) -> z:context().
Set the cowmachine request data of the context
Link to this function

set_resource_headers(Id, Context)

-spec set_resource_headers(m_rsc:resource_id() | undefined, z:context()) -> z:context().
Set resource specific headers. Examples are the non-informational resource uri and WebSub headers.
Link to this function

set_resp_header(Header, Value, Context)

-spec set_resp_header(binary(), binary(), z:context()) -> z:context().
Set a response header for the request in the context.
Link to this function

set_resp_headers(Headers, Context)

-spec set_resp_headers([{binary(), binary()}], z:context()) -> z:context().
Set multiple response headers for the request in the context.
Link to this function

set_security_headers(Context)

-spec set_security_headers(z:context()) -> z:context().
Set security related headers. This can be modified by observing the 'security_headers' notification.
Link to this function

set_session_id(Sid, Context)

-spec set_session_id(binary(), z:context()) -> z:context().
Set the cotonic session id. Mostly used when on a request with a cotonic session id in the cookie.
Link to this function

set_state_cookie(Data, Context)

-spec set_state_cookie(term(), z:context()) -> z:context().
Set a cookie on the user-agent, holding secret information. The state cookie is used during OAuth key exchanges, against csrf attacks.
Link to this function

set_tz(Tz, Context)

-spec set_tz(string() | binary() | boolean(), z:context()) -> z:context().
Set the timezone of the context.
-spec site(z:context() | cowboy_req:req()) -> atom().
Maps the site in the request to a site in the sites folder.
Link to this function

site_protocol(Context)

-spec site_protocol(z:context()) -> binary().
Fetch the protocol for absolute urls referring to the site (always https).
Link to this function

site_url(Url, Context)

-spec site_url(Url, Context) -> SiteUrl
            when
                Url :: undefined | string() | binary(),
                Context :: z:context(),
                SiteUrl :: binary().
Ensure that an URL is an URL to the current site. If not then return the URL of the homepage. If the URL is not a fragment then the returned URL is always sanitized and absolute.
-spec tz(z:context()) -> binary().
Return the selected timezone of the Context; defaults to the site's timezone
Link to this function

tz_config(Context)

-spec tz_config(z:context()) -> binary().
Return the site's configured timezone.
Link to this function

without_zotonic_args(Map)

-spec without_zotonic_args(map()) -> map().
Filter all Zotonic and dispatcher vars from a map.