Volunteer Sign Up Sheets Custom Fields documentation

• Create any number of custom fields, with most common field types: Text, Phone, Email, URL, Number, Checkbox, Select, Radio Buttons, Textarea, HTML, and Date.
• Fields can be used for Sheets, Task, and Signup Templates, in any combination
• Applying fields to a Sheet or Task allows you to display additional info in the Sheet and Tasks list tables, such as Location, for each Sheet or Task.
• You can create custom Signup Templates, and add as many custom fields to each template as you need.
• Signup Templates can be assigned at the Sheet or Task level. If you assign a template to a task, that template will override any template applied to the sheet for that task. Templates assigned to Sheets are used for all tasks on the sheet unless those tasks specifically have a different template assigned
• Signup Templates also have Layout Blocks (as of version 2.0.0) which allow you to add custom HTML at various positions on the signup form, including after any custom field you add to the template, for extra formatting or information you want to present on the associated signup forms
• When a volunteer signs up for a task where a Signup Template is assigned (either at task or sheet level), the custom fields, and layout blocks, added to that template will appear on the Signup form page.
• Fields added to a Signup Template can be optional defined as Required, Admin Only, and/or Public View. Required means that the volunteer must fill out that field when it appears on the signup form. Admin Only are for fields that can only be filled out by admin (either through the add/edit signup page on admin dashboard, or through the public side if you use live search to allow admin to signup for others). Public View determines if the custom field values should be shown in the public side list of signups when you are showing individual signups in the task list tables.
• Custom Fields will also show in the DataTables displays in the Admin Dashboard, and thus can be exported/printed along with all other data (if desired).
• Version 2.0 adds a new Hide From Public checkbox to the custom fields, allowing you to create fields that will only show to admin, and can be used to add additional info or notes that you may want to have in any reports you create.

This plugin lets you set up and define any number of custom fields for the Volunteer Sign Up Sheets plugin. The fields can be used for Sheets, Tasks, or Signup Templates. When used in sheets and/or tasks, those fields can be used by the admin, or signup sheet manager, to add additional info to sheets and/or tasks, that will be shown in the associated tables to the public. For example, you could add a field named “Location” and make it a select box field, and define all the locations you normally use for your sheets (events) or tasks. Then, if you assigned that field to be used on sheets, whenever you create or edit a sheet, you will see that dropdown select box with the locations you defined, and you can then select and save a location for that sheet (event). On the front end, in the main list of sheets, you would then see an additional column with “Location” as the heading, and the locations that you saved for each sheet in their respective rows.

To use Custom Fields to create additional form fields for signup forms, where volunteers can enter additional information when signing up, you create one, or more, Signup Templates. For each template, you can assign custom fields that you have created, and then decide if those fields should be Required when a volunteer signs up, or if they should be Admin Only fields, and if the info saved in those fields should be shown to the public on the list of signups. Admin Only fields can be used for things that you, or a signup sheet manager, might want to track for each user that signs up, such as number of hours that person worked, for example. Admin users can enter that info on the Add/Edit signup page for the admin dashboard, or they can use the public side “live search” feature that allows admin to search for and signup volunteers/users for a task.

Custom Fields fully integrates with the new DataTables display of signups in the admin dashboard, and thus can be exported or printed along with all the other data, if desired.

A new submenu page is added to the Sign-up Sheets menu called “Custom Fields”. This page is where you can add/edit/delete your custom fields, as well as enter your license key (for automatic updates and support).

Click on the Add New Field blue button at the top of the page. This brings up the form for defining your new custom field. The form has the following fields:

• Admin Name – Give your field a unique admin name to help you keep track of your fields. This will also be used as the “slug” for the field in the database, and the input name on form fields, so it must be unique.
• Field Label – This is the label shown next to, or above, the input field on any forms where the custom field is used. This field does not need to be unique.
• Field Type – Select one of the field types to use for the custom field. This determines the type of form field used in the associated form. If you choose “Select Box” or “Radio Buttons”, you enter the options with the below field
• Field Options – This field will appear if you choose “Select Box” or “Radio Buttons” as your field type. In this box you type in all the options for the custom field, separated by commas (no spaces after the commas). Type these in the way you want them displayed on the forms. For example, if entering some city names, you would type something like: Seattle,Chicago,New York,San Francisco,Dallas
• Field Description – This is an optional short description you can enter to help the user know what the field is for, or what type of info to enter (if it’s not clear from the Label)
• Field Placeholder – An optional placeholder value you can enter for fields that support placeholders. Good way to give the user an example of what you expect them to type in.
• Field RegEx Pattern – This can be useful for text style inputs to declare a pattern that the user’s input needs to match before they can submit the form. Be sure you know what you are doing before putting anything in this box! Search for HTML5 regex patterns for the type of data you want formatted a certain way to get examples online. Enter the RegEx pattern without any quotes at beginning and end. For example, the RegEx for a 5 or 9 digit U.S. zipcode pattern would be:  ^s*?d{5}(?:[-s]d{4})?s*?$
• Use on Sheets? – Check this box if you want this field to be shown on the admin side add/edit sheet page. For example, if you created a “Location” field as a “Select Box” with those cities I listed, then on the admin Add/Edit Sheet page, you would see a Location select box with those cities as options. You can then select one for your sheet, and then the location you selected would show up in a new “Location” column in the list of sheets on the public side.
• Use on Tasks? – The same as “Use on Sheets”, but this will add the field to your admin page where you add/edit tasks for a sheet. Each task will now have that field. Again, using the Location example, you would have a drop down select for Location on every task (so you could select a different location for each task), and a Location column will appear in the table for that task showing its location.
• Hide from Public? – This option was added in version 2.0.0 and is un-checked by default. Check this to hide this field from the public in all locations. This could be useful on Sheet and/or Task fields if the admin wants to add some special info for sheets and/or tasks that will only be visible to them and can also be shown in admin side reports (View Signups and View All Data). You could potentially also use it for signup template fields if the admin needs to sign people up themselves and wants to add extra information in fields that would never be available to the public.

