Module z_context

Request context for Zotonic request evaluation.

Copyright © 2009-2021 Marc Worrell

Authors: Marc Worrell (marc@worrell.nl).

Description

Request context for Zotonic request evaluation.

Function Index

abs_url/2Make the url an absolute url by prepending the hostname.
add_q/2Add the value of multiple request parameter arguments.
add_q/3Add the value of a request parameter argument Always filter the #upload{} arguments to prevent upload of non-temp files.
client_id/1Return the current client id (if any).
client_topic/1Return the current client bridge topic (if any).
cookie_domain/1Fetch the cookie domain, defaults to 'undefined' which will equal the domain to the domain of the current request.
db_driver/1Fetch the database driver module for this site.
db_pool/1Fetch the pid of the database worker pool for this site.
depickle/1Depickle a context for restoring from a database.
depickle_site/1Depickle a context, return the site name.
ensure_qs/1Ensure that we have parsed the query string, fetch body if necessary.
fallback_language/1Return the first fallback language of the Context.
get/2Fetch the value of the context variable Key, return undefined when Key is not found.
get/3Fetch the value of the context variable Key, return Default when Key is not found.
get_all/1Return a proplist with all context variables.
get_controller_module/1Get the resource module handling the request.
get_cookie/2Read a cookie value from the current request.
get_cookies/2Read all cookie values with a certain key from the current request.
get_envdata/1Return the cowmachine request data of the context.
get_q/2Get a request parameter, either from the query string or the post body.
get_q/3Get a request parameter, either from the query string or the post body.
get_q_all/1Get all parameters.
get_q_all/2Get the all the parameters with the same name, returns the empty list when non found.
get_q_all_noz/1Get all query/post args, filter the zotonic internal args.
get_q_validated/2Fetch a query parameter and perform the validation connected to the parameter.
get_qargs/1Fetch all arguments starting with a 'q'.
get_render_state/1
get_req_header/2Get a request header.
get_req_path/1Return the request path.
get_reqdata/1Return the cowmachine request data of the context.
get_resp_header/2Get a response header.
get_state_cookie/1Get the state cookie and decode it.
hostname/1Return the preferred hostname from the site configuration.
hostname_port/1Return the hostname (and port) for http from the site configuration.
hostname_ssl_port/1Return the hostname (and port) for https from the site configuration.
init_cowdata/3Set the cowmachine request data of the context.
is_request/1Check if the current context is a request context.
is_session/1Check if the current context has an active MQTT session.
is_ssl_site/1Check if the preferred protocol of the site is https (always true).
is_zotonic_arg/1
lager_md/1
lager_md/2
language/1Return the selected language of the Context.
new/1Return a new empty context, no request is initialized.
new/2Create a new context record for a site with a certain language.
new/3
new_tests/0Create a new context used when testing parts of zotonic.
output/2
pickle/1Pickle a context for storing in the database.
prune_for_async/1Make the context safe to use in a async message.
prune_for_database/1Cleanup a context so that it can be used exclusively for database connections.
prune_for_scomp/1Cleanup a context for cacheable scomp handling.
prune_for_spawn/1Minimal prune, for ensuring that the context can safely used in two processes.
q_upload_keepalive/2Keep the tempfiles alive by attaching the current process to its monitors.
reset_state_cookie/1Delete the state cookie.
session_id/1Return the unique random session id for the current client auth.
set/2Set the value of the context variables to all {Key, Value} properties.
set/3Set the value of the context variable Key to Value.
set_client_context/2Merge a context with client information into a request context.
set_controller_module/2
set_cookie/3Set a cookie value with default options.
set_cookie/4Set a cookie value with cookie options.
set_cors_headers/2Set Cross-Origin Resource Sharing (CORS) headers.
set_envdata/2Set the cowmachine request data of the context.
set_language/2Set the language of the context, either an atom (language) or a list (language and fallback languages).
set_nocache_headers/1Some user agents have too aggressive client side caching.
set_noindex_header/1Set the noindex header if the config is set, or the webmachine resource opt is set.
set_noindex_header/2Set the noindex header if the config is set, the webmachine resource opt is set or Force is set.
set_q/2Set the value of multiple request parameter arguments.
set_q/3Set the value of a request parameter argument Always filter the #upload{} arguments to prevent upload of non-temp files.
set_q_all/2Replace all parameters.
set_render_state/2
set_req_metrics/2Add metrics data to the Cowboy request, will be added to the metrics notifications.
set_reqdata/2Set the cowmachine request data of the context.
set_resp_header/3Set a response header for the request in the context.
set_resp_headers/2Set multiple response headers for the request in the context.
set_security_headers/1Set security related headers.
set_session_id/2Set the cotonic session id.
set_state_cookie/2Set a cookie on the user-agent, holding secret information.
set_tz/2Set the timezone of the context.
site/1Maps the site in the request to a site in the sites folder.
site_protocol/1Fetch the protocol for absolute urls referring to the site (always https).
state_cookie_secret/1Return the secret used to encode the state cookie.
tz/1Return the selected timezone of the Context; defaults to the site's timezone.
tz_config/1Return the site's configured timezone.

