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
- Form Parameters
- Fields Tag Pair
- Showing Individual Fields
- Other Tags
- Form Assets
- Overriding Success/Failure Messages
- Using reCAPTCHA
- Email Notifications
- CSRF
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 }}
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. |
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 }}