Directive Parameters

On this Page:

Standard Directives Special Directives
Captcha
Conditional Field
Download File
Email
Encrypt
Field
File
Imperius
Match
Redirect
Redirect-template
Require
Subscribe
Sum
Unset
Unsubscribe
Upload
BUMC
Cashier
One Help

Standard Directives

Captcha

  • Base tag:
    • <directive action="captcha" />
  • Full tag example:
    • <directive action="captcha" />
  • Typical use:
    • Reduces spam by placing a test to prevent automatic bots from submitting your form.
Parameters Required? Usage References
There are no parameters for this directive. n/a Identify what form field is being identified for comparison. How-to

Example

Note that captchas can reduce but may not eliminate form spamming.

Conditional Field

  • Base tag:
    • <directive action="conditional-field" {parameters} />
  • Full tag examples:
    • <directive action="conditional-field" source_field="status" source_value="student" target_field="cost" target_value="10" />
    • <directive action="conditional-field" source_field="age" source_value="21" comparison="greater" target_field="cost" target_value="20"/>
    • <directive action="conditional-field" source_field="age" source_value="21" comparison="less-or-equal" target_field="cost" target_value="50"/>
  • Typical uses:
    • Change prices based on user input (e.g., for discounts).
    • Select which output templates should be used.
    • Select e-mail recipients based on user input.
Parameters Required? Usage References
source_field Yes Identify what form field is being used for comparison. Example
source_value Yes Identify the exact value that the source_field must have for the conditional-field directive to take effect. Same as above
target_field Yes Identify the field whose value will be replaced if source_field matches source_value. Same as above
target_value Yes Specify what value will be replace target_field if source_field matches source_value. Same as above
comparison No Use mathematical comparisons to determine whether the conditional-field takes effect. The possible parameter values are:

  • greater-than
  • less-than
  • greater-or-equal
  • less-equal
Same as above

Download File

  • Base tag:
    • <directive action="download-file" {parameters} />
  • Full tag examples:
    • <directive action="download-file" file="/myawesomesite/myfile.txt" content_type="application/octet-stream" />
    • <directive action="download-file" file="/myawesomesite/myfile.txt" filename="file.txt" content_type="application/octet-stream" />
  • Typical uses:
    • Force a file download when the form is submitted.
  • Additional requirements:
    • The file you would like downloaded must be in the same directory as a telegraph.allow file, a blank file that allows Telegraph access to download files from that directory. download-file will not work without the telegraph.allow file.
Parameters Required? Usage References
file Yes Define the location of the file to download, relative to form_configuration. n/a
content_type Yes The MIME type to give for this file. Applications are application/octet-stream. n/a
filename No Specifies a filename that the browser should recommend when the file is saved. n/a

Email

  • Base tag:
    • <directive action="email" {parameters} />
  • Full tag examples:
    • <directive action="email" to="fred.flinstone@example.com" from="[e-mail]" subject="Question Received" />
    • <directive action="email" to="fred.flinstone@example.com" from="[e-mail]" subject="[what-is-this-about]" template="telegraph/question.template" />
    • <directive action="email" to="[to-e-mail-selector]@example.com" from="[e-mail]" subject="[what-is-this-about]" template="telegraph/[to-e-mail-selector].template" error="There was a problem sending this e-mail. Please check that the e-mail address that you entered is correct." encoding="UTF-8"/>
  • Typical use:
    • Send e-mails to one or more users.

You can send multiple e-mails (potentially using different subjects, templates, and recipients) by adding additional e-mail directives to your configuration file.

Parameters Required? Usage References
to Yes Identify where the Telegraph-generated e-mail will be sent. How-to

Example

from No Identify the from/reply-to address used for the Telegraph-generated e-mail. (Note: if this parameter is not specified, Telegraph will insert server information on the server used to send the outgoing e-mail.) Same as above
subject No Identify the Subject used in the Telegraph-generated e-mail. (Note: if this parameter is not specified, Telegraph will insert a generic message.) Same as above
template No Identify the e-mail template to be used for the Telegraph-generated e-mail, relative to the form’s parent directory. (Note: if this parameter is not specified, Telegraph will generate a basic e-mail specifying any form field data and form field names that have been used on your form.) Same as above
error No Specify an error message to be displayed if there is a problem sending e-mail. Same as above
encoding No Specify what character encoding set is used. This should match the encoding used on your web form (e.g., UTF-8). If diacriticals don’t show up correctly, you probably need to add this. Example
html No Specify whether or not to send the message as HTML. Include html=”yes” to send formatted email from Telegraph. N/A

