Volunteer Sign Up Sheets Calendar Display

The Volunteer Sign Up Sheets Calendar Display generates a variety of calendar views for the Volunteer Sign Up Sheets plugin. This plugin requires the Volunteer Sign Up Sheets plugin.

This plugin creates a custom post type registered as “volunteer_calendar”, which will show up in your admin menu as “Calendars”. From the Calendars menu, you can add a new calendar, view & edit existing calendars, and set global options for all calendars.

You can have as many calendars as you need, each of which will be their own custom post with their own permalink. Each calendar can show All of your signup sheets, or you can specify one or more specific sheets to show on a specific calendar.

See the sections below for detailed description of all available options, as well as how to further customize the calendar display via templates and custom CSS.

Version 2.0 adds a week view to the calendar, as well as sortable color code groups that sheets can be assigned to.

Version 1.2 adds the ability to display a calendar on any page/post using a shortcode, as well as integration with the Groups extension.

Adding or Editing a Calendar

The main calendar add/edit page is where you define most of the options for a specific calendar.

You must give the calendar a title, which is also used to generate the permalink (if you are using pretty permalinks).

The regular content area allows you to add any specific information/content you want displayed on that calendar page. The content will appear above the calendar (in the default template layout).

The Calendar Settings meta box is where you define all the options for this specific calendar. Options are described below:

  • Default Calendar View – Choose whether the calendar should be shown with Month view or week view as the default view.
  • Hide the Month/Week View buttons – Check this if you do NOT want to show the Month and Week view buttons above the calendar on the public side (preventing the user from switching views).
  • Show which sheets? – This is a multi-select box that allows you to choose one or more specific signup sheets to show on the calendar. The default setting is “All”, which will show all active sheets.
  • Fixed Date – This is a month/year picker field that allows you to set a single month to show on the calendar. If this is set, the calendar will ONLY show that month, and will NOT have any navigation arrows for next/prev months. Default setting is blank, which allows your visitors to view any month, with the current month & year being displayed upon initial page load.
  • Show Sheet Title? – Checkbox to allow you to set whether or not the sheet/event title is shown above the task/item list for all days where that sheet has any tasks/items to display. If you are using a custom calendar for one specific sheet/event, you may wish to un-check this box to save some space and avoid repeating the title many times.
  • Show Sheet Details? – Checking this box will show the sheet/event details (the text area sheet description/content you entered in the main plugin when creating the sheet) within the calendar. When the box is checked, a few more options will appear:
    • Show Sheet Progress Bar? – Added in version 1.1, checking this box shows a progress bar right below the sheet details. It will calculate a progress percentage for ALL tasks/items for the sheet. The next few options only apply when this is checked.
    • Show Progress by Date – Check this to calculate the progress bar percentage by the date. When checked, the percentage shown is only calculated based on task/item spots for each specific date on the calendar. If left unchecked, the progress bar will show the total progress for ALL task/item spots for the sheet.
    • Progress Bar Shows – You can choose to show the percentage filled or the percentage remaining.
    • Progress Bar Text – Enter the text to show inside the progress bar. This text should be relatively short or else it will wrap below the progress bar when showing the details and progress within full month view (as opposed to inside a pop-up, or mobile view). Use curly brackets and the word progress where you want the progress percentage displayed, like this:  {progress}
    • Show Details with pop-up? – Check this to show the details in a pop-up window instead of trying to fit what could be a lot of content into a limited space on your calendar. The next two options only apply when this option is checked.
    • Text for pop-up details link – This allows you to specify the text used for the pop-up details link
    • Details title bar text – Allows you to specify the text that shows in the title bar of the pop-up details window.
  • Show View Sheet Link? – Checking this will show the “View & Signup” link (text for the link is defined in the main plugin, and can be filtered via custom PHP, or can be changed via the Customizer extension). This link will take the user back to the main plugin page to view that specific sheet. If you don’t want them to leave the calendar page, then you should probably keep this un-checked.
  • Show Pop-up Link? – If you check this, then, by default, only the sheet title will be shown in the calendar, and when that is clicked, a dialog box will open to show the details (all of the things you have chosen to show) for that specific sheet and specific date. Checking this reveals one more option, below:
    • Event title bar text – Allows you to define the text in the title bar for the event details pop-up box
  • Show Task Title? – This is checked by default to show the task/item title. If you have only one task/item for a sheet/event, or even a whole calendar, you could un-check this to hide the titles.
  • Show Task Times? – Check this to show task start and end times (only when they exist) on the calendar.
  • Show Task Signups Name List? – This will show the full list of signups for a task item. If you have the main plugin set to show signup names, then this will show the first name and last initial. If you don’t have it set to show names, then it will show “Filled” (the text can be filtered by custom PHP functions, or changed with the Customizer extension). If the volunteer is logged in to the same account they used when they signed up, then they will see their name for any tasks/items they signed up for, even if you have the main plugin set to hide names (all other volunteer signups will still show as “Filled”). Checking this option reveals one more setting:
    • Show Signup Clear Link? – Checking this will show a “Clear” link next to the signups, if certain conditions are met. Admin and signup sheet managers will always see clear links, so that they can clear any signup quickly from the calendar view. Volunteers must be logged into the same account they used to sign-up, and then they will see a clear link for their own signups (not for anyone else), but only if you have the main plugin set to allow clear links for that sheet, and they are not within the number of days you set to allow clearing. When a clear link is clicked, the signup will be cleared via an Ajax function, and a dialog box will pop-up letting them know it was a success, along with a “Close and Refresh” button that will refresh/update the calendar.
  • Show Task Signups Summary? – As in the main plugin, checking this will show a simple summary of signups, such as “1 Filled, 1 Remaining”. Unlike the main plugin, this option is not mutually exclusive with the above option, so you could show a list of signups as well as a signup summary (instead of one or the other).
  • Show Task Signup Link? – This will show a signup link for the task/item, but only if there are spots still available.
    • Admin Only Signups? — If checked, this will allow only Admin and Sign-Up Sheet Managers to signup through the calendar.
  • Show Signup Form in pop-up? – Checking this will open the sign-up form in a pop-up dialog box, allowing the user to signup via an Ajax function without leaving the calendar page. If this is NOT checked, then when they click on a signup link, it takes them to the signup form on the main plugin volunteer page.
  • Require Login to view? – You can check this to completely hide a calendar from the public, requiring volunteers to login before they can even see the calendar. This can be defined for each calendar, and will ignore the login setting of the main plugin. If this is NOT checked, then the following option appears
  • Require Login to signup? – If you are NOT requiring login to view (above option), then you can still require that volunteers login before they can signup. Again, this can be set on a per calendar basis, and will ignore the main plugin settings.

