exampple v0.10.6

Exampple.Xmpp.Stanza.Xdata (exampple v0.10.6)

Using Xdata gives the functionality to create and validate forms. You can use Xdata to define your own form, create a sent and/or validate the form against the rules you defined giving the facilities to translate it directly to stanzas or XML string.

Link to this section Summary

Types

t()

Functions

add_data(xdata, var, value)

Add a value inside of the data structure. In difference of cast/2 this is forcing to be included and it's not checking the types.

add_error(xdata, name, text)

Add an error definition inside of the structure and set the valid? value to false. It needs the name of the error and the definition (or text) for the error.

cast(xdata, data)

Performs the inclusion of the data from the map into the second parameter into the first one. It's not performing validation, it's only checking which values are legal to be included and the way (using the types) we could include them.

field(var, type, args)

Creates a field definition inside of the form definition. The field is the most important part of the form and they have two missions: specifiy what will be useful for the form to be retrieved from the input map (cast) and the kind of data the field supports to ensure we are using the correct values (validation).

form(xmlns, title \\ nil, list)

Creates a form definition inside of a module which is using the Exampple.Xmpp.Stanza.Xdata module. The parameters are the following

has_field?(module, var)

Let us know if the field exists inside of a form definition.

instructions(text)

Creates the instructions definition inside of the form definition. It accepts only one parameter which is the text regarding of the instructions to be included inside of the form.

is_multi_type?(map)
is_multi_type?(module, var)

Let us know if a field from a definition specified as the first parameter, exists and it's a multi value. We can receive a boolean value if the field is found, otherwise we will receive the atom :error. If the boolean value is true, that is meaning the type is list-multi, text-multi or jid-multi, otherwise we receive false.

new(form_type_mod, xdata_form_type \\ "form")

Creates a new Xdata structure. It let us define the module which has the definition for the xdata, the type attribute for the form tag. The possible types for the xdata form are the following ones

parse(form, module)

Transform a XML representation of a xdata form into a Xdata structure. We have to provide the data to be transformed in string or Xmlel structure representations as first parameter. The second parameter let us define the module which have the definitions of the form.

submit(xdata, data)

Submitting a form is the action to get a previous form and proceed to the following step. The steps which follows usually a xdata form are the following ones

validate_form(xdata)

Performs the validation of the form (or Xdata structure). It's checking the data stored inside previously using cast/2 and then perform changes into the errors and valid? internal values.

Link to this section Types

Link to this type

t()

Specs

t() :: %Exampple.Xmpp.Stanza.Xdata{
  data: map(),
  errors: nil | [map()],
  module: module(),
  valid?: boolean(),
  xdata_form_type: String.t()
}

Link to this section Functions

Link to this function

add_data(xdata, var, value)

Specs

add_data(t(), String.t(), any()) :: t()

Add a value inside of the data structure. In difference of cast/2 this is forcing to be included and it's not checking the types.

Link to this function

add_error(xdata, name, text)

Specs

add_error(t(), String.t(), String.t()) :: t()

Add an error definition inside of the structure and set the valid? value to false. It needs the name of the error and the definition (or text) for the error.

Link to this function

cast(xdata, data)

Specs

cast(t(), map()) :: t()

Performs the inclusion of the data from the map into the second parameter into the first one. It's not performing validation, it's only checking which values are legal to be included and the way (using the types) we could include them.

Link to this macro

field(var, type, args)

(macro)

Creates a field definition inside of the form definition. The field is the most important part of the form and they have two missions: specifiy what will be useful for the form to be retrieved from the input map (cast) and the kind of data the field supports to ensure we are using the correct values (validation).

The field accepts two main arguments:

  • var is the name of the field.
  • type is the type of the field. The types are defined into the [XEP-004]. and they are defined below.

Types we can use:

  • :boolean: we can set the values as true or 1 and false or 0.
  • :fixed: this is not data itself, it is in use to define a separator into the form.
  • :hidden: data which will be sent to the user, and it should back as is from user.
  • :jid_multi: possible to send one or more JID as values.
  • :jid_single: a JID.
  • :list_multi: possible to send one or more elements defined into a list of options.
  • :list_single: possible to send one element from a defined list of options.
  • :text_multi: possible to send one or more text values.
  • :text_private: tells to the interface to obscure the input, special for password inputs.
  • :text_single: generic text entry. The most common.

