Volunteer Sign Up Sheets Customizer documentation

The Volunteer Sign Up Sheets Customizer plugin is an extension for the free Volunteer Sign Up Sheets plugin, that allows you to modify most of the public side text that the main plugin generates, as well as easily changing styles for the sheet and task/signups list tables, and error/success messages.

GENERAL INFO

Features

  • Modify or Disable all the Public Text strings output by the main plugin.
  • Table header text that you modify can also be applied to the admin side lists of signups, so your custom text can be used in exporting or printing
  • Choose from Default, Compact, or Custom layout styles for public side list tables
  • For Custom layouts, you can specify a large number of display options (font sizes, colors, padding, etc.) for various types of table rows and header info shown on the public side
  • Layout Templates can be created and assigned on a per sheet basis, allowing you to choose which columns to show, reorder columns, how to display the tables (default, one table per date, or all in one table), whether to use DataTables for display, and columns to “Group” into rows when using DataTables.
  • Customize the text and buttons used by DataTables for public side tables.
  • Create custom email templates that can be used for any email type (confirmation, reminder, reschedule, clear) and assigned on a per sheet basis. Can use all the standard email template tags, plus template tags for Custom Fields.

Overview

This plugin lets you easily modify, or even disable, most of the public side text that the main plugin generates, without having to setup custom translation files or using PHP code snippets. Version 2 adds layout options with default, compact, and custom layout styles. Default doesn’t change anything (uses styles from main plugin, or your own manual styles if you disable the main plugin’s CSS). Compact makes the font size and cell padding smaller on the public side list tables to allow you to fit more columns/info in one row (especially helpful for themes with large default font sizes). Custom allows you to specify your own parameters for font size, cell padding, border size and color, filled row background color, as well as background & text colors for error and success messages. The Custom Styles work with either the original Table layout view, or the newer table styled Divs layout.

Version 3 adds Layout Templates that you can assign on a per sheet basis to determine what columns should be shown, the order of the columns, change column headers, and also pick between 3 different table display styles in addition to whether or not to use DataTables to display the table. It also add many more appearance controls to the custom styles section introduced in version 2.

Version 3.2 adds Custom Emails. You can create custom email templates that can be used for any email type (confirmation, reminder, reschedule, clear) and assigned on a per sheet basis. Can use all the standard email template tags, plus template tags for Custom Fields.

CUSTOMIZER SETTINGS

Customizer Page

A new submenu page is added to the Sign-up Sheets menu called “Customizer”. This page is where you will find all the settings for the Customizer. The page is split into 3 tabs:

  • Public Text – This section is where you can modify, or disable, just about any public side text generated by the main plugin
  • Settings – This section has general options, as well as the Layout Settings
  • Layout Templates – This section lets you define as many layout templates as you need, which can then be assigned to sheets on a per sheet basis.
  • DataTables Settings – This sections lets you edit the text that the jQuery DataTables plugin uses for table view controls, as well as enable/disable buttons for DataTables.
  • License – This section contains the license form to activate your license for the plugin.

Changing or Disabling Public Text

In the public text section, you will see a long list table of all the public side text you can modify.

The first column shows the “Filter ID” tag (used in the WordPress PHP filter hook), which is unique for each text string output on the public side.

The second column shows the “Screen” where that text appears, which can include: “Main Sheets List”, “Sheet Details”, “Sign Up Form”, and “Multiple” (for text that appears in more than one “Screen” location).

The third column contains a text input box, which is blank by default. Underneath each text input is a longer description of where the text appears, as well as the Default value that the plugin outputs. If you want to change the text shown on the public side, enter the text you want shown in the text input for that text string, and then scroll to the bottom of the table and hit “Submit”.

The fourth column is a Check Box input that you can use to disable the output of that text. Since an empty value in the text input will result in the default text being shown, you check the check box if you do not want anything to show for that particular text string.

The last column shows any Variables used within the text string, such as the number of remaining slots for a task. It’s empty for most text strings that don’t show any variable values. For those that do have a variable, you use XXXX as a placeholder in your custom text to indicate where you want that variable’s value shown. For example for the text that shows the number of slots remaining for a task (when consolidating open slots), the default value is: XXXX Remaining. But, you could change it to something like: Only XXXX positions left!

Settings Tab and Layout/Style Settings

As of right now, there is only one “Setting” on this page: Modify Admin Table Headers?  Checking the box for this setting will modify the text on the Admin side for any signups table headers you changed in the Public Text settings, such as Start Time and End Time for start and end time headers. You may want these to be changed when you are going to export or print out the list of signups using those features of the DataTables display added in version 3 of the main plugin.

Below that single setting checkbox, there will be a select box for Layout Style. If you leave this set to default, the main plugin’s CSS file will be used for the public side table lists, if you haven’t already disabled CSS in the main plugin and replaced it with your own. The second option is “Compact”, which uses the same default CSS as the main plugin, but makes the font size “smaller” and decreases the cell padding amount for the table cells and divs. This allows you to squeeze additional columns into your limited screen space, especially if additional columns are being added to the public display via the Custom Fields or Groups plugin.

The third layout option is “Custom”. If you select that, you’ll see additional fields revealed that allow you to set various properties and colors for the public side display, which should all be self-explanatory. Note that these layout options will apply to both the original table html layout, as well as the newer divs layout, of the main plugin.

In addition, if you have NOT disabled the main plugin’s CSS, you will see a notice about that above the select box. It is highly recommended that you disable the main plugin’s CSS file if you are going to use either the “Compact” or “Custom” layout options offered by the Customizer… this will avoid conflicts and redundant CSS.

Layout Templates

