Docxpresso variables processing

As explained elsewhere "placeholder variables" are the way to tell Docxpresso that certain parts of the document are waiting for some kind of user interaction.

Docxpresso variables are just plain text enclosed in double curly brackets, i.e. {{some_variable}} (remember only to use plain ASCII chars, dashes and underscores).

By default Docxpresso assumes that those variables are of plain text type and assigns them certain configuration settings (more about this in what follows). Although this must be enough in the simplest of documents, in general, we need to add further metadata in order to get a truly useful end user interface.

By clicking in the variable name a pop up window will show up with all the basic available configuration settings. Let us go in detail over every single one of them:

  • Label: this is the value that will be shown in the interface in place of the variable inserted into the document. If the end user does not modify it, it will be saved with the rest of the data and it also show in the resulting final document. Its default value is just the same variable name.
  • Tip: this is the tip text that will show up whenever the end user passes the mouse over the interactive variable area. Its default value is again the variable name. If left empty, there will be no tip in the end user interface.
  • Type: this is the data type of the variable. Its default value is text but there are many other available options:
    • text: this corresponds to plain text with no carriage returns, although one can include, in principle, some basic formatting using the buttons included in the panel in the top of the page. This is the default data type.
    • Multiline text: the same as before but hitting the enter in the keyboard we will be able to introduce a carriage return.
    • full rich text area: when the end-user clicks it a WYSIWYG editor will open and full rich text may be introduced. Notice that this type of data better fits variables that stand alone by themselves in a paragraph or table cell (Docxpresso automatically cleans all prior paragraph data and structure before inserting the rich text value into the final document).
    • date: the end user will be offer a date picker to choose a date (we will talk about the date format below).
    • options: this is the right choice whenever we want to offer the end user a limited set of possible values. You should specify:
      • display mode: dropdown, multiselect, checkboxes or radio buttons.
      • Values: list of available options separated by semicolons (;).
    • predefined list: whenever you have a long list of options or simply some closed list of options that you oftenly use you may create a predefined list as a Docxpresso resource, i.e. a list of world countries, U.S. states, etcetera. You will be offered a list of the available resources from which you should pick one.
    • remote procedure call: you may also populate a dropdown with a list of options obtained from an external web service previously defined in the Resources section of the website (the actual definition of the RPC may most probably require the participation of a programmer or tech savvy staff). You will be offer a list of the predefined RPCs and you should just pick one.
    • validation: you may choose from the dropdown:
      • a standard predefined validation like: none (default), empty, numeric, email, URL, phone or date (standard US format: mm/dd/yyyy)
      • A custom validation previously defined in the Resources section of the website. For example, you may include other date formats different from the standard one. Please see our tutorial page on custom validations and alternative date formats.
    • General settings:
      • Editable: if checked (default value) the variable will be editable by the end user. In certain cases, where the variable is prepopulated via programmatical means, you may choose it not to be editable by the end user.
      • Global: it is quite usual that a variable appears more than once in a document so we should instruct Docxpresso if that variable is “global”, i.e. if once edited somewhere changes all over the document. The default behaviour is the following: by default, is true if it is not included in a cloneable block of the document and false otherwise, the logic being that if it belongs to a block that can be replicated, like a table row, it may naturally take different values.
      • Rich text: true by default. It allows for certain restricted formatting in variable types that are not full rich text. If true, the formatting buttons accessible in the top of the end user web interface will be active while editing the corresponding variable.
    • Comments: this will show up as a helper box in the end user interface offering further assistance and auxiliary info to the user.

Variable prefixes

In certain cases, you may wish to set up a workflow for a particular document in which part of the documents are only editable by some type of user and not others.

In this case, you should include a unique prefix to each variable that identifies it as belonging to a specific group that may be potentially blocked for edition by certain user by making explicit the "prefix option" in the document request parameters (GET or POST).

If, for example, you want the prefix to be “NE” you should enter the variable as: {{NE_variable_name}} in the original document. Docxpresso will take care of all the details afterward as long as the prefix is indicated in the web request.