Simple:Press Documentation

Plugin: Birthdays

Plugin Description

Plugin: Birthday – The Simple:Press plugin allows users to enter their birthday in their profile then display on the forum page which users have a birthday today and which have upcoming birthdays.

WARNING: In standard supplied Simple:Press themes the Birthday notice is contained in the ‘Stats’ section of the forum page footer. The Birthday notices will not be displayed if the ‘Stats’ section has been removed or commented out. It is strongly recommended that standard supplied Simple:Press themes not be modified, but instead a Child Theme or Custom Theme be developed to accommodate the changes to the theme.

Plugin Features

Installing this Simple:Press plugin adds:

  • A new “Birthdays” section in the “Available Plugins – Install Simple:Press Plugins” panel under the forum Admin menu path Forum > Plugins > Available Plugins. From this panel the plugin can be activated, or deleted by the admin.
  • When properly installed, a new folder in the “forum-plugin” folder named “birthdays” containing the plugin’s files.

Activating this plugin provides:

    • A change to the new “Birthdays” section in the “Available Plugins – Install Simple:Press Plugins” panel under the Admin menu path Forum > Plugins > Available Plugins so the Simple:Press plugin can be deactivated, uninstalled, or have its Options set up.
      • The Options link goes to the existing “Options – General Display Settings” forum Admin panel with a new “Birthdays Window” section.
      • The “Getting Started” link associated with the “Deactivate/Uninstall/Options” selections should be selected to view the pertinent information regarding the plugin.
    • A new “Birthdays Window” section in the existing “Options – General Display Settings” forum Admin panel where the size (in days) of the look ahead window for selecting the users whose name will be displayed with upcoming birthdays.
      • The current default is 7 days.
      • The “Help” link should be used for assistance in setting up the options.
      • The “Options – General Display Settings” forum Admin panel can also be accessed under the Admin menu path Forum > Options > General Display Settings.
    • A new “Birthday:” input text box in users’ profile where the users can input their birth date in the “YYYY-MM-DD” format if they wish to have their birthday displayed in the forum.
      • The “Birthday:” input text box is access from the forum page header by clicking the “Profile” button, followed by clicking the “Profile” tab from among the tabs, then clicking the “Edit Profile” tab.
    • A new Birthdays display in the forum page footer containing the “birthday cake icon” and the names of users with birthdays today and in the near future as selected by the forum admin in the “Birthdays Window” section of the “Options – General Display Setting” forum Admin panel.
Note:
A user’s birth year is not displayed.
    • Users whose birthdays are today have their names displayed after “Today” in the Birthday section of the forum page footer.
    • Users whose birthdays are within the specified look-ahead window have their names displayed after “Upcoming” in the Birthday section of the forum page footer.
  • A new “sph_birthdays_cron” that runs on the schedule set up by the forum Admin to check for users whose birthdays are within the birthday display parameters for display of the users’ name.
    • The “sph_birthdays_cron” can be accessed under the Admin menu path Forum > Toolbox > Cron Inspector.

There are no new permissions added to the permission sets due to this plugin that must be set up.

If the WordPress “MyCred” plugin and the Simple:Press “MyCred Integration” plugin are installed, users can be credited for their birthday partipation.

Plugin Requirements

This plugin requires Simple:Press version 5.5.7 and above.

This plugin must be installed, activated, and its options set before it is operational.

As part of the installation, a “Birthdays” section is added to the Plugin Management panel under the admin menu Forum > Plugins > Available Plugins. From this panel the plugin can be activated, deactivated, uninstalled, deleted, or its options set using its “Activate/Delete” and “Deactivate/Uninstall/Options” selections.

  • The Options link goes to the existing “Options – General Display Settings” forum Admin panel where this plugin’s “Birthday Window” option is set by the forum Admin.

Users wishing to have their birthdays displayed in the forum footer must fill out the “Birthday” field in their profile.

There are no new permissions added to the permission sets due to this plugin that must be set up.

The plugin has one (1) template tag ‘sp_ListBirthdays()’ incorporated into standard supplied Simple:Press themes.

  • If the location of the template tag in the themes as well as the argument and parameter values for the template tag are acceptable, nothing need be done.
  • If any item relating to the template tag is to be modified or if the other template tags are to be added to a theme, it is recommended that a Child or Custom theme is created first to accept the changes prior to installing this plugin.
  • In all cases the template tag should be called conditionally, if (function_exists(‘ ‘)) so that if the plugin is deactivated or does not exist, the website will continue to operate.

Plugin Installation and Activation

Please see Using Plugins how to obtain and install this Simple:Press plugin.

  • Whatever method is used to add the Simple:Press plugin, the folder that should have been added to the forum plugin folder is named “birthdays“.
  • If using the “Simple:Press Upload Plugin – Upload a Simple:Press Plugin” panel at the forum Admin menu Forum > Plugins > Plugin Uploader, the folder to browse for after downloading it from the Simple:Press site is “birthdays.zip” before clicking the “Upload Now” button.