Encrypt

  • Base tag:
    • <directive action="encrypt" {parameters} />
  • Full tag example:
    • <directive action="encrypt" to="applications@example.com" from="[e-mail]" subject="Scholarship Application" template="telegraph/apps.template" error="There was a problem sending this e-mail." encoding="UTF-8"/>
  • Typical use:
    • Encrypt sensitive information (e.g., Social Security numbers).

Parameters Required? Usage References
This directive uses the same parameters as the E-mail directive. n/a n/a How-to

Examples

To use this directive, the to e-mail address must be a BU e-mail address with a PGP public key on file.

Note: Online credit card transactions should use the Cashier directive.

Field

  • Base tag:
    • <directive action="field" {parameters} />
  • Full tag examples:
    • <directive action="field" name="time-and-date" value="[timestamp:date] at [timestamp:time]" />
    • <directive action="field" name="full-name " value="[last_name] [first_name]" />
    • <directive action="field" name="name-tag " value="[salutation] [profile:last_name] of [place]" />
  • Typical uses:
    • Combine user data into a single field.
    • Convert profile or time and date information into usable field data.
Parameters Required? Usage References
name Yes Identify the name of the new field being created. Make sure that this doesn’t match an existing field. How-to

Example

value Yes Identify a combination of existing fields, date/time information, profile information, and/or specified characters used to produce the value of the new field. Same as above

File

  • Base tag:
    • <directive action="file" {parameters} />
  • Full tag examples:
    • <directive action="file" filename="names" fields="full-name" />
    • <directive action="field" value="[last_name] [first_name]" />
  • Typical uses:
    • Create or update a spreadsheet with data from form submissions.
    • Create or update a webpage with data from form submissions.
Parameters Required? Usage References
filename Yes Identify the name of the output file. If this file doesn’t exist, Telegraph will create it for you. How-to

Example

format No (if using template)

Yes (if creating a spreadsheet)

Identify the spreadsheet format to be used while outputting data to a file. The possible parameter values are:

  • csv
  • tab-delimited
How-to
fields No (if using template)

Yes (if creating a spreadsheet)

Identify the fields (and order of fields) when entering data into a spreadsheet. This field is ignored if the template parameter is used, since the template itself determines the form fields to use and their placement. How-to
template No (if creating a spreadsheet)

Yes (if not creating a spreadsheet)

Identify an output template to be used when writing form data to a file. If this parameter is used, the content of the format and fields parameters (if present) is ignored. How-to
overwrite No With overwrite=”yes” Telegraph overwrites the output contents with the original template using the currently-submitted data. n/a

Imperius

  • Base tag:
    • <directive action="imperius" {parameters} />
  • Full tag examples:
    • <directive action="imperius" filename="index.html" />
  • Typical use:
    • Displays error messages on your web form, rather than on a separate error page.
Parameters Required? Usage References
filename Yes Specify the filename of your form. This is necessary to tell Telegraph where to display errors. How-to

Example

url For WordPress pages Because there is no filename (e.g., index.html) for WordPress forms, the url parameter must be used to tell Telegraph where to display errors. Same as above

It is sometimes necessary to add a base href tag to your form to make sure that images display correctly using Imperius.

Match

  • Base tag:
    • <directive action="match" {parameters} />
  • Full tag example:
    • <directive action="match" field1="[e-mail1]" field2="[e-mail2] />
  • Typical use:
    • Verify an e-mail address by asking that it be entered twice.
Parameters Required? Usage References
field1 Yes Identify the first of two fields that must be matched for the form to be submitted. Normally used for confirming an e-mail address by asking for it twice. How-to

Example

field2 Yes Identify the second of two fields that must be matched for the form to be submitted. Normally used for confirming an e-mail address by asking for it twice. Same as above

Output

  • Base tag:
    • <directive action="output" {parameters} />
  • Full tag examples:
    • <directive action="output" errors="errors.html" />
    • <directive action="output" thanks="thanks.html" />
    • <directive action="output" errors="errors.html" thanks="thanks.html" />
    • <directive action="output" errors="templates/[order-type]-problems.html" thanks="templates/[order-type].html" />
  • Typical uses:
    • Send the form user to a custom page including form data (e.g., an electronic receipt, thank you or error page).
Parameters Required? Usage References
errors No Identify a web page (relative to the form) to redirect users to if there has been an error with form submissions. You can use a web page template to display custom error messages. (Note: your web page template must include a base href tag to display properly within Telegraph.) Example
thanks No Identify a web page (relative to the form) to redirect users to after a form has been successfully submitted with no errors. You can use a web page template to display some form information (such as a name) on your thank you page. (Note: your web page template must include a base href tag to display properly within Telegraph.) Same as above