Function Details

abs_url/2

abs_url(Url::iodata(), Context::z:context()) -> binary()

Make the url an absolute url by prepending the hostname.

add_q/2

add_q(KVs::list(), Context::z:context()) -> z:context()

Add the value of multiple request parameter arguments

add_q/3

add_q(Key::binary() | string() | atom(), Upload::z:qvalue(), Context::z:context()) -> z:context()

Add the value of a request parameter argument Always filter the #upload{} arguments to prevent upload of non-temp files.

client_id/1

client_id(Context::z:context()) -> {ok, binary()} | {error, no_client}

Return the current client id (if any)

client_topic/1

client_topic(Context::z:context()) -> {ok, mqtt_sessions:topic()} | {error, no_client}

Return the current client bridge topic (if any)

cookie_domain/1

cookie_domain(Context::z:context()) -> binary() | undefined

Fetch the cookie domain, defaults to 'undefined' which will equal the domain to the domain of the current request.

db_driver/1

db_driver(Context::z:context()) -> atom()

Fetch the database driver module for this site

db_pool/1

db_pool(Context::z:context()) -> atom()

Fetch the pid of the database worker pool for this site

depickle/1

depickle(X1::tuple()) -> z:context()

Depickle a context for restoring from a database

depickle_site/1

depickle_site(X1::tuple()) -> z:context()

Depickle a context, return the site name.

ensure_qs/1

ensure_qs(Context) -> any()

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.

fallback_language/1

fallback_language(Context::z:context()) -> atom()

Return the first fallback language of the Context

get/2

get(Key::atom(), Context::z:context()) -> term() | undefined

Fetch the value of the context variable Key, return undefined when Key is not found.

get/3

get(Key::atom(), Context::z:context(), Default::term()) -> term()

Fetch the value of the context variable Key, return Default when Key is not found.

get_all/1

get_all(Context::z:context()) -> list()

Return a proplist with all context variables.

get_controller_module/1

get_controller_module(Context::z:context()) -> atom() | undefined

Get the resource module handling the request.

get_cookie/2

get_cookie(Key::binary(), Context::z:context()) -> binary() | undefined

Read a cookie value from the current request.

get_cookies/2

get_cookies(Key::binary(), Context::z:context()) -> [binary()]

Read all cookie values with a certain key from the current request.

get_envdata/1

get_envdata(Context::z:context()) -> cowmachine_middleware:env() | undefined

Return the cowmachine request data of the context

get_q/2