Global Options

General Settings

  • Starting weekday – Set the starting day for the weeks in your calendars.
  • jQuery UI Theme – Choose a jQuery UI theme stylesheet to load (loads from Google CDN). This applies to all the pop-up dialog boxes used by the calendars.
  • Mobile Breakpoint – Choose the screen width below which the calendar table will collapse to a single column view (only showing days with tasks/items).
  • Pop-up window width & height – These two settings let you set the height and width of the pop-up details boxes. These are the boxes that show all the details of a sheet/event for a day. Allows you to tailor the size of the dialog boxes based on how much info you are showing for each sheet & task.
  • Sign-up window width & height – These two settings allow you to set the size of the sign-up form dialog boxes separately from the event details boxes. The sign-up form boxes are also used to display the results when a user clears a signup.
  • Jump to first date for sheet view links? – When you have a sheet linked to a calendar, but you are still using the main plugin volunteer sheet list on a page, if you check this option, and a volunteer clicks on the “View & sign-up” link for a sheet, the calendar will open up to the month/year for the first date of that sheet IF the month/year is after the current month/year.
  • Only show active sheets? – When checked, only active sheets will be shown on calendars. Sheets whose last date has already passed will not be shown.

Messages & Text

  • Days of week – Allows you to specify exactly how you want the days of the week shown on your calendar (e.g., abbreviations instead of full names). Please note that you MUST start with Sunday in this setting, regardless of the starting day you selected in the general settings. You MUST also enter a comma between each day, and there MUST be 7 days in the list or you will get an error.
  • Months – As above, this field allows you to specify exactly how you want the months of the year displayed on your calendars. Again, they MUST be separated by commas, and there MUST be 12 of them.
  • Close button text – Allows you to specify the text for the “Close” button on any pop-up details boxes.
  • Cancel button text – Allows you to specify the “Cancel” button text for the sign-up form pop-up box.
  • Close and Refresh button text – This is the text on the “Close and Refresh” button that appears after a successful signup or clearing. The button must be clicked in order to force a refresh of the calendar.
  • Block UI Text – The text that appears when the user interface (UI) is blocked during AJAX requests (loading event data, getting signup form, processing signup or clear, refreshing calendar, etc.).

Color Groups

In this settings tab you can create, edit, and delete color groups. A color group can be used to display sheets with different colors on the calendar. You can define the background color, text color, and give each group an admin name for you to keep track of.  If you create more than one color group, you can drag and drop them to sort them in the order you want them to appear (top to bottom) on the calendar. Make sure to press the “SAVE ORDER” button after you sort the color groups to save the new order.

Main plugin additional Sheet options

  • View with Calendar: This new field for the add/edit sheet page in the main plugin allows you to select a specific calendar to view the sheet with. What that does is modify the “View & Signup” link in the main list of sign-up sheets (main plugin) so that when you click on it, that specific sheet will be opened in the calendar of your choice. By default the “No Calendar View” will be selected, which shows the sheet using the regular plugin view.
  • Calendar Color Group: This field allows you to select the color group you want to use to display the sheet on the calendar. Select “No Color Group” for the default colors. Note that if you have more than one sheet on a day, then the order they will be shown on the calendar is by the order of the color groups that you sorted and saved in the calendar Color Groups options page.

TEMPLATES & CUSTOM CSS

This plugin uses 3 custom template files, and 1 CSS file, to define the appearance and layout of the calendars. If you are happy with the way the calendars look by default, then you do not need to do anything, as the appropriate templates and CSS file are loaded directly from the plugin folders.