Redirect

  • Base tag:
    • <directive action="redirect" {parameters} />
  • Full tag examples:
    • <directive action="redirect" href="http://www.google.com/mail/" />
    • <directive action="redirect" href="http://www.example.com/" />
  • Typical use:
    • Redirect a user to any page after a successful form submission, regardless of whether or not the page is hosted at BU.

Redirect-template

  • Base tag:
    • <directive action="redirect-template" {parameters} />
  • Full tag examples:
    • <directive action="redirect-template" filename="thanks.html" />
    • <directive action="redirect-template" url="http://www.example.com/" />
  • Typical use:
    • Redirect a user to any page after a successful form submission. This should be used with forms that collect credit card information to prevent resubmitting the form when a thank you page is refreshed.
    • When using this directive, be sure to include a Telegraph form (even a blank one) on the receiving page using the form tag.
      <form action="/phpbin/telegraph/index.php"></form>
Parameters Required? Usage References
filename Yes Specify a file to redirect to after the form is submitted. n/a
url Yes, but only when building a form for WordPress. Specify a URL to redirect to after the form is submitted. n/a

Require

  • Base tag:
    • <directive action="require" {parameters} />
  • Full tag examples:
    • <directive action="require" field="e-mail" />
    • <directive action="require" field="e-mail" format="e-mail" />
  • Typical use:
    • Require that specified field(s) be filled out and/or adhere to specific formats.
  • Note:
Parameters Required? Usage References
field Yes Identify the form field which must contain input. How-to

Example

format No Identify one of several special, required formats for any data input into this field. How-to
error No Specify a custom error message when the specified form field either doesn’t contain input or if the format parameter is used. Same as above

Subscribe

  • Base tag:
    • <directive action="subscribe" {parameters} />
  • Full tag examples:
    • <directive action="subscribe" address="[e-mail]" list="nis-telegraph-l" />
    • <directive action="subscribe" address="[e-mail]" list="nis-telegraph-l" notification="no" password="MxyZptlk" />
    • <directive action="subscribe" address="[e-mail]" list="nis-telegraph-l" notification="yes" password="MxyZptlk" />
  • Typical use:
    • Subscribe an e-mail address to a Majordomo mailing list.
Parameters Required? Usage References
address Yes Identify the e-mail address which is being subscribed to the list. How-to
list Yes Identify the Majordomo mailing list to which the e-mail address specified by the address parameter is being subscribed. How-to
notification No Identify if a Majordomo-generated confirmation message should be sent to the e-mail address specified by the address parameter. Requires the use of the password parameter. Can be set to yes or no. How-to
password No (for unmoderated lists)

Yes (for moderated lists)

Identify the administrative password for the mailing list specified by the list parameter. How-to

Sum

  • Base tag:
    • <directive action="sum" {parameters} />
  • Full tag examples:
    • <directive action="sum" list="costs" total="total_cost" />
    • <directive action="sum" add="[total:total_cost]" total="amount_due" />
    • <directive action="sum" subtract="[deposit_amount]" total="amount_due" />
  • Typical use:
    • Add, subtract, or multiply values, which can be listed as number or as form fields (in brackets). Each line of directive adds an element to the final total. In the example above, for instance, the first directive adds together all of the numbers in the list array and produces the total_cost, while the second line puts them into amount_due, and the third subtracts the deposit_amount.
Parameters Required? Usage References
add Yes Specifies a number to add to the total. This can be an actual number or a field name (in brackets). n/a
subtract Yes Specifies a number to subtract to the total. This can be an actual number or a field name (in brackets). n/a
total Yes (Required) Specifies the name of the field that will contain the results of your calculation. This must be a field name (with no brackets). If it doesn’t already exist, it will be created and will start at 0. Later, you can access this number by referring to [total:my_field_name]. n/a
quantity No Specifies a number by which to multiply the “add” or “subtract” amount. n/a
list No Adds up all the items in an array of numbers to calculate a total. n/a

Unset

  • Base tag:
    • <directive action="unset" {parameters} />
  • Full tag example:
    • <directive action="unset" field="tracking-code" />
  • Typical use:
    • Stops an internal-only variable (e.g., one used for database input only)  from displaying in browser output.
Parameters Required? Usage References
field Yes Identify the name of the new field which should not be displayed in web browser output. (Note: this does not affect the field identified in this parameter from being used in any file, database, or e-mail output – only in a specified output template.) n/a

Unsubscribe

  • Base tag:
    • <directive action="unsubscribe" {parameters} />
  • Full tag examples:
    • <directive action="unsubscribe" address="telegraph-test-l" />
    • <directive action="unsubscribe" address="[list-name]-l" />
    • <directive action="unsubscribe" address="telegraph-test-l" />
  • Typical use:
    • Unsubscribe an email address from one or more majordomo lists.
