Directive Parameters

List of Directives

Captcha
Conditional Field
Download File
Email
Field
File
Imperius
Match
Nelnet
Output
Redirect
Redirect-template
Require
Subscribe
Sum
Unset
Unsubscribe
Upload

Marconi also supports some “special” directives that were created for specific forms. If your form configuration contains a directive not on this list, it may be purpose-built. Contact IS&T for support with any special directives.

Standard Directives

Captcha

• Base tag:
  • <directive action="captcha" />
• Full tag example:
  • <directive action="captcha" />
  • If used on a form that uses the Nelnet directive, use the the Captcha directive first and include “_skip” parameter: <directive action="captcha" _skip="[if?:transactionId=::yes]" />

• Typical use:
  • Reduces spam by placing a test to prevent automatic bots from submitting your form.

Parameters	Required?	Usage	References
_skip	no	Use _skip parameter when using both Captcha and Nelnet directives on the same form. Use Captcha directive before Nelnet Directive with <directive action=”captcha” _skip=”[if?:transactionId=::yes]” />	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

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

Nelnet

• Base tag:
  • <directive special="nelnet" {parameters} />
• Note: This special directive requires special set-up and financial training. Please contact the Cashier’s Office for more information.
• Full tag examples (replace order_type=”AB123″ with the code your receive from the Cashier’s Office):
  • <directive special="nelnet" is_test="Y" amount="20.00" order_type="AB123"/>
  • <directive special="nelnet" is_test="Y" amount="[total]" order_type="AB123"/>
• Typical uses:
  • Collect and process credit card data for online purchases or registrations.
  • Collect and submit credit card data collected in person or via phone for online processing.

Parameters	Required?	Usage	References
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. amount="20.00"(a fixed amount) amount="[total]" (a field value from your form)	Example How-to
order_type	Yes	Identify required order_type code obtained from the Cashier’s Office. The order_type parameter tells Nelnet whether it is a public or office payment and other settings and one form may now submit to more than one order_type. order_type="AB123" (with your order_type received from Cashier’s Office) order_type="[if?:email=dept_email@bu.edu:OF321:AB123]" (using [if?:] special variable to populate the order_type value so Nelnet knows whether public or office payment.)	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:
  • The require directive does not work with the upload directive. Learn more about requiring file uploads.

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