The same Custom Field can be used for sheets, tasks, and Signup Templates, if that’s what you need. So, for example, you wouldn’t need to create 3 separate “Location” fields if you wanted to enter a Location for sheets and tasks, and also need a volunteer to enter a Location for something they sign up for. You would only need to create different “Location” fields if you needed a different label or description for each place you use them.

As described in the above section, when creating a custom field, there are check boxes you can check if you want to use the Custom Fields you created for sheets and tasks. Checking one or both of those boxes gives you fields on the add/edit sheet or task forms on the admin side.  The admin, or signup sheet manager, is the only one who can enter the info into that custom field when adding or editing sheets and/or tasks. Note, that the info is NOT required for each custom field you use on a sheet or task, so you can leave them blank, but the columns for that custom info will always get added to your sheet or task list tables. So, be careful not to get carried away with too many custom field that are assigned to sheets or tasks, or else those tables will get too wide to display easily on most screens! Also keep in mind that every sheet has a full editor where you can enter as much info as you want, so you should only use the custom fields for things that are important for a volunteer to see when viewing the table of all sheets (same thing with custom fields for tasks).For custom fields that you want to use to collect additional information from volunteers when they sign up for something, see the section below on Signup Templates.

On the Admin “All Sheets” list page, any Custom Fields you have assigned to Sheets will appear as additional columns, and you will also see a filter select box for each custom field which you can use to quickly filter the shown sheets by that field value.

Options for Custom Fields are shown on the main Custom Fields submenu page, under the table of Custom Fields.

• Show Custom Fields in Sheet title/header – Check this option to show Custom Field data for a sheet field in the sheet title/header area on an individual sheet page (will show above the description). This only applies to Custom Fields where you have selected “Use On Sheets” and you have actually saved some data for that field for the sheet being shown. If left unchecked, you will only see these custom sheet fields in a column in the main list of sheets, unless you use the Customizer Extension to create a custom sheet layout (where you can include custom fields as columns).

Below the Custom Fields submenu page, is a Signup Templates submenu page where you can create custom Signup Templates that can be assigned to sheets and tasks for collecting additional information for signups.

This page shows a list of any current templates you have created, with actions you can take, as well as a button to Add New Template.

The template list shows the name of the template, along with any notes you entered when you created it, the custom fields you have added to the template, and a column with icons for actions you can take.

From left to right, the Action column icons are: Edit Template, Edit Fields Layout, Copy Template, and Delete Template.

The Edit Template action just lets you edit the template definition (name and template notes). You use the Edit Fields Layout action to add custom fields to the template (see section below). Copy will copy a template and all fields to a new template.

From the list of templates, click on the second action icon (Edit Fields Layout) to go to the Template Fields page for that template. On that page, you’ll see a list of all custom fields not currently assigned to the template on the left, and any current template fields you have assigned on the right. Drag the fields you want to use on that template from the left to the right side. You can arrange the order that the fields will appear by dragging them into the position you want on the right side. If you need to remove a field, drag it outside of the box on the right side, and it will go back to the left side unused fields. Note that these fields will appear in the vertical order you have set, but below the default fields generated by the main plugin (you can’t remove those, other than what you can remove via the main plugin settings). Once the field is on the right, you’ll see the name of the field along with 4 check box options. These options are:

