[upcoming_list]

Introduction

The [upcoming_list] shortcode can be used to display a list of upcoming anniversaries, birthdays, or other date events added to an entry.

Tip

Click here to learn shortcode basics.

Shortcode Options

By default, if no option is used, the shortcode displays a list of birthdays occurring over the next 30 days. This list displays the name, minus the last name, followed by the date.

The shortcode has the following available options:

  1. template
  2. list_type
  3. days
  4. include_today
  5. show_title
  6. list_title
  7. name_format
  8. show_lastname
  9. year_type
  10. date_format
  11. year_format
  12. no_results

Tip

You do not need to add the shortcode option to the shortcode if you wish to use the default value.

template

The default value for the template option is anniversary-light. This is a great option for sites with a light/white background. To accommodate sites with a black/dark background the template option can be set to anniversary-dark.

Default Value:

  • birthday-light

Valid Values:

  • anniversary-light
  • anniversary-dark

Example:

/*
 * Example 1 
 */
[upcoming_list template='anniversary-dark']

list_type

The list_type option allows you to change the listed upcoming dates from anniversaries, birthdays or other registered date events.

Default Value:

  • birthday

Valid Values:

Any of the enabled Date Types found on the Connections : Settings admin page under the Fieldset Configuration tab in the Date Fieldset section.

Use the date name, but in all lowercase, and substitute underscores for spaces.  For example Anniversary will become anniversary or Graduate College will become graduate_college.

Examples:

/*
 * Example 1
 */
[upcoming_list list_type='anniversary']

/*
 * Example 2
 */
[upcoming_list list_type='birthday']

/*
 * Example 2
 */
[upcoming_list list_type='graduate_college']

days

The days option tells the shortcode how many days to look ahead for upcoming date events.

Default Value:

  • 30

Valid Values:

  • Any number between 0 and 365

Example:

/*
 * Example 1
 * Display birthdays occuring in the next 90 days.
 */
[upcoming_list days='90']

include_today

By default, the upcoming list displays event dates occurring today. Using this option, you can exclude event dates occurring today.

Default Value:

  • true

Valid Values:

  • false
  • true

Examples:

/*
 * Example 1
 * Exclude event dates occuring today.
 */
[upcoming_list include_today=false]

show_title

The upcoming list will automatically have a heading added. This option can be used to disable this heading.

Default Value:

  • true

Valid Values:

  • false
  • true

Examples:

/*
 * Example 1
 * Do not display the list heading.
 */
[upcoming_list show_title=false]

list_title

This list_title option allows you to define a custom list heading.

Default Value:

  • Upcoming Birthdays for the next 30 days

Valid Value:

  • Any text, no HTML.

Examples:

/*
 * Example 1
 */
[upcoming_list list_title='Upcoming Membership Expirations']

name_format

The name shown will be the full name of the entry including the prefix, middle name and suffix. This can be configured by using the name_format shortcode option.The name_format option accepts only a few specific tokens. A token is a word wrapped with the % symbol, for example, %token% is a token.

Default Value:

  • %prefix% %first% %middle% %last% %suffix%

Valid Value:

  • %prefix%
  • %first%
  • %middle%
  • %last%
  • %suffix%

Examples:

/*
 * Example 1
 * Display the first and last name. `show_lastname` must be set to `true`.
 */
[upcoming_list name_format='%first% %last%']

show_lastname

By default, the last name of the entry will not be displayed, even when configured to display when using the name_format shortcode option. This is so the list can be publicly displayed without revealing to the world at large the full name of the entry.

Default Value:

  • false

Valid Value:

  • false
  • true

Examples:

/*
 * Example 1
 * Display the last name.
 */
[upcoming_list show_lastname=true]

year_type

This option allows you to configure whether to display the original year, the upcoming year,  or the number of years since an anniversary.

Important

For the year to display, you must use the date_format option and configure it to display the year.

Default Value:

  • upcoming

Valid Value:

  • original :: Display the year as entered.
  • since:: Display the number of years since the date entered.
  • upcoming :: The current year or next year based on the current (today’s) date. The displayed year will be the current year or next year if the month/day has already passed in the current year. For example March 21, 2018 will be displayed if the current date (today) is before March 21st and the displayed year will be March 21, 2019 if the current date (today) is after March 21st.

Examples:

/*
 * Example 1:
 * Display the year as entered.
 */
[upcoming_list year_type=original]

/*
 * Example 2:
 * Display the number of years since the date entered.
 */
[upcoming_list year_type=since]

/*
 * Example 3:
 * Display the current or next year based on today's date.
 */
[upcoming_list year_type=original]

date_format

This option can be used to configure the date format.

Default Value:

  • F jS:: This will display the date in this format, Month 1st

Valid Value:

Examples:

/*
 * Example 1:
 * Display the date with year. Month 1st 2018 
 */
[upcoming_list date_format='F jS Y']

year_format

This option, when the year_type option is set to since, will allow you to configure the time since the date entered.

Default Value:

  • %y Year(s)

Valid Value:

Examples:

/* 
 * Example 1: 
 * Display the number of years, months and days since the date entered. 
 */
[upcoming_list year_format='%Y %M %D']

no_results

Use this option to configure the message displayed when there are no upcoming date events.

Default Value:

  • No results.

Valid Value:

  • Any text. No HTML is permitted.

Examples:

/*
 * Example 1: 
 */ 
[upcoming_list no_results='No Upcoming Membership Expirations']