The other options we can add to the specification are:

  • required (boolean) if the value is required. Default to false.

  • label (text) a label which will be shown into an interface.

  • desc (text) the description of the input.

  • value is the default value indeed.

  • options is a list of 2-element tuples which are {name, id} letting use to define as the name (the visual definition of the value) and id as the element which we use:

    [{"Male", "M"}, {"Female", "F"}]
Link to this macro

form(xmlns, title \\ nil, list)

(macro)

Creates a form definition inside of a module which is using the Exampple.Xmpp.Stanza.Xdata module. The parameters are the following:

  • xmlns (required) the namespace which will be inserted as FORM_TYPE data inside of the form.
  • title (optional) the title which will be apearing as the <title/> tag inside of the form.

We have to define a configuration block where we will use other macros like field or instructions, see below.

Link to this function

has_field?(module, var)

Specs

has_field?(module(), String.t()) :: boolean()

Let us know if the field exists inside of a form definition.

Link to this macro

instructions(text)

(macro)

Creates the instructions definition inside of the form definition. It accepts only one parameter which is the text regarding of the instructions to be included inside of the form.

Link to this function

is_multi_type?(map)

Specs

is_multi_type?(map()) :: boolean()
Link to this function

is_multi_type?(module, var)

Specs

is_multi_type?(module(), String.t()) :: :error | boolean()

Let us know if a field from a definition specified as the first parameter, exists and it's a multi value. We can receive a boolean value if the field is found, otherwise we will receive the atom :error. If the boolean value is true, that is meaning the type is list-multi, text-multi or jid-multi, otherwise we receive false.

Link to this function

new(form_type_mod, xdata_form_type \\ "form")

Specs

new(module(), String.t()) :: t()

Creates a new Xdata structure. It let us define the module which has the definition for the xdata, the type attribute for the form tag. The possible types for the xdata form are the following ones:

  • form (default): The form-processing entity is asking the form-submitting entity to complete a form.
  • submit: The form-submitting entity is submitting data to the form-processing entity. The submission MAY include fields that were not provided in the empty form, but the form-processing entity MUST ignore any fields that it does not understand. Furthermore, the submission MAY omit fields not marked with <required/> by the form-processing entity.
  • cancel: The form-submitting entity has cancelled submission of data to the form processing entity.
  • result: The form-processing entity is returning data (e.g., search results) to the form-submitting entity, or the data is a generic data set.

See further here: https://xmpp.org/extensions/xep-0004.html#protocol-formtypes

Link to this function

parse(form, module)

Specs

parse(String.t() | Exampple.Xml.Xmlel.t(), module()) :: t()

Transform a XML representation of a xdata form into a Xdata structure. We have to provide the data to be transformed in string or Xmlel structure representations as first parameter. The second parameter let us define the module which have the definitions of the form.

Link to this function

submit(xdata, data)

Submitting a form is the action to get a previous form and proceed to the following step. The steps which follows usually a xdata form are the following ones:

  • form: we receive the form with this type and the specification of the fields. It gives us information about what we should to fill up.
  • submit: when we get a form and perform the submit function, it is changed to submit. We have to provide the specific data for the form as well. It performs first a cast and then a validation. If everything is fine, then we have prepared a form to be in use.
  • result: if we receive a submit form and we want to reply it, it is changed to result and we can provide more information inside or modify the information to report to the submitter what was changed or added.

See cast/2 and validate_form/2 for further information.

Link to this function

validate_form(xdata)

Specs

validate_form(t()) :: t()

Performs the validation of the form (or Xdata structure). It's checking the data stored inside previously using cast/2 and then perform changes into the errors and valid? internal values.

After the running of the validation we'll get the transformed Xdata structure and we can use valid? value inside of the structure to know if the validation was fine or it detects errors.