Skip to content
Snippets Groups Projects
README.md 3.37 KiB
Newer Older
Chabadrichmond's avatar
Chabadrichmond committed
Household Greetings
===================

The **Household Greetings** extension for CiviCRM introduces dynamic email tokens to address individuals and their spouses. It ensures your communication is personalized and appropriate for both joint and individual recipients, streamlining the process for sending household-focused emails or letters.

* * *

Features
--------

*   **Dynamic Joint Tokens**: Includes new tokens that automatically adjust based on whether the recipient has a spouse:
    *   If a spouse exists: Displays both names (e.g., "John & Jane Doe").
    *   If no spouse exists: Displays the individual's name (e.g., "John Doe").
*   **Flexible Greetings**: Supports both informal and formal greetings with titles.
*   **Seamless Integration**: Works across CiviMail and other communication tools.
*   **Custom Tokens**: Provides tokens for addressing households or individuals flexibly.

* * *

Requirements
------------

*   PHP v7.1+
*   CiviCRM 5.46+

* * *

List of Tokens
--------------

1.  `{contact.household_greeting}`: Informal joint greeting (e.g., "John & Jane").
2.  `{contact.household_greeting_formal}`: Formal joint greeting (e.g., "Mr. and Mrs. John Doe").
3.  `{contact.individual_greeting}`: Fallback for individual-only communications.

* * *

Installation
------------

1.  **Download the Extension**:  
    Clone or download the extension from the [Household Greetings Git Repository](https://lab.civicrm.org/Chabadrichmond/household-greetings).
    
        git clone https://lab.civicrm.org/Chabadrichmond/household-greetings.git
    
2.  **Upload to CiviCRM**:  
    Place the `com.stools.householdgreetings` folder in your CiviCRM extensions directory.
3.  **Enable the Extension**:  
    1.  Navigate to **Administer → System Settings → Extensions** in CiviCRM.
    2.  Locate "Household Greetings" in the list of extensions.
    3.  Click **Install** to enable the extension.

* * *

Setup and Configuration
-----------------------

1.  Navigate to the **Household Greetings setup page** in your CiviCRM interface.
    *   **Location:** Go to **Administer → CiviMail → Household Greetings Settings**.
2.  Customize greeting settings:
    *   Choose the format for informal and formal greetings.
    *   Test token outputs for different recipient scenarios.
3.  Save your changes.

* * *

Usage
-----

1.  Insert tokens into your email or PDF letter templates:
    *   Use `{contact.household_greeting}` for informal joint greetings.
    *   Use `{contact.household_greeting_formal}` for formal joint greetings.
    *   Use `{contact.individual_greeting}` as a fallback.
2.  Preview and send:
    *   Ensure the tokens populate correctly for all recipients.

* * *

Screenshots
-----------

### Setup Page

![Settings Page](images/settingspage.png)

### Example Token in a Letter Template

(Insert screenshot here)

### Final Output

(Insert screenshot here)

* * *

Contributing
------------

Contributions are welcome! Please submit issues or pull requests via the [GitHub repository](https://github.com/your-repository/com.stools.householdgreetings).

* * *

License
-------

This extension is licensed under the [GNU AGPL-3.0](https://www.gnu.org/licenses/agpl-3.0.html).

* * *

Maintainer
----------

This extension has been developed and is maintained by [Pradeep Nayak](https://github.com/pradpnayak).

For more details, refer to the documentation or watch the setup video demonstration.