As mentioned there the default location for Simple:Press plugin folders is …/wp-content/sp-resources/forum-plugins. If this path is changed, it is important to note that the plugin’s folder and its content need to reside in the forum plugins folder wherever it has been moved and however it has been renamed. See Storage Locations for more information.

Activation is accomplished from the Admin Dashboard panel menu by selecting Forum > Plugins > Available Plugins from the drop down forum Admin menu. On the “Available Plugins – Install Simple:Press Plugins” panel select the “Birthdays” plugin and click on “Activate”. The “Activate/Delete” label changes to “Deactivate/Uninstall/Options” with a “Get Started” Link.

  • The “Getting Started” link associated with the “Deactivate/Uninstall/Options” selections should be selected to view the pertinent information regarding the plugin.

To deactivate the plugin, click on “Deactivate”. The “Deactivate/Uninstall/Options” label changes to “Activate/Delete”.
To re-activated the plugin, click on on “Activate”. The “Activate/Delete” label changes to “Deactivate/Uninstall/Options”.

 

Plugin Administrative Options

After activation, a) on the aforementioned “Available Plugins – Install Simple:Press Plugins” panel, click “Options” on the Birthdays plugin section or b) under the Options entry on the forum menu on the left side forum admin page click the General Display Settings sub-menu item to get the “Options – General Display Settings” Admin panel.

  • Specifying Birthday Window Option
    • Go to the “Birthday Window” section of the Admin panel.
      • Please click on the section’s “Help” link for more information.
    • In the text input box to the right of “Number of days to show upcoming Birthdays:” put in the number of days in advance of a user’s birthday to begin displaying that they have an upcoming birthday.
    • If there are no more options to set on the page, click on the “Update Display Options” button at the bottom of the panel to save the settings. Otherwise proceed to the next section, if there is one.

The CRON Inspector under the forum menu Toolbox entry is a time based job scheduler used to determine when to check for today’s and upcoming birthdays.

  • Verifying when birthdays are checked by the CRON Inspector
    • From the admin menu click on “FORUM”.
    • From the forum menu click on “Toolbox”.
    • From the Toolbox sub-menu, click on “CRON Inspector” to see the panel with the “Toolbox – CRON Inspector” section and the “Toolbox – CRON Update” section.
    • Under the “Toolbox – CRON Inspector” section, the “CRON Schedules” subsection shows the name, descriptions, and interval (in seconds) for the various selections available for checking events. The “Active CRON” subsection lists the specifics for the active checks currently being done.
      • In the “Active CRON” subsection, under “HOOK”, find ‘sph_birthdays_cron’ to verify when the next birthdays check will be done, what the timestamp will be at the next run, the schedule (or frequency) the check is run, and any arguments.
    • Under the “Toolbox – CRON Update” section, the “Delete CRON “subsection can be used to remove an existing CRON, the “Add CRON” subsection can be used to add a new CRON, and the “Run CRON” subsection can be used to cause an existing CRON to run once.

To be complete for multilingual forums, the language translation files for this plugin should be installed or downloaded/properly placed in the appropriate forum-language folder for SP plugins using one of the procedures below in the “Plugin Language Translation” section of this page.

 

Plugin Language Translation

A plugin may not have language translation files, but in general each Simple:Press plugin has its own language translation files each with multiple pages for translating the forum plugin’s message strings.

Forum Plugin translation files are to reside in a unique forum folder location as defined by the “Simple:Press Plugin Language Files” entry on the “Integration – Storage Locations” forum Admin panel available through the forum Admin menu at Forum > Integration > Storage Locations.

  • The default location for forum plugin translation files is the folder “…/wp-content/sp-resources/forum-language/sp-plugins”.

Information regarding downloading language files, “mo’ language file placement, and translation (language localization) is found at Localization.

WARNING: On the Localization page, the Language Translation “.mo” Files Overview should be reviewed and well understood for naming convention and language translation file placement.

More information is available regarding translation files at Simple:Press Translations. which is the repository for Simple:Press language translation files. On the base page, select the “Getting Started Guide” link for basics about it’s use. On that page, select the “register a username here” link to obtain a password to the site. Use the “Contact Form” link to request the desired language if it is not currently available. The “Contact Form” link may also be used to volunteer to be a validator for a translation project.