get_q(Keys::string() | atom() | binary() | list(), Context::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.

get_q/3

get_q(Key::binary() | string() | atom(), Context::z:context(), Default::term()) -> z:qvalue()

Get a request parameter, either from the query string or the post body. Post body has precedence over the query string.

get_q_all/1

get_q_all(Context::z:context()) -> [{binary(), z:qvalue()}]

Get all parameters.

get_q_all/2

get_q_all(Key::string() | atom() | binary(), Context::z:context()) -> [z:qvalue()]

Get the all the parameters with the same name, returns the empty list when non found.

get_q_all_noz/1

get_q_all_noz(Context::z:context()) -> [{binary(), z:qvalue()}]

Get all query/post args, filter the zotonic internal args.

get_q_validated/2

get_q_validated(Keys::string() | atom() | binary(), Context::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.

get_qargs/1

get_qargs(Context::z:context()) -> [{binary(), z:qvalue()}]

Fetch all arguments starting with a 'q'. This is used for queries.

get_render_state/1

get_render_state(Context::z:context()) -> z_render:render_state() | undefined

get_req_header/2

get_req_header(Header::binary(), Context::z:context()) -> binary() | undefined

Get a request header. The header MUST be in lower case.

get_req_path/1

get_req_path(Context::z:context()) -> binary()

Return the request path

get_reqdata/1

get_reqdata(Context::z:context()) -> cowboy_req:req() | undefined

Return the cowmachine request data of the context

get_resp_header/2

get_resp_header(Header::binary(), Context::z:context()) -> binary() | undefined

Get a response header

get_state_cookie/1

get_state_cookie(Context::z:context()) -> {ok, term()} | {error, term()}

Get the state cookie and decode it.

hostname/1

hostname(Context::z:context()) -> binary()

Return the preferred hostname from the site configuration

hostname_port/1

hostname_port(Context::z:context()) -> binary() | undefined

Return the hostname (and port) for http from the site configuration

hostname_ssl_port/1

hostname_ssl_port(Context::z:context()) -> binary() | undefined

Return the hostname (and port) for https from the site configuration

init_cowdata/3

init_cowdata(Req::cowboy_req:req(), Env::cowmachine_middleware:env(), Context::z:context()) -> z:context()

Set the cowmachine request data of the context

is_request/1

is_request(Context::z:context()) -> boolean()

Check if the current context is a request context

is_session/1

is_session(Context::z:context()) -> boolean()

Check if the current context has an active MQTT session. This is never true for the first request.

is_ssl_site/1

is_ssl_site(Context::z:context()) -> boolean()

Check if the preferred protocol of the site is https (always true)

is_zotonic_arg/1

is_zotonic_arg(X1) -> any()

lager_md/1

lager_md(Context) -> any()

lager_md/2

lager_md(MetaData, Context) -> any()

language/1

language(Context::z:context()) -> atom()

Return the selected language of the Context

new/1

new(Context::z:context() | atom() | cowboy_req:req()) -> z:context()

Return a new empty context, no request is initialized.

new/2

new(Site::atom(), Language::atom()) -> z:context()

Create a new context record for a site with a certain language

new/3

new(Site::atom(), Language::atom(), Timezone::binary()) -> z:context()

new_tests/0

new_tests() -> any()

Create a new context used when testing parts of zotonic

output/2

output(MixedHtml::term(), Context::z:context()) -> {iolist(), z:context()}

pickle/1

pickle(Context::z:context()) -> tuple()

Pickle a context for storing in the database

prune_for_async/1

prune_for_async(Context::z:context()) -> z:context()

Make the context safe to use in a async message. This removes render_state and the db transaction.

prune_for_database/1

prune_for_database(Context::z:context()) -> z:context()

Cleanup a context so that it can be used exclusively for database connections

prune_for_scomp/1

prune_for_scomp(Context::z:context()) -> z:context()

Cleanup a context for cacheable scomp handling. Resets most the render_state to prevent duplicating between different (cached) renderings.

prune_for_spawn/1

prune_for_spawn(Context::z:context()) -> z:context()

Minimal prune, for ensuring that the context can safely used in two processes

q_upload_keepalive/2

q_upload_keepalive(X1::boolean(), Context::z:context()) -> ok

Keep the tempfiles alive by attaching the current process to its monitors

reset_state_cookie/1

reset_state_cookie(Context::z:context()) -> z:context()

Delete the state cookie.

session_id/1

session_id(Context::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.

set/2

set(PropList::proplists:proplist(), Context::z:context()) -> z:context()

Set the value of the context variables to all {Key, Value} properties.

set/3

set(Key::atom(), Value::term(), Context::z:context()) -> z:context()

Set the value of the context variable Key to Value

set_client_context/2

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.

set_controller_module/2

set_controller_module(Module::atom(), Context::z:context()) -> z:context()

set_cookie/3

set_cookie(Key::binary(), Value::binary(), Context::z:context()) -> z:context()

Set a cookie value with default options.

set_cookie/4

set_cookie(Key::binary(), Value::binary(), Options::list(), Context::z:context()) -> z:context()

Set a cookie value with cookie options.

set_cors_headers/2

set_cors_headers(Default::[{binary(), binary()}], Context::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.

set_envdata/2

set_envdata(Env::cowmachine_middleware:env() | undefined, Context::z:context()) -> z:context()

Set the cowmachine request data of the context

set_language/2

set_language(Lang::atom() | binary() | string() | list(), Context::z:context()) -> z:context()

Set the language of the context, either an atom (language) or a list (language and fallback languages)

set_nocache_headers/1

set_nocache_headers(Context::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.

set_noindex_header/1

set_noindex_header(Context::z:context()) -> z:context()

Set the noindex header if the config is set, or the webmachine resource opt is set.

set_noindex_header/2

set_noindex_header(Force::term(), Context::z:context()) -> z:context()

Set the noindex header if the config is set, the webmachine resource opt is set or Force is set.

set_q/2

set_q(KVs::[{binary() | string() | atom(), z:qvalue()}] | map(), Context::z:context()) -> z:context()

Set the value of multiple request parameter arguments

set_q/3

set_q(Key::binary() | string() | atom(), Upload::z:qvalue(), Context::z:context()) -> z:context()

Set the value of a request parameter argument Always filter the #upload{} arguments to prevent upload of non-temp files.

set_q_all/2

set_q_all(QArgs::[{binary(), z:qvalue()}], Context::z:context()) -> z:context()

Replace all parameters.

set_render_state/2

set_render_state(RS::z_render:render_state() | undefined, Context::z:context()) -> z:context()

set_req_metrics/2

set_req_metrics(Metrics::map(), Context::z:context()) -> ok

Add metrics data to the Cowboy request, will be added to the metrics notifications.

set_reqdata/2

set_reqdata(Req::cowboy_req:req() | undefined, Context::z:context()) -> z:context()

Set the cowmachine request data of the context

set_resp_header/3

set_resp_header(Header::binary(), Value::binary(), Context::z:context()) -> z:context()

Set a response header for the request in the context.

set_resp_headers/2

set_resp_headers(Headers::[{binary(), binary()}], Context::z:context()) -> z:context()

Set multiple response headers for the request in the context.

set_security_headers/1

set_security_headers(Context::z:context()) -> z:context()

Set security related headers. This can be modified by observing the 'security_headers' notification.

set_session_id/2

set_session_id(Sid::binary(), Context::z:context()) -> z:context()

Set the cotonic session id. Mostly used when on a request with a cotonic session id in the cookie.

set_state_cookie/2

set_state_cookie(Data::term(), Context::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.

set_tz/2

set_tz(Tz::string() | binary() | boolean(), Context::z:context()) -> z:context()

Set the timezone of the context.

site/1

site(Context::z:context() | cowboy_req:req()) -> atom()

Maps the site in the request to a site in the sites folder.

site_protocol/1

site_protocol(Context::z:context()) -> binary()

Fetch the protocol for absolute urls referring to the site (always https).

state_cookie_secret/1

state_cookie_secret(Context::z:context()) -> binary()

Return the secret used to encode the state cookie.

tz/1

tz(Context::z:context()) -> binary()

Return the selected timezone of the Context; defaults to the site's timezone

tz_config/1

tz_config(Context::z:context()) -> binary()

Return the site's configured timezone.


Generated by EDoc