• Required? – Check this to make the form field required when a volunteer signs up for a sheet/task that uses this template.
• Admin Only? – Check this if you have some fields you want to add for individual signups, but you only want the admin, or signup sheet manager, to be able to enter the info for those fields for each signup. When this is checked, that field will NOT show up to volunteers on the public side signup form if they are not admin or signup sheet manager roles. Admin can see these fields when signing up volunteers on the public side, so they can fill out the info there. Admin can also see these fields on the admin side when using the Add/Edit signup feature of the main plugin.
• Public can View? – If this is checked, the info the volunteers enter for that field will be shown in a column on the list of signups for a task. Note that if you are using “Filled” instead of showing names for signups, AND you also have the main plugin set to consolidate the remaining slots, then the custom field column will NOT be shown. However, if you only have it set to show “Filled” instead of names, but are not consolidating the remaining slots, you will still see the column for the custom field in the signups table.
• User Meta? – If this is checked, the info the volunteer enters on the signup form will be stored in the user meta database table for the current user, only if the user is logged into a user account. On subsequent signups this field can then be pre-filled from the saved user meta (again, only if they are logged in).

In version 2.0, a new section has been added on the template fields layout page, below the area where you select/create template fields. Layout blocks are blocks of HTML that you can insert at various points on the signup form. You can use this for extra formatting, such as putting a divider between sections, or for additional information for sections. You can have as many layout blocks as you want. You give each layout block an admin name (for your own personal reference), and then can specify the position as well as enter the content you want to appear. After you have saved your template fields in the upper section, they will appear in the dropdown select for positions of the layout blocks. You can insert your layout block after any custom field, along with the following pre-defined positions (corresponding to hooks in the main/free plugin):

• Before form header – This position is at the very top of the signup form div, before the default “Sign Up” header
• Before form fields – This position is after the signup form header info, but before the default form fields (first name, last name, etc.)
• Before form details field – This position is after the default fields of first name, last name, email, and phone (if set to show), but before the details input if you have the “Details Needed” checkbox checked for that task. Even if you are not using details for a task, layout blocks set to this position will still be shown after the default fields
• After form details field – This is below the task details form field. Layout blocks assigned this position will also show whether or not the details input is shown. If there is no details input, layout blocks assigned this position will show in the same location as the above position, but after any layout blocks assigned to the above. This is also before any custom fields that you add.

Signup Templates can be assigned at the Sheet and/or Task level. When you add or edit a Sheet, you will see a Custom Fields section below the title and event type fields. Here you will see a dropdown select box where you can select a Signup Template to use for the sheet. Selecting a template here will apply that template to all tasks for that sheet, unless you specifically select a different Signup Template for a task on the add/edit tasks page. This way, if most of the tasks for a sheet should use the same Signup Template, you only have to set it once for a sheet, and then if you need to use a different Signup Template for any of the tasks, you only have to select the different Signup Template to assign to those specific tasks.

When adding/editing tasks, the Signup Template select box will be shown after the end time. Leave it set to the default “Use Sheet Template” if that task should use the same Signup Template you set on the add/edit sheet page. If you need a different template than what was assigned for the sheet, or if you did not set a template for the sheet (such as each task needing a very specific template), just select the Signup Template for the task and save your tasks.

When a volunteer signs up for a task, the signup form will contain any additional custom fields assigned for the task or sheet, which will be shown after the default signup form fields set by the main plugin. Note that any fields you set as Admin Only will not show to any users who aren’t signed in to an admin, or signup sheet manager, account. The info entered for custom fields is saved in a separate database table and linked to a specific signup by the database ID of the signup (main plugin’s signup database table).

Any fields that you add to a Signup Template, and check the box for “Public can View?” will be shown in the list of tasks and signups on the public side, as long as you are showing signups individually (not hiding names and consolidating remaining). Certain field types will be formatted with clickable links, such as URL, email, and phone. Also, if the field type is Date, then there will be a pop-up datepicker on the signup form for that date field. Other field types will be used as input types on the signup form for HTML5 capable browsers, to help guide the user to enter field values correctly for the input types that offer some form of format validation (number type inputs will only allow numbers, for example). Any fields you mark as Required in the Signup Template will have the required attribute set on the signup form, and HTML5 browsers will not let the user submit the form if any required fields are blank. For browsers that don’t support HTML5, the form values will still be validated when the form is submitted, and the signup will not be processed if there are missing or invalid field inputs.

You can use template tags for custom fields in the email templates to show the corresponding values in the email body or email subject. To create a template tag for a custom field, the first part of the tag text should indicate if it’s for a sheet, a task, or a signup, followed by an underscore. The second part of the text should be the slug version of the custom field (shown in the list of custom fields in the admin dashboard), and the whole thing should be surrounded by curly braces.For example, if you created a custom field called Location to show the location of a sheet/event, then the slug of the field will simply be “location” (slugs are only lowercase characters and underscores or dashes). Since you want to show the location of the sheet, you need to prefix that with “sheet_”. So, that makes the template tag: {sheet_location}

Another example would be maybe you have someone enter their birthday on a signup form, using a custom field you called “Birthday”, and you want to show what they entered on the emails sent to them. Since the birthday is a signup field, the template tag would be: {signup_birthday}