This plugin’s available language translation files with translation statistics, and message translations can be viewed at Birthdays within the repository for Simple:Press language translation files.

  • Installing this Simple:Press Plugin’s Language Translation “.mo” files
    The plugin’s language translations files for each language can be correctly located in two ways.

    • Using the Admin Word:Press “Site Language” and Simple:Press “Language Translation” Features
      WARNING: On the Localization codex page, the Language Translation “.mo” Files Overview should be reviewed and well understood for naming convention and language translation file placement.
        • Under the “Language Translation Selection Sequences” heading, the “Coordinated Language Translation File Download Using the Simple:Press ‘Language Translation’ Selection” section, follow the instructions at “Adding its Translation File(s) After Downloading/Activating a Simple:Press Theme or Simple:Press Plugin”.
          • Follow the instructions to select the “Site Language” and then get to the admin page with the “Integration – Language Translations” section where there should be an entry for “Birthdays” along with an “Install” button.
          • Click on the “Install” button for this plugin to install the language translation file for the current “Site Language” language.
            • Note: If the message “No Translation Project Exists” is displayed rather than the “Install” button, a translation file for that language could not be found in GlotPress at this time. Consider posting in the Simple:Press forum if it is felt there needs to be one added.
          • Be sure to verify the locale (filename) for the “.mo” file matches the language code for the language as referenced in the “Warning” above. If it does not, change it to match.
          • As called out in the section, continue to change the “Site Language” language and repeat the process until all desired translation files for this plugin have been installed.

       

    • Manually Finding and Storing Simple:Press Plugin’s Language Translation ‘mo’ files
    • WARNING: On the Localization codex page, the Language Translation “.mo” Files Overview should be reviewed and well understood for naming convention and language translation file placement.
      • After reviewing the material discussed under the “Language Translation Selection Sequences” heading, the “Manual Installation of Simple:Press Language Translation Files section, follow the steps outlined at “Finding and Storing ANY Simple:Press Plugin’s Language Translation ‘mo’ files”.
      • Each time through the process at the step, “Scroll down the list and click on the name of the plugin whose language files are being sought to see the translation file Version Number available”, substitute “Birthdays” for the phrase “the name of the plugin whose language files are being sought”.
      • Be sure to verify the locale (filename) for the “.mo” file matches the language code for the language as referenced in the “Warning” above. If it does not, change it to match.
      • Repeat the steps for each language it is desired to have a translation file (french, spanish, etc.) for the plugin on the website.

Plugin Usage

Forum Admins use the plugin to set up its option.

Forum Users and Admins can enter their birth date in their profile if they wish to have their name appear in the birthday section of the forum page footer.

    • Specifying A User’s “Birth Date”
      • On the forum page, click on the “Profile” button to display the “Profile” page.
      • On the profile page, click on the “profile” tab to display the “Overview” page and the profile subtabs.
      • Click on the “Edit Profile” tab to display the “Edit Profile” page.
      • In the text input box to the right of “Birthday:” input the birthday for the user in the YYYY-MM-DD format where YYYY is the four digit identifier for the year (e.g. 1990), MM is the two digit identifier for the month (e.g. 01 for January, 12 for December), and DD is the two digit identifier for the day (e.g. 11 is the eleventh day of the month).
Note:
The user’s birth year is not displayed when the user’s birth month and day meet the criteria for displaying the user’s name in the birthday section of the forum page footer.
      • If there are no other options to select on the tab, click on the “Update Profile” button at the bottom of the page to save the settings. Otherwise, proceed to the next option(s) to select.

 

  • Viewing the Birthdays of Forum Users
    • On the forum page, scroll down to view the page footer and the “birthday cake” icon.
    • The names of forum users having birthdays today are shown to the right of “Today”.
    • The names of forum users having upcoming birthdays are shown to the right of “Uncoming”.

Plugin Special Notes

There are no specific member permissions that need setting.
All members can view the display of today’s and upcoming birthdays.
Users do not have to enter their birthday if they do not wish for theirs to be displayed.

 

Template Tags Used in the Plugin

There is one (1) template tag available for this plugin that allow further customization of the plugin’s usage or otherwise customize the website. ‘sp_ListBirthdays()‘is incorporated into standard supplied Simple:Press themes.

  • If the location of the template tags in the themes as well as the argument and parameter values for the template tags are acceptable, nothing need be done.
  • If any item relating to the template tags are to be modified or if the other template tags are to be added to a theme, it is recommended that a Child or Custom theme is created first to accept the changes prior to installing this plugin.
  • In all cases the template tags should be called conditionally, if (function_exists(‘ ‘)) so that if the plugin is deactivated or does not exist, the website will continue to operate.

The Template Tag can be viewed by selecting its link below.

Action and Hooks Used in the Plugin

There are Actions and Hooks available in the Plugin’s Template Tags. The Template Tag’s Action and Hooks can be viewed by selecting its link below.

There are other Actions and Hooks available for this plugin to modify aspects of the plugin.
In file ‘sp-birthdays-components.php‘:

  • do_action(‘sph_todays_birthday_list’, $birthdays) – Hook fired to fill the cache with the today’s and upcoming birthdays in preparation for the =’sph_birthday_cron’ executing.

