Context module for actions shared among ZSchemas.Documents.* structs.

Variables + Merge Variables

In email/html documents parlance, a "variable" is whole struct that defines meta-information about field name, default value, whether the field will be required when the template is merged and so on. A "merged variable", by contrast, is just a key/value store of the actual field names and values that became implemented when the template was rendered into an instance.

# variable
%ZSchemas.Documents.Variable{
  name: "test_field",
  default_value: "thing that will render if no user data is passed",
  required: false
}

# merged variable
%{test_field: "user data override"}

Required Variables

Template variables can be marked as required. If this is the case, then an attempt to generate a document (merged template) will fail unless all required variables are passed as data.

For example, if we have an ZSchemas.Documents.HtmlTemplate with a %{field_name: "First Name", required: true} variable, then any attempt to make a ZSchemas.Documents.HtmlDocument will fail unless it passes the merged variable %{first_name: "some value"}.

The exception to this is "required" fields with a default value. If a default value is set in the template, then that value will be used for all documents that are merged from that template, if they do not provide a replacement merged value.

Field Name Normalization

In templates, any variables will have their field names normalized (using normalize_field_name/1) when doing evaluation. This means that a person can use whatever they want for field names (like in FileMaker, for example), and we can still reference the fields in an EEX context, knowing that they'll be usable.

For example, if a field name is entered as First Name, it'll be referened in the EEX template as @first_name.