The "Add New Submission Form" and "Edit Submission Form" screens consist of a large form with all the settings you need to create a submission form, or edit an existing submission form, respectively.
The Add New screen can be reached in one of two ways:
- In the top toolbar, go to Create > Submission Form
- Go to Creator > Submission Forms, then click “Add New”
The Edit screen can be reached by going to Creator > Queries, and then clicking on the name of the submission form you wish to edit.
Name
At the top of the screen is a large box where you can enter a name for your submission form. This should be a brief descriptive name, such as "Contact Form", "Resume Submission Tool", or "User Review Form". This name will not appear publicly on your site.
The Form Tab
Save Submissions As
The first thing to do after adding a name for your submission form is to specify which content type to save entries as. You can do that by selecting a content type from the dropdown menu here.
Form Fields
This works very similarly to the field-building tool at Creator > Fields, with one major addition: the "Field" column at the beginning of each row.
In the Field column, you can choose which information to map the form field to. You choose from all of the content type's custom fields, taxonomies, connection types, and general information.
Once you choose a field, the rest of the information in the row will be filled in automatically, based on how you originally set up the field. If needed, you can then modify the field label or any other options.
(If you don't choose an existing field, you can fill in the other information normally; this field will be saved as post meta, with the field's system name as the post meta key.)
The Options Column
The options column includes additional options for each field beyond the label and field type. Most of these are identical to the options found at Creator > Fields, with a few additional options that are specific to submission forms. We will go over those options here:
Hidden Field
Check this box to set this field as a hidden field. A hidden field means that the user will not see it. It allows you to add information that is needed, but is not meant to be user-editable.
Once you check the box, a few other options will appear:
Value is where you can set the value of the hidden field. You can add any text here, with the addition of two placeholders:
- [user] will be replaced by the ID of user submitting this form entry (or "0" for a logged-out user)
- [now] will be replaced by a timestamp (in YYYY-MM-DD HH:MM:SS format) of when the form was submitted.
For a common usage of this, see Change the Status of Submission Form Entries.
Dynamic Value Type allows you to set the value according to GET or POST data on the page containing the form that match's the field's system name. It is for advanced users. If GET or POST is selected, the Value field above can remain blank.
Required
Check this box to set this field as required. A red asterisk will appear after the field label. A user will not be able to successfully submit the form until they have added information in this field.
Unique
Check this box to set this field as unique. A unique field means that every submission entry must contain a different value for this field.
For example, if you want to discourage people from submitting this form more than once, you can create an Email Address field and set it as unique. A user will not be able to successfully submit the form until they specify an email address that does not match any existing email address in any other entry.
The Permissions & Editing Tab
Permissions
Here you can control which user roles can view the form, add new entries, edit existing entries, and delete existing entries.
In the dropdown on the left, select a user type -- "Anyone", "Logged-In Users", or a specific user role. Selecting an option will reveal additional options:
View form - click this checkbox to allow this user role to view the form.
Submit new entries - click this checkbox to allow this user role to submit new entries with the form.
Edit entries - click this checkbox to allow this user role to edit existing entries in this form's chosen content type.
Delete entries - click this checkbox to allow this user role to delete existing entries in this form's chosen content type.
But wait: we usually won't want users to be able to edit or delete *all* entries in the form's content type (though it's handy for administrators). That's why another clarifying option appears when you check either "Edit entries" or "Delete entries", labeled "if user is connected as...".
Click inside this box to select conditions that, if met, will allow the user to edit/delete specific entries. The options include:
- Post Author - the user that WordPress set as the author of this entry. By default, if a user submits a new entry in a submission form, they will be set as the post author, so selecting this will allow users to only edit/delete entries that they themselves have previously submitted. (If someone who's not logged in submits an entry on a submission form, the site administrator will be set as the post author.)
- Any connection type that connects users to the submission form's content type. In other words, this would allow users to edit/delete entries only if they are connected to those entries via this connection type.
If no option is selected, "No condition, can edit/delete all" will display, and the user role will be able to edit or delete all entries.
Click "Add Permission" to add permissions for another user role, or click the trash icon to the left an existing row to remove it.
Entries
This section contains options that are only relevant if any users are allowed to edit or delete entries via this submission form.
Entries to Display
When users are allowed to edit or delete entries, then when they view the form, they first see a list of entries that are available for them to edit or delete.
By default, they will see a simple table listing the title of each entry. The user can click on the title to edit the entry, or click on a "delete" link to delete it (if allowed).
However, you can replace this default display with your own list of entries by selecting a query from the dropdown menu here (if SmartSimian Queries and Templates are activated on your site).
Note that the Template that the selected Query uses will need to display "Edit Link" or "Delete Link" somewhere so that users will be able to click through to edit or delete the entry. These options will appear in the template builder whenever Templates and Submissions are both activated.
Filter Entries
Some queries are set to display many or all of a content type's entries. If you want the user to see only the entries they'll be able to click through to edit or delete, check this box. If you want the users to be able to see all the entries that the query is normally set to show, uncheck this box.
The Advanced Tab
Form Settings
Display entry title above form
When editing an existing entry, check this box to display the entry title above the form. (Turned on by default.)
Hide form after submission
Check this box to hide the form after a user submits the form; only the "successfully submitted" message will be displayed. (Turned on by default.)
Before Form
Generic text or HTML to include above the form. If SmartSimian Templates is installed, then you can select a template here to display various information about the current entry (only works for entries that already exist and are being edited).
After Form
Generic text or HTML to include below the form. If SmartSimian Templates is installed, then you can select a template here to display various information about the current entry (only works for entries that already exist and are being edited).
Labels & Messages
Below the Form Settings section are a few sections in which you can edit the text (and in some cases, the HTML) of various labels used when displaying submission forms, such as the success message.
Sidebar
The following basic options appear in the right-hand sidebar:
Description
The description is only displayed within the WordPress admin area. It is an optional field, but can be helpful if you have multiple submission forms that use similar names, or even just for leaving a note for yourself, other developers, or even the client about the purpose of that submission form.
System Name
The system name, also referred to as the slug, is the lowercase "URL friendly" version of the name of the submission form. If left blank, it is generated automatically, and will contain only lowercase characters and underscores. You can choose an alternate system name if you like, but it cannot be modified again once the new submission form has been saved.
Shortcode
After saving a submission form, the shortcode will appear underneath the system name, and will be based on the system name. It is not editable. You can paste this shortcode into any page or template, and it will be replaced with the full submission form.
Delete/Save
Click the small red “Delete” link to delete the current submission form, or the large blue “Save” button to save or update the submission form.
Note: unlike WordPress’s content types, there is no “trash” for deleted submission forms. When you click delete, you will be asked if you are sure. Immediately after deleting, there will be a link to undo the deletion. After these two chances, however, the submission form will be deleted permanently.