In file ‘sp-birthdays-install.php‘:

  • do_action(‘sph_birthdays_cron’) – Hook fired to fill the cache initially for the ‘sph_birthday_cron’ when the plugin is installed and when it is reactivated. It is used in two (2) places within the file.

Plugin and Template Tag Changelog

Since Simple:Press version 5.1.4.

Codex page template tags sync’d to code version 5.6.4 and plugin version 1.2.8.



Individual Template Tags


 

sp_ListBirthdays

Description

sp_sp_ListBirthdays() – This template displays the users having birthdays and the birthday icon.

Usage

sp_sp_ListBirthdays($args, $headerLabel=”, $todayLabel=”, $upcomingLabel=”);

Arguments

$args – List of arguments for controlling display.
Type:
(string) (optional)
Default:
‘tagId’ => ‘spBirthdays’
‘tagClass’ => ‘spStatsSection’
‘headerClass’ => ‘spBirthdaysHeader’
‘bodyClass’ => ‘spBirthdaysBody’
‘todayClass’ => ‘spBirthdaysToday’
‘upcomingClass’ => ‘spBirthdaysUpcoming’
‘iconClass’ => ‘spIcon’
‘icon’ => ‘sp_BirthdayIcon.png’
‘showToday’ => 1
‘showUpcoming’ => 1
‘echo’ => 1
‘get’ => 0

tagId‘: CSS ID for the Div.
tagClass‘: CSS Class for the Div.
headerClass‘: CSS Class for the header.
bodyClass‘: CSS Class for the body.
todayClass‘: CSS Class for the ‘today’ birthday entries.
upcomingClass‘: CSS Class for the ‘upcoming’ birthday entries.
iconClass‘: CSS Class for the ‘birthday’ icon.
icon‘: Filename of file containing the birthday icon to display.
showToday‘: Flag to indicate whether or not to display the users having birthdays today. A one (1) will display the users’ names. A zero (0) will not display the users’ names.
showUpcoming‘: Flag to indicate whether or not to display the users having upcoming birthdays. A one (1) will display the users’ names. A zero (0) will not display the users’ names.
echo‘: Flag to indicate whether to write out the generated html display code or just return the html display code. One (1) is true and causes the html display code to be written to the display. Zero (0) is false and causes the html display code to be returned instead of written out.
get‘: Flag to indicate whether to short circuit the template tag display process and simply return data or to proceed with normal HTML display code generation. One (1) is true and the template tag display process is not done and data is returned. Zero (0) is false and normal html display code generation happens.

$headerLabel – Text shown as the header label identifying the birthday components.
Type:
(string) (optional)
Default:
None

$todayLabel – Text shown as the label displayed in front of the names of users with birthdays today.
Type:
(string) (optional)
Default:
None

$upcomingLabel – Text shown as the label displayed in front of the names of users with upcoming birthdays.
Type:
(string) (optional)
Default:
None

Special Notes

In standard supplied Simple:Press themes this template tag is included in the forum Footer (‘spFoot.php’) file.
The exceptions are:

    • the reboot and barebones themes where the template tag is not included in the ‘spHead.php’ file, but is included in the ‘spHeadDesktop.php’ and ‘spHeadMobile.php’ files.

 

The function is called conditionally, if (function_exists(‘ ‘)), so that if the plugin is deactivated or does not exist, the website will continue to operate.

The template tag can be placed elsewhere in the forum pages if that better fits the site’s theme. If the template tag is to be modified or its location on a page changed, it is suggested a Custom or Child theme be made to accept the modified template tag. Please see discussion at Template Tags Used in the Plugin.

The function requires the use of file ‘sp-birthdays-display-tag.php’ located in the plugin’s Template Tag folder.

Examples

In the forum footer display the names of forum users with birthdays today and those with upcoming birthdays using “tagclass” of “spCustomTag&spLeft”, “$headerLabel” of “Members Birthdays”, “$todayLabel” of “Today”, and “$upcomingLabel” of “Upcoming”. Call the function conditionally.

if (function_exists('sp_ListBirthdays')) sp_ListBirthdays('tagClass=spCustomTag&spLeft', __sp('Members Birthdays'), __sp('Today'), __sp('Upcoming'));

 

Actions and Hooks Used in the sp_ListBirthdays Template Tag

  • apply_filters(‘sph_ListBirthdays_args’, $a) – Allows modification of the arguments to the template tag. $a contains the parsed arguments.
  • apply_filters(‘sph_ListBirthdays’, $out, $a) – Allows modification of the display code just prior to being output/returned. $out will contain the html display code.

Changelog

See Plugin and Template Tag Changelog for Template Tag changes and Codex page syncing to code versions.


More Topics In SimplePress: Plugins


Copyright © 2006-2019 Simple:Press. All Rights Reserved.