Parameters Required? Usage References
address Yes Identify the e-mail address which is being unsubscribed from the list. How-to
list Yes Identify the Majordomo mailing list to which the e-mail address specified by the address parameter is being unsubscribed. Same as above
notification No Specify if a Majordomo-generated confirmation message should be sent to the e-mail address specified by the address parameter. Requires the use of the password parameter. The possible parameter values are:

  • yes
  • no
Same as above
password No (for unmoderated lists)

Yes (for moderated lists)

Identify the administrative password for the mailing list specified by the list parameter. Same as above

Upload

  • Base tag:
    • <directive action="upload" {parameters} />
  • Full tag examples:
    • <directive action="upload" field="file-uploads" destination="telegraph/uploads" />
    • <directive action="upload" field="file-uploads" destination="telegraph/uploads/[application-type]" />
    • <directive action="upload" field="file-uploads" destination="telegraph/uploads/[application-type]" create="yes" />
    • <directive action="upload" field="file-uploads" destination="telegraph/uploads/[application-type]" require="yes"/>
  • Typical use:
    • Upload files to the web server.
  • Note:
    • If you use this parameter, your form tag must include enctype=”multipart/form-data”, e.g.,<form action="https://www.bu.edu/phpbin/telegraph/" method="post" name="myform" id="myform" enctype="multipart/form-data">
Parameters Required? Usage References
field Yes Identify the field that selects the file to be uploaded. n/a
destination Yes Identify the directory (relative to your form) to which this file will be uploaded. (Note: this directory must be activated for your form to write to it.) n/a
create No Specify whether Telegraph can create additional subdirectories if they are specified in the destination parameter but don’t already exist. (Note: this is always a good option to set to yes, especially if a form field is used to determine the subdirectory.) The possible parameter values are:

  • no
  • yes
n/a
require no The upload directive doesn’t support use of the traditional require directive to validate. Instead, use the require parameter with “yes” as its value to prevent the form from submitting without a file to upload:

require="yes"

n/a

Special Directives

BUMC

  • Base tag:
    • <directive special="bumc" {parameters} />
  • Note:
    • This special directive is used in some BUMC forms that were migrated to WordPress. This special directive is no longer required; forms using this should be converted to use either the standard Telegraph directives or Gravity Forms.
  • Typical uses:
    • Adapt forms from the old BUMC website to work on the current BUMC WordPress server. Note: this directive should not be used while creating any new forms.

Cashier

  • Base tag:
    • <directive special="cashier" {parameters} />
  • Note:
      This special directive requires special set-up and financial training. Please contact the Cashier’s Office for more information.
  • Full tag examples:
    • <directive special="cashier" is_test="Y" is_office="N" amount="20.00" cashier_app_code="12345" cashier_conf_code="CF123" />
    • <directive special="cashier" is_test="N" is_office="N" amount="20.00" cashier_app_code="12345" cashier_conf_code="CF123" />
    • <directive special="cashier" is_test="N" is_office="N" amount="[total]" cashier_app_code="12345" cashier_conf_code="CF123" />
    • <directive special="cashier" is_test="N" is_office="Y" amount="[total]" cashier_app_code="12345" cashier_conf_code="CF123" />
  • Typical uses:
    • Collect and process credit card data for online donations, purchases, or registrations.
    • Collect and submit credit card data collected in person or via phone for online processing.
Parameters Required? Usage References
is_test Yes Determine whether the form feeds the Cashier’s test system, or conducts actual charges with actual credit cards. The possible parameter values are:

  • Y (i.e., “Yes”)
  • N (i.e., “No”)
Example

How-to

is_office Yes Identify whether the information is being entered by the cardholder, or being entered by office staff (e.g., for verbal orders given over the phone).

  • Y (i.e., “Yes”)
  • N (i.e., “No”)

A typical setup would have two copies of the same form using different configuration files – one for online orders (with is_office=”N”), and the other for office staff to enter orders given in person or via phone (with is_office=”Y”).

Same as above
amount Yes Identify the amount of money to be charged to the credit card. This can be a fixed amount or (more likely) a field from your form. Same as above
cashier_app_code Yes Identify one of two required codes obtained from the Cashier’s Office. Same as above
cashier_conf_code Yes Identify the second of two required codes obtained from the Cashier’s Office. Same as above

One Help

  • Base tag:
    • <directive special="one-help-only" {parameters} />
  • Note:
      The One Help directive is used exclusively for forms feeding the One Help system. One Help forms require special setup in conjunction with Information Services & Technology.