Commit 05f20212 authored by Christian Wach's avatar Christian Wach

Initial release

parent 94e4c8ca
# CiviCRM Groups Sync
CiviCRM Groups Sync
===================
*CiviCRM Groups Sync* is a WordPress plugin that keeps Contacts in CiviCRM Groups in sync with WordPress Users in groups provided by the [Groups plugin](https://wordpress.org/plugins/groups/).
\ No newline at end of file
Please note: this is the development repository for *CiviCRM Groups Sync*.
*CiviCRM Groups Sync* is a WordPress plugin that keeps Contacts in CiviCRM Groups in sync with WordPress Users in groups provided by the [Groups plugin](https://wordpress.org/plugins/groups/).
#### Notes ####
This plugin requires a minimum of *WordPress 4.9*, *Groups 2.5* and *CiviCRM 5.8*.
##### WordPress users #####
By default, this plugin does not create a WordPress user when a CiviCRM contact is added to a CiviCRM group which is synced to a Groups group. If you wish to do so, use a callback from the `civicrm_groups_sync_user_id_get_by_contact_id` filter to create a new WordPress user and return the user ID.
##### CiviCRM contacts #####
By default, this plugin does not create a CiviCRM contact when a WordPress user is added to a Groups group which is synced to a CiviCRM group. If you wish to do so, use a callback from the `civicrm_groups_sync_contact_id_get_by_user_id` filter to create a new CiviCRM contact and return the contact ID.
#### Installation ####
There are two ways to install from GitHub:
###### ZIP Download ######
If you have downloaded *CiviCRM Groups Sync* as a ZIP file from the GitHub repository, do the following to install and activate the plugin and theme:
1. Unzip the .zip file and, if needed, rename the enclosing folder so that the plugin's files are located directly inside `/wp-content/plugins/civicrm-groups-sync`
2. Activate the plugin (in multisite, network activate)
3. You are done!
###### git clone ######
If you have cloned the code from GitHub, it is assumed that you know what you're doing.
<!-- assets/templates/admin/settings-groups.php -->
<div class="field">
<label for="civicrm-group-field" class="field-label civicrm-group-field"><input type="checkbox" id="civicrm-group-field" name="civicrm-group-field" /> <?php _e( 'Create a CiviCRM group', 'civicrm-groups-sync' ); ?></label>
<p class="description"><?php _e( 'Checking this will create a CiviCRM group that is linked to this group. The group members will exist in both groups.', 'civicrm-groups-sync' ); ?></p>
</div>
<!-- assets/templates/admin/settings-page.php -->
<div class="wrap">
<h1><?php _e( 'CiviCRM Groups Sync', 'civicrm-groups-sync' ); ?></h1>
<?php if ( $show_tabs ) : ?>
<h2 class="nav-tab-wrapper">
<a href="<?php echo $urls['settings']; ?>" class="nav-tab nav-tab-active"><?php _e( 'Settings', 'civicrm-groups-sync' ); ?></a>
<?php
/**
* Allow others to add tabs.
*
* @since 0.1
*
* @param array $urls The array of subpage URLs.
* @param str The key of the active tab in the subpage URLs array.
*/
do_action( 'civicrm_groups_sync_settings_nav_tabs', $urls, 'settings' );
?>
</h2>
<?php else : ?>
<hr />
<?php endif; ?>
<form method="post" id="civicrm_groups_sync_settings_form" action="<?php echo $this->page_submit_url_get(); ?>">
<?php wp_nonce_field( 'civicrm_groups_sync_settings_action', 'civicrm_groups_sync_settings_nonce' ); ?>
<p><?php _e( 'Settings to go here.', 'civicrm-groups-sync' ) ?></p>
<hr />
<p class="submit">
<input class="button-primary" type="submit" id="civicrm_groups_sync_settings_submit" name="civicrm_groups_sync_settings_submit" value="<?php _e( 'Save Changes', 'civicrm-groups-sync' ); ?>" />
</p>
</form>
</div><!-- /.wrap -->
{* template block that contains the new field *}
<table>
<tr class="civicrm_groups_sync_create_block">
<td class="label"><label for="civicrm_groups_sync_create">{ts}Create Synced Group{/ts}</label></td>
<td>{$form.civicrm_groups_sync_create.html} <span class="description">{ts}If you are creating a Synced Group, you only need to fill out the "Title" field (and optionally the "Description" field) above. The Group Type will be set to "Access Control" automatically.{/ts}</span></td>
</tr>
</table>
{* reposition the above block after #someOtherBlock *}
<script type="text/javascript">
// jQuery will not move an item unless it is wrapped
cj('tr.civicrm_groups_sync_create_block').insertBefore('.crm-group-form-block .crm-group-form-block-group_type');
</script>
<!-- assets/templates/help/settings-help.php -->
<p><?php _e( 'Settings: For further information about using CiviCRM Groups Sync, please refer to the readme.txt file that comes with this plugin.', 'civicrm-groups-sync' ); ?></p>
<?php /*
--------------------------------------------------------------------------------
Plugin Name: CiviCRM Groups Sync
Plugin URI: https://github.com/christianwach/civicrm-groups-sync
Description: Keeps Contacts in CiviCRM Groups in sync with WordPress Users in groups provided by the Groups plugin.
Author: Christian Wach
Version: 0.1
Author URI: http://haystack.co.uk
Text Domain: civicrm-groups-sync
Domain Path: /languages
Depends: CiviCRM
--------------------------------------------------------------------------------
*/
// Set our version here.
define( 'CIVICRM_GROUPS_SYNC_VERSION', '0.1' );
// Store reference to this file.
if ( ! defined( 'CIVICRM_GROUPS_SYNC_FILE' ) ) {
define( 'CIVICRM_GROUPS_SYNC_FILE', __FILE__ );
}
// Store URL to this plugin's directory.
if ( ! defined( 'CIVICRM_GROUPS_SYNC_URL' ) ) {
define( 'CIVICRM_GROUPS_SYNC_URL', plugin_dir_url( CIVICRM_GROUPS_SYNC_FILE ) );
}
// Store PATH to this plugin's directory.
if ( ! defined( 'CIVICRM_GROUPS_SYNC_PATH' ) ) {
define( 'CIVICRM_GROUPS_SYNC_PATH', plugin_dir_path( CIVICRM_GROUPS_SYNC_FILE ) );
}
/**
* CiviCRM Groups Sync Class.
*
* A class that encapsulates plugin functionality.
*
* @since 0.1
*/
class CiviCRM_Groups_Sync {
/**
* Admin utilities object.
*
* @since 0.1
* @access public
* @var object $admin The Admin utilities object.
*/
public $admin;
/**
* CiviCRM utilities object.
*
* @since 0.1
* @access public
* @var object $civicrm The CiviCRM utilities object.
*/
public $civicrm;
/**
* WordPress utilities object.
*
* @since 0.1
* @access public
* @var object $wordpress The WordPress utilities object.
*/
public $wordpress;
/**
* Constructor.
*
* @since 0.1
*/
public function __construct() {
// Initialise.
add_action( 'plugins_loaded', array( $this, 'initialise' ) );
}
/**
* Do stuff on plugin init.
*
* @since 0.1
*/
public function initialise() {
// Only do this once.
static $done;
if ( isset( $done ) AND $done === true ) {
return;
}
// Enable translation.
$this->enable_translation();
// Init only when CiviCRM is fully installed.
if ( ! defined( 'CIVICRM_INSTALLED' ) ) return;
if ( ! CIVICRM_INSTALLED ) return;
// Bail if CiviCRM plugin is not present.
if ( ! function_exists( 'civi_wp' ) ) return;
// Bail if we don't have the "Groups" plugin.
if ( ! defined( 'GROUPS_CORE_VERSION' ) ) return;
// Include files.
$this->include_files();
// Set up objects and references.
$this->setup_objects();
// Finally, register hooks.
$this->register_hooks();
/**
* Broadcast that this plugin is now loaded.
*
* @since 0.1
*/
do_action( 'civicrm_groups_sync_loaded' );
// We're done.
$done = true;
}
/**
* Include files.
*
* @since 0.1
*/
public function include_files() {
// Load our classes.
require( CIVICRM_GROUPS_SYNC_PATH . 'includes/civicrm-groups-sync-admin.php' );
require( CIVICRM_GROUPS_SYNC_PATH . 'includes/civicrm-groups-sync-civicrm.php' );
require( CIVICRM_GROUPS_SYNC_PATH . 'includes/civicrm-groups-sync-wordpress.php' );
}
/**
* Set up this plugin's objects.
*
* @since 0.1
*/
public function setup_objects() {
// Instantiate classes.
$this->admin = new CiviCRM_Groups_Sync_Admin( $this );
$this->civicrm = new CiviCRM_Groups_Sync_CiviCRM( $this );
$this->wordpress = new CiviCRM_Groups_Sync_WordPress( $this );
}
/**
* Register hooks.
*
* @since 0.1
*/
public function register_hooks() {
// If global-scope hooks are needed, add them here.
}
/**
* Load translation files.
*
* @since 0.1
*/
public function enable_translation() {
// Enable translation
load_plugin_textdomain(
'civicrm-groups-sync', // Unique name.
false, // Deprecated argument.
dirname( plugin_basename( __FILE__ ) ) . '/languages/' // Relative path to files.
);
}
//##########################################################################
/**
* Check if this plugin is network activated.
*
* @since 0.1
*
* @return bool $is_network_active True if network activated, false otherwise.
*/
public function is_network_activated() {
// Only need to test once.
static $is_network_active;
// Have we done this already?
if ( isset( $is_network_active ) ) {
return $is_network_active;
}
// If not multisite, it cannot be.
if ( ! is_multisite() ) {
$is_network_active = false;
return $is_network_active;
}
// Make sure plugin file is included when outside admin.
if ( ! function_exists( 'is_plugin_active_for_network' ) ) {
require_once( ABSPATH . '/wp-admin/includes/plugin.php' );
}
// Get path from 'plugins' directory to this plugin.
$this_plugin = plugin_basename( CIVICRM_GROUPS_SYNC_FILE );
// Test if network active.
$is_network_active = is_plugin_active_for_network( $this_plugin );
// --<
return $is_network_active;
}
/**
* Check if CiviCRM is initialised.
*
* @since 0.1
*
* @return bool True if CiviCRM initialised, false otherwise.
*/
public function is_civicrm_initialised() {
// Bail if no CiviCRM init function.
if ( ! function_exists( 'civi_wp' ) ) return false;
// Try and initialise CiviCRM.
return civi_wp()->initialize();
}
} // Class ends.
/**
* Utility to get a reference to this plugin.
*
* @since 0.1
*
* @return object CiviCRM_Groups_Sync The plugin reference.
*/
function civicrm_groups_sync() {
// Store instance in static variable.
static $civicrm_groups_sync = false;
// Maybe return instance.
if ( false === $civicrm_groups_sync ) {
$civicrm_groups_sync = new CiviCRM_Groups_Sync();
}
// --<
return $civicrm_groups_sync;
}
// Initialise plugin now.
civicrm_groups_sync();
// Uninstall uses the 'uninstall.php' method.
// See: http://codex.wordpress.org/Function_Reference/register_uninstall_hook
/**
* Utility to add link to settings page.
*
* @since 0.1
*
* @param array $links The existing links array.
* @param str $file The name of the plugin file.
* @return array $links The modified links array.
*/
function civicrm_groups_sync_action_links( $links, $file ) {
// Add links only when CiviCRM is fully installed.
if ( ! defined( 'CIVICRM_INSTALLED' ) ) return $links;
if ( ! CIVICRM_INSTALLED ) return $links;
// Bail if CiviCRM plugin is not present.
if ( ! function_exists( 'civi_wp' ) ) return $links;
// Bail if we don't have the "Groups" plugin.
if ( ! defined( 'GROUPS_CORE_VERSION' ) ) return $links;
// Add settings link.
if ( $file == plugin_basename( dirname( __FILE__ ) . '/civicrm-groups-sync.php' ) ) {
// Add settings link if not network activated and not viewing network admin.
$link = add_query_arg( array( 'page' => 'civicrm_groups_sync_parent' ), admin_url( 'options-general.php' ) );
$links[] = '<a href="' . esc_url( $link ) . '">' . esc_html__( 'Settings', 'civicrm-groups-sync' ) . '</a>';
// Always add Paypal link.
$paypal = 'https://www.paypal.me/interactivist';
$links[] = '<a href="' . $paypal . '" target="_blank">' . __( 'Donate!', 'civicrm-groups-sync' ) . '</a>';
}
// --<
return $links;
}
// Add filter for the above.
add_filter( 'plugin_action_links', 'civicrm_groups_sync_action_links', 10, 2 );
<?php
/**
* CiviCRM Groups Sync Admin Class.
*
* A class that encapsulates Admin functionality.
*
* @since 0.1
*/
class CiviCRM_Groups_Sync_Admin {
/**
* Plugin (calling) object.
*
* @since 0.1
* @access public
* @var object $plugin The plugin object.
*/
public $plugin;
/**
* Plugin version.
*
* @since 0.1
* @access public
* @var str $plugin_version The plugin version.
*/
public $plugin_version;
/**
* Plugin settings.
*
* @since 0.1
* @access public
* @var array $settings The plugin settings.
*/
public $settings = array();
/**
* Parent Page.
*
* @since 0.1
* @access public
* @var str $parent_page The parent page.
*/
public $parent_page;
/**
* Settings Page.
*
* @since 0.1
* @access public
* @var str $settings_page The settings page.
*/
public $settings_page;
/**
* Class constructor.
*
* @since 0.1
*
* @param object $plugin The plugin object.
*/
public function __construct( $plugin ) {
// Store reference to plugin.
$this->plugin = $plugin;
// Add action for init.
add_action( 'civicrm_groups_sync_loaded', array( $this, 'initialise' ) );
}
//##########################################################################
/**
* Initialise this object.
*
* @since 0.1
*/
public function initialise() {
// Load plugin version.
$this->plugin_version = $this->option_get( 'civicrm_groups_sync_version', 'none' );
// Perform any upgrade tasks.
$this->upgrade_tasks();
// Upgrade version if needed.
if ( $this->plugin_version != CIVICRM_GROUPS_SYNC_VERSION ) {
$this->store_version();
}
// Load settings array.
$this->settings = $this->option_get( 'civicrm_groups_sync_settings', $this->settings );
// Register hooks.
$this->register_hooks();
}
/**
* Perform upgrade tasks.
*
* @since 0.1
*/
public function upgrade_tasks() {
// None needed yet.
}
/**
* Store the plugin version.
*
* @since 0.1
*/
public function store_version() {
// Store version.
$this->option_set( 'civicrm_groups_sync_version', CIVICRM_GROUPS_SYNC_VERSION );
}
/**
* Register hooks.
*
* @since 0.1
*/
public function register_hooks() {
// Add admin page to Settings menu.
add_action( 'admin_menu', array( $this, 'admin_menu' ) );
}
//##########################################################################
/**
* Add admin menu items for this plugin.
*
* @since 0.1
*/
public function admin_menu() {
/**
* Set capability but allow overrides.
*
* @since 0.1
*
* @param str The default capability for access to settings page.
* @return str The modified capability for access to settings page.
*/
$capability = apply_filters( 'civicrm_groups_sync_page_settings_cap', 'manage_options' );
// Check user permissions.
if ( ! current_user_can( $capability ) ) return;
// Add the admin page to the Settings menu.
$this->parent_page = add_options_page(
__( 'CiviCRM Groups Sync: Settings', 'civicrm-groups-sync' ),
__( 'CiviCRM Groups Sync', 'civicrm-groups-sync' ),
$capability,
'civicrm_groups_sync_parent',
array( $this, 'page_settings' )
);