This tab lets you add/edit/delete custom Layout Templates which can then be assigned to sheets on a per sheet basis (you’ll see a dropdown select box with your template names on the add/edit sheet page).

When you add a new template, you need to give it a unique admin name (this is what you will see in the select box on the add/edit sheet pages), then choose one of the table styles. The “Default” style is the one table per task display introduced with version 3 of the main plugin. “Separate Table per Date” will create a new table for each date, with the date above the table, and the table will contain all tasks/signups for that date (this is similar to the original table display before version 3 of the main plugin). “Single Table” puts everything in one big table, which may be the best choice when using the DataTables option, especially when using the row grouping feature.

You can then check the check box if you wish to display the table using the jQuery DataTables plugin (which was added to version 3 of the main plugin for admin display of signups). This will create a simplified DataTables implementation for the task/signup table on the front end, and gives you the opportunity to use row grouping.

Below that, you will see a table of all available columns that could be shown on the tasks/signups table. This will include and custom fields you have created with the Custom Fields extension. Check the check box next to each column you wish to show. You can also change the text that appears for the column header for that template (saved individually per layout template). You can drag and drop the rows in this table to re-arrange the order in which they will appear in the tasks/signup table. Top to bottom ordering on the settings page equates to left to right column order.

If you have your layout set to use DataTables, then you can check the check boxes for any columns you want to “Group” into DataTables row groups. What this will do is organize the table to display entries in “groups” that have the same value for the checked column, and will insert a table spanning row with that value above the group (which can be styled differently). This can extend multiple levels, although I don’t recommend going past 4 levels (and the DataTables Settings page only allows you to specify styling for 4 levels).

As an example of row grouping, let’s say that you are showing the Date, Task Title, and Task Description columns, in that order, along with the “normal” columns for signups/available spots, clear link, and maybe start and stop times. If you check the Group check box for those first 3 columns (date, task title, and description), then all the data will be organized into groups of rows that have the same values, and showing those values via a table-spanning group row header. Easier to see than to explain. The image below shows the first two tasks of a test sheet. Both tasks are on the same date, so the Date row header is only shown once. Then you see the task title (task 1 and task 2), and the task descriptions, all in their own rows, followed by signups and remaining/open slots for each task. Descriptions can contain HTML, as shown in the task 2 description, so that grouped row could get big if you have a big description, but it’s much better to display it this way than to try to show the description in a column (which would get repeated for every row of the table for that task). The group rows in this example have been styled to make them stand out more (you can define the styling at the bottom of the Custom Layout section of the Settings tab on the Customizer page).

Row Grouping Example
3 level Row Grouping example
Click to view full size

Note that if you choose to show the Column Visibility button for your users, the columns that have been grouped will show up in the list of columns to show/hide when they click that button (they will initially be set to hidden status since they are being used for groups).

DataTables Settings

In this tab you can change the text that DataTables uses to display info and for various controls, as well as enable/disable the 3 default control buttons.Many of the text strings include variables in the format that DataTables uses. Anything in all caps, and surrounded by underscores, such as _START_ , is a variable and needs to be in your text string if you want the corresponding value to show.

Below the table where you can define the text strings, are 3 check boxes for the buttons you can show at the top of the DataTables table, which allow the viewer to have limited control over what they can view. These buttons are as follows:

  • Column Visibility Button – When this button is clicked, it will display a vertical list of all columns in the table, and the user can click to toggle the visibility of that column. By default, any columns that you had set to be Group columns (when using a custom layout template) will be hidden and shown as group rows instead. If you enable this button, the user could use this button to turn those hidden columns back on (which would be redundant, unless you also allow them to disable grouping with another button)
  • Hide Signups Button – This is a custom, one time use button, that will remove all filled signup rows from the table, leaving only the open/available rows. Possibly useful if your tasks needs a LOT of signups and people don’t want to scroll way down the page to find the open slot to click to signup. Once the signup rows are removed, they can’t be shown again without reloading/refreshing the page.
  • Disable Grouping Button – This is also a custom, one time use button, that will remove the grouped header rows, if you are using them for the layout template. Once those group rows are removed, they can’t be shown again without reloading/refreshing the page. However, if you enable the column visibility button, they can always make those columns visible using that button (they will be put into columns, though – that does not turn on the group rows again).
  • Show the Print button – Shows the button to allow printing of the table
  • Show the PDF button – Show the button to allow exporting the table to a PDF file
  • Show the CSV button – Show the button to allow exporting the table to a CSV file

Custom Emails

In this tab you can create and edit custom email templates (subject and message body) that can then be assigned to any of the 4 email types (confirmation, reminder, reschedule, clear) on a per sheet basis.

Click on the “Add New Custom Email” button , or click on edit for an existing custom email, to open the form for the custom email. Give it a name that allows you to remember what the email is for. Enter a subject and a message body, and save. You can use any of the email template tags from the main plugin (you can find those under the Settings sub-menu of the main plugin, in the Email Settings tab). Template tags for Custom Fields can also be used (see the Email Template Tags section of the documentation for the Custom Fields extension).

Once you have one or more custom emails defined, you can select them on the admin add/edit sheet page. You will see a new “Customizer Email Options” section right under the “Customizer Layout Options” section on the admin add/edit sheet page. There will be four select boxes, one for each type of email. If you want to use the regular email templates set in the main plugin settings, just leave these set to “Default”. To assign a custom email for any of the 4 types of emails, just select the name of the custom email to use, and then save the sheet. The same email can be used for more than one email type, and for as many sheets as desired.

License

The final tab of the Customizer admin page has a simple form for entering your license key and activating your license. Although the plugin will operate just fine without the license being activated, you need an active license in order to do automatic updates of the plugin, as well as to receive support.