However, if you are comfortable with PHP and/or CSS, and you want to modify how the calendars look, then you may wish to modify some or all of these files.

The 3 PHP/HTML template files can be found in the “templates” folder of the plugin. If you wish to customize these, and you are confident enough with PHP not to break anything, you should NOT directly modify these files! Instead, COPY the files you wish to modify to a folder with name “pta-volunteer-calendar” in your theme’s folder. Ideally, you should be using a child theme, so that these files do not get overwritten or erased if you update the main theme.

My plugin will first look for the templates in that folder of the active theme, and use those first, if they exist. If any of them do not exist, it uses the templates from the plugin’s folder.

Similarly, the main CSS file for the public facing calendar can be found in the public/css folder of the plugin. Again, if you want to customize the CSS, simply COPY the CSS file to a “pta-volunteer-calendar” folder in your theme’s folder (same as for the templates).

Below is a description of each template file (each template also has some notes within it to help you):

single-volunteer_calendar.php

Since the volunteer calendars are a custom post type, a custom template has been created to display the calendar post type in WordPress. This is a fairly simple template file that sets up the required divs for the calendar (which is generated by javascript after the page loads). There are some “do_action” PHP function calls in there which also generate some hidden fields that the javascript needs to see in order to generate the calendar correctly, so you MUST not delete those!

sheet.php

This is the layout for an individual sheet/event on a single day. So, this template is loaded and parsed for every day that has active tasks/items in the current calendar. This template is VERY PHP heavy, and so it is NOT recommended that you modify it unless you really know what you are doing. HTML start/end comments have been placed around sections to let you know what each section is doing, and to allow you to cut and paste sections easily if you want to change the order in which things appear. Please read the notes in the template itself!

event-popup-link.php

This is a very simple template that generates the div and the link text for the pop-up details link when you choose to show event details in a pop-up (as opposed to listing them all out directly in each day of the calendar).

Displaying a calendar via a shortcode

Starting with version 1.2.0, you can now embed a calendar on any page via a shortcode. Use version 1.2.5 of the PTA Shortcodes plugin to help you generate the proper shortcode.  Or use the template below.  You MUST specify a calendar to display with the calendar argument. You can use either the numerical ID, or the title, of the calendar you want to display.  For example, if you created a calendar that you titled “Main Volunteer Calendar”, the shortcode should look like the following:

[pta-calendar calendar="Main Volunteer Calendar"]

If you are using the Groups extension, you can also specify which groups to show on the calendar with the “group” argument. See the Groups documentation for more info.

UPDATES AND NEW FEATURES

Version 2.0 add a “Week” view to the calendar. You can choose the default view, Month or Week, and also choose whether to show the buttons to change the view on the public side. In addition, you can now define color groups and sort them into any order that you want. A color group consists of a background color and a text color along with an admin name for you to keep track of. Once you have color groups created and sorted in the order that you want, you can select a color group for each sheet, and that sheet will be shown on the calendar with the colors of that color group, and if there is more than one sheet for that date, then they will be shown in the order of the color groups that you sorted.

Version 1.3 adds the ability to use “live search” on the pop-up signup forms so that admin and signup sheet managers can search for and signup other users/volunteers for tasks directly from the calendar. For this to work, the pop-up signup form function was changed and now gets the html output for the signup form directly from the main plugin (through an update in version 2.2 of the main plugin). This will also allow extensions that modify the sign-up for the main plugin to also work with the pop-up signup form on the calendar.

NOTE that the behavior of the “login to signup” options have become a bit more complex with version 1.3, now that the pop-up signup form is generated by the main plugin. If you have the “login to signup” option checked in the MAIN plugin, but NOT on a calendar, the signup link on the calendar will pop-up the signup form, but if the user is not logged in, the form will show the login to signup message generated by the main plugin instead of the signup fields. If however, that option is NOT checked in the main plugin, then you are able to independently set if the user needs to be logged in to signup from the calendar. If you check the “signup to login” option on the calendar, then they never see a signup link on the calendar, instead seeing the “login to signup” text and link. Note that both the main plugin and the calendar plugin have separate “login required” options. So, one possible combination is to have “login required” set on the main plugin (but NOT “login to signup” on main plugin), and then neither login option set on the calendar. In that case, a non-logged in user could view and sign-up for something through the calendar pop-up form, but could neither view or signup via the main plugin volunteer page.

Version 1.2 adds the ability to display a calendar on any page/post using a shortcode, as well as integration with the Groups extension.

Version 1.1 added a progress bar, which was a subsidized feature addition on request from a customer. 4 new options are added to each calendar to enable/disable the progress bar and set the options.  If you have previously copied template files to your theme for modification, you’ll want to copy the new sections for the progress bar.  The only two files modified are the sheet.php template, and the CSS file. The CSS is the one you will most likely want to modify the style the progress bar to your liking. The section for the progress bar was added at the end of the file.  The PHP code that generates the progress bar is labeled with start and end HTML comments, and is within the sheet details section.