====== Birthday list ======

This plugin is used to display birthdays and anniversaries of members.

Results are directly shown on the screen. 

In addition to display the generated lists they can also be printed or exported.

{{:de:2.0:documentation:plugins:geburtstagsliste:anzeige_mit_email.png?400|}}

===== Installation =====

For installation the following steps have to be done:

  - Create a new folder in **adm_plugins** with the name "geburtstagsliste".
  - All files (and folders) in the folder birthday list from the unzipped Zip file copy in this folder.
  - Following lines add to //\admidio\adm_themes\modern\my_body_bottom.php// (e.g. after calling login_form.php):
<code php>
  include(SERVER_PATH.'/adm_plugins/geburtstagsliste/geburtstagsliste.php');
</code>

{{:de:2.0:documentation:plugins:geburtstagsliste:link_liste_und_einstellungen.png?200|}}
 
===== Operation =====

Depending on the configurations the plugin generates birthday and anniversary lists.


  * About a settings menu, the plugin is configured. This settings menu can, separate from the display list, are authorized only for specific roles. The display may, for example, be released for the roles Board and / or head of department. The configuration can only be done by the role Webmaster.

  * The display is in list form, each column of the list (surname, first name, place, etc) must be activated in the settings menu. 

  * The last column displayed is the Focus column. For columns in focus, different configurations can be created. The source of a focus column is always a profile field of type DATE.

  * Either the current date or January 1 of the current year can be chosen as a reference date for the display. 

  * The display of the birthday and anniversary lists can be done either for a certain number of days (for example, display of important birthdays within the next 60 days) or as well  for a particular months (eg display of important birthdays in the month of May).

===== Configuration =====

{{:de:2.0:documentation:plugins:geburtstagsliste:einstellungen_menue.png?300|}}

The entire configuration of the plugin is done via the **Settings** menu.

=== The Settings Menu ===

The settings menu is divided into five menu items.

  * Coloumns
  * Configurations
  * Options
  * Plugin Access
  * Plugin Information

== Coloumns ==

{{:de:2.0:documentation:plugins:geburtstagsliste:einstellungen_spalten.png?300|}}

Across **Columns**  those columns to be displayed in the list are selected. Multiple selection is possible using the CTRL key.

**Notice:** Sorting of coloumns is not possible.

== Configurations ==

{{:de:2.0:documentation:plugins:geburtstagsliste:einstellungen_spaltenkonfiguration1.png?300|}}

{{:de:2.0:documentation:plugins:geburtstagsliste:einstellungen_spaltenkonfiguration2.png?300|}}

{{:de:2.0:documentation:plugins:geburtstagsliste:einstellungen_spaltenkonfiguration3.png?300|}}

Across **configurations** many additional columns (= Focus column) can be configured.
In the subsequent display of birthday list one of these columns will focus in each case determined as a basis for display, ie to them, the focus is set. The Focus column is always the last column of the display. Use the Field Chooser for profile fields of type DATE to be selected as the source for this configuration. Across Role selection and category selection can be further restricted to specific roles and / or categories.

Example:

Problem:
The Head of soccer team needs a list of all anniversary birthdays of members of his team.
(Assuming that a category "Division Football" with appropriate roles exists.)

Configuration:
|Description: |Special birthdays football|
|Field Selection:|Birthday|
|Values:|20,30,40,50,60,70,80,90|
|Suffix:|th birthday at #Day#.#Month#|
|Role Selection:| |
|Category Selectionl:|Division Soccer| 

**Note:** 
  * The Role Selection and category selection is dependent on the respective role configurations in Admidio.
  * To make the suffix must begin with a space it must be declared as non-breaking space with the Code &nbsp; (eg &nbsp;-th birthday on #Day # # # Month.).
  * The text description of a column should not be identical to the text of the field selection. In order to avoid display errors caused by same names, in this case, the description text will be automatically updated with "-focus"

{{:de:2.0:documentation:plugins:geburtstagsliste:einstellungen_spaltenkonfiguration_namensgleichheit1.png?300|}}

{{:de:2.0:documentation:plugins:geburtstagsliste:einstellungen_spaltenkonfiguration_namensgleichheit2.png?300|}}

Across **email-text** an text can be customized and added to an email. The text is divided into two areas (Subject & Content) and is identified by the string #subject# and #content#. To be followed by the contents of the area.

In each message, the following placeholders can be used, which will be replaced at runtime by the relevant content:

  * %user_first_name% - Firstname of the member
  * %user_last_name% - Lastname of the member
  * %organization_long_name% - Name of organization
  * %focus% - Text of the coloumn in focus

**Note:** Requirement for sending e-mails is the display of email addresses. For this, the column e-mail in the menu columns must be selected.

To delete a configuration again, only the text has to be deleted in the description field.
{{:de:2.0:documentation:plugins:geburtstagsliste:einstellungen_spaltenkonfiguration_spalte_loeschen.png?300|}}

Example for configurations:

{{:de:2.0:documentation:plugins:geburtstagsliste:einstellungen_spaltenkonfiguration_beispiel1.png?300|}}

Display anniversary birthdays (no restriction).

{{:de:2.0:documentation:plugins:geburtstagsliste:einstellungen_spaltenkonfiguration_beispiel2.png?300|}}

Displaying anniversary birthdays with the limitation to a particular category.

{{:de:2.0:documentation:plugins:geburtstagsliste:einstellungen_spaltenkonfiguration_beispiel3.png?300|}}

Display of anniversaries with the restriction on the role of bowling (on the assumption that the role and the profile of bowling field accession exist).

== Options ==

{{:de:2.0:documentation:plugins:geburtstagsliste:einstellungen_optionen1.png?300|}}

{{:de:2.0:documentation:plugins:geburtstagsliste:einstellungen_optionen2.png?300|}}

Across **Options** common valid settings can be set.

  * Length of text
  * Configurations
  * Preview of dates
  * Focus
  * Preview list
  * Database Separator
  * Year

**Text length** is the maximum length of text in the select boxes (min. 20). 

Across **Configurations**, the number of configurations can be increased.

{{:de:2.0:documentation:plugins:geburtstagsliste:einstellungen_optionen_defaulteinstellungen.png?300|}}

With **Preview** and **Days Focus** Default settings for the start are determined.

In the **Preview list** the dates are entered, which will be offered later in the birthday list for selection. Multiple entries must be separated by commas (ex: -14,2,5,10,20,30,60,365). A preview is maximum possible for one year.

Using the **database** delimiter, so configuration data that are managed at runtime as an array, will be combined into a string and stored in the Admidio database. If the predetermined combination of characters (# _ #) but also, for example, be used in describing a configuration, so the plugin is unable to read properly stored configuration data. In this case, change the preset combination of characters (eg in !-!).

The setting **Calendar Year** determines the reference date of the output. By default, the output is the current date. The hook If the output from 1 January of the current year is to begin, then you can select. This setting has no effect when choosing a month.

== Access for Plugin ==

{{:de:2.0:documentation:plugins:geburtstagsliste:einstellungen_pluginfreigabe1.png?300|}}

{{:de:2.0:documentation:plugins:geburtstagsliste:einstellungen_pluginfreigabe2.png?300|}}

Selection of roles whose members are allowed to call the plugin. The display of the birthday list and the settings menu can be unlocked separately for specific roles.

{{:de:2.0:documentation:plugins:geburtstagsliste:link_liste_ohne_einstellungen.png?200|}}

**Note:** A selected role also needs at least one of the following permissions of the Admidio role management:
  * "Maintain roles and assign"
  * "Edit profile data of all users"
  * "Maintain registrations and assign"

== Plugin Information ==

{{:de:2.0:documentation:plugins:geburtstagsliste:einstellungen_plugininformationen.png?300|}}

Here information about the version and the state of the plugin will be displayed.

=== Saving Configurations ===

All configuration data is stored in an additional table called adm_plugin_preferences in Admidio database. If not yet exist this table, so it will be created.

Currently, in this table, the following configurations plugins are stored:
   * Membership fee
   * Category report
   * Birthday list
The table entries of the plugin Birthday List all begin here with the letters "PGL".

=== File readme.txt ===

Current information regarding update or reinstall the plugin are located in the readme.txt

===== Display =====

{{:de:2.0:documentation:plugins:geburtstagsliste:fokus.png?400|}}

Display of birthdays January 1 to December 31

{{:de:2.0:documentation:plugins:geburtstagsliste:kein_fokus_gesetzt.png?400|}}

This message appears when you start the birthday list, if the default setting of the preview days has been set too low.

{{:de:2.0:documentation:plugins:geburtstagsliste:anzeige_mit_email.png?400|}}

To send emails, the email column to be have to be displayed.

{{:de:2.0:documentation:plugins:geburtstagsliste:modul_email.png?400|}}

Depending on the Admidio e-mail settings, either the module E-mail or the default email client opens.

{{:de:2.0:documentation:plugins:geburtstagsliste:druckvorschau.png?400|}}

For a check in front of a term the print preview can be chosen.

{{:de:2.0:documentation:plugins:geburtstagsliste:export.png?400|}}

Across the pull-down menu "Export to ..." the list is exported. 

Two differently formatted CSV files are available for download:
  * Microsoft Excel (ISO-8859-1)
  * CSV-Datei (UTF-8) 
 
Examples of displays:

{{:de:2.0:documentation:plugins:geburtstagsliste:anzeige_runder_geburtstag_gesamt.png?400|}}

All anniversary birthdays between 1 January to 31 December.

{{:de:2.0:documentation:plugins:geburtstagsliste:anzeige_tage_auswahl.png?400|}}

The same focus, but the preview will be only 30 days.

{{:de:2.0:documentation:plugins:geburtstagsliste:anzeige_tage.png?400|}}

The same focus for the period 1 to 30 January

{{:de:2.0:documentation:plugins:geburtstagsliste:vorschautage_zu_klein_gesetzt.png?400|}}

Message, if no user is found, because the preview days were too small.

{{:de:2.0:documentation:plugins:geburtstagsliste:anzeige_monat_auswahl.png?400|}}

The same focus, but the preview is supposed to be only for the month of November.

{{:de:2.0:documentation:plugins:geburtstagsliste:anzeige_monat.png?400|}}

The same focus for the month of November

{{:de:2.0:documentation:plugins:geburtstagsliste:anzeige_runder_geburtstag_fussball.png?400|}}

On the other focus; here with restriction on category and / or role

{{:de:2.0:documentation:plugins:geburtstagsliste:fokus_auswahl.png?400|}}

Another focus is selected.