Entry Form

PyroStreams gives you tools to allow for modification of data through PyroCMS page templates, so you can build data interactions without having to give users access to your control panel.

The Entry Form

PyroStreams allows you to display a create or edit form using the PyroCMS tag system. Forms are generated using the following format:

{{ streams:form stream="concerts" mode="new" }}

	{{ form_open }}

	<table>

	{{ fields }}

	<tr class="{{ odd_even }}">
	<td width="250">{{ input_title }}{{ required }} <small>{{ instructions }}</small></td>
	<td>{{ error }}{{ input }}</td>
	</tr>

	{{ /fields }}

	</table>

	{{ form_submit }}

	{{ form_close }}

{{ /streams:form }}

Form Parameters

Parameter	Default	Description
stream		Required. Stream slug for the stream we are editing or creating data for.
mode	new	Either new or edit, depending on if you are creating or editing data..
edit_id		Required if editing an entry. ID of the entry to edit.
where		Allows you to specify a where parameter using the following structure: field_slug==value.
required	<span class="required">* required</span>	String that populates the required variable if the field is required.
return	current url	Where to redirect to to when the form action is done. Use -id- to designate the insert id for when using the new mode. This will set a flash success/error message and redirect, so make sure the page you redirect to does not have a redirect itself, otherwise the flash message wil be lost between the two redirects.
error_start	<span class="error">	String that prepends error messages.
error_end	</span>	String that appends error messages.
include		Fields to include in the form, separated by pipe characters (\|). If you specify fields here, all other fields (excluding default columns) will be excluded.
exclude		Fields to exclude from the form, separated by pipe characters (\|).
use_recaptcha	no	Activates reCAPTCHA. See documentation below.
creator_only	no	When using the form in edit mode, setting this to yes will only show the form and allow editing of an entry if the creator_id matches the logged in user's id.

Fields Tag Pair

The fields tag pair loops through each input row and makes data available via variables that allows you to mark up your form in any way you'd like using the following tags:

Parameter	Description
{{ input_title }}	The field title.
{{ input_slug }}	The field slug.
{{ instructions }}	The field instructions.
{{ input }}	The field input element.
{{ required }}	If field is required, displays a required message. Blank if field is not required.
{{ odd_even }}	Displays odd or even based on the field count.

Example:

{{ fields }}

<label for="{{ input_slug }}">{{ title }}</label>
{{ if instructions }}<p>{{ instructions }}</p>{{ endif }}
<p>{{ input }}</p>

{{ /fields }}

Showing Individual Fields

If you want a finer-grain control over your form inputs, you can access various form variables with single tags. For instance, if you had a name field with a slug of 'your_name', you could display the input element by using {{ your_name:input }}.

The following variables are available for each input:

Parameter	Description
label	The name of the field.
slug	The slug of the field.
instructions	The instructions that you entereded when assigning the field.
input	The field form input.
error	The error for the field if there is one. If you have error_start and error_end specificied, the error will be wrapped in those variables.
is_required	Returns true/false based on whether the fireld is required or not.
required	The string to show if a field is required.

Example:

{{ title:label }} {{ if title:is_required }}Make sure to fill this in!{{ endif }}

{{ if title:instructions }}<p>{{ title:instructions }}</p>{{ endif }}

<p>{{ title:input }}</p>

Other Tags

Tag	Description
{{ form_open }}	Creates the opening form tag that submits to the current URL. It is highly recommended that you use this tag instead of using your own form opening tag, since this tag adds important hidden fields that some field types may rely on.
{{ form_submit }}	Creates a form submit button.
{{ form_reset }}	Creates a form reset button.
{{ form_close }}	Creates a form close tag.

Form Assets

Many fields have CSS or Javascript that needs to be loaded. Depending on your theme, the assets may not be automatically added to your page, breaking some fields. In this case, you can add them manually with the form_assets function. Just place this below your form tags:

{{ streams:form_assets }}

Note: You should already have jQuery loaded before the form_assets tag is used.

Overriding Success/Failure Messages

Many PyroCMS themes have built-in displays for flash data (that is, data that is only available on the next page refresh, and usually contains a message about the success/failure of the previous action). You can control what these messages say with these two parameters:

Parameter	Default	Description
success_message		Overrides flash success message content.
failure_message		Overrides flash failure message content.

Using reCAPTCHA

reCAPTCHA is a simple and high quality CAPTCHA tool, and PyroStreams makes it easy to implement. To start, get your public and private keys from reCAPTCHA. Then, add those keys into the reCAPTCHA config file, located in streams/config/recaptcha.php.

After that, all you need to do is add use_recaptcha="yes" in your form tag, and add the following tags:

{{ recaptcha }}

This is the actual reCAPTCHA box. It takes a parameter of theme, which is set to "red" by default. This can be changed to "clean", "white", or "blackglass" to fix your design.

{{ recaptcha_error }}

This displays the reCAPTCHA error. If obeys the form's error parameters so it will fit in with the rest of your form.

Email Notifications

When an entry form is submitted and processed successfully, you can set the form to send an email.

The entry form email notification feature hooks into PyroCMS native email template module, so to get started, you'll need to go to Design → Email Templates and create a new template. Aside from all the normal variables and functions you can access in a layout, the following special email variables are available to you:

Tag	Description
{{ sender_ip }}	The IP address of the sender.
{{ sender_os }}	The operating system of the sender.
{{ sender_agent }}	Full user agent of the sender.
{{ entry }} {{ /entry }}	The data for the newly submitted or updated form entry. All normal variables are available.

Note: These variables are also available in the email template subject field.

Once you've created your template, you can add the necessary variables to the form entry tag. The entry form supports sending two notifications - a and b. Each have their own set of variables. The variables below use {ID} as a replacement for either a or b.

Tag	Description
notify_{ID}	The email address (or addresses) to send the notification to. Multiple addresses can be separated by a pipe (\|) character. You can also use form input values here, so if you have a field called your_email_address, you can use your_email_address as an email value and it will send it to the user's input.
notify_template_{ID}	The slug of the email template to use.
notify_from_{ID}	Optional custom from email. This can be a single email address or an email address and name separated by a pipe (\|) character. If no value is provided, PyroStreams will use your admin email and site name as the from value.

When you put it all together, you entry tag may look like this:

{{ streams:form stream="messages" mode="new" notify_a="admin@example.com|email_field" notify_template_a="new_feedback" notify_from_a="noreply@example.com|Example" }}

CSRF

If you need to use CSRF, the necessary hidden elements will be added when you use the form_open tag that is available in the form function.

However, if you can't use the form_open tag, you can add the CSRF elements by adding:

{{ streams:form_csrf }}