PledgeBank for CiviCRM - Specifications

TABLE OF CONTENTS

Roles

• Pledge creator/owner - person in possession of appropriate CiviCRM permissions allowing him/her to create Pledges. Conceptually, creating a Pledge is understood as binding him/herself or his/her organisation to perform certain action, if given number of people bind themselves to do the same (or something different). Technically, creating a Pledge is setting up an object described in definition below. Apart from creating a pledge, Pledge creator/owner has ability to perform different administrative tasks throughout whole Pledge's lifecycle.

• Pledge signer - person using functionality offered by Pledge to make a promise by which he/she binds him/herself to perform an action defined by Pledge creator/owner (named in the Pledge). Pledge signer is never anonymous for Pledge creator/owner, however his/hers credentials might stay undisclosed on public pages.

Permissions

• access PledgeBank for CiviCRM - defines ability to use the module

• edit pledge signer records - defines ability to edit pledge signer records

• access PledgeBank public pages - defines ability to access public pledge pages and ability to sign pledges

• view pledge signer records - defines ability to view pledge signer records

Menu structure

• PledgeBank for CiviCRM - modules dashboard
  • Find Signers - signer records search page
  • Manage Pledges - list of current pledges
  • New Pledge - link to new pledge adding page
  • Import Signers - link to pledge signing record import page

Data objects

Pledge (civicrm_pb_pledge)

REFER TO FIELDS BELOW: (creator_name) will (creator_pledge_desc) but only if (signers_limit) (signer_description_text) will (signer_pledge_desc).

I.e. I will (donate my old laptop to a charity) but only if (10) (other people) will (do the same).

Attributes:

Pledge Signer (civicrm_pb_signer)

Screen list

Screen: PledgeBank for CiviCRM Dashboard

Elements:

• list of max 10 recent active pledges (deadline in future, regardless of other attributes), made of following columns:
  • Title: (literally: "(creator_name) will (creator_pledge_desc) but only if (signers_limit) (signer_description_text) will (signer_pledge_desc).")
  • Id (civicrm_pb_pledge.id)
  • Signers limit (civicrm_pb_pledge.signers_limit)
  • Deadline (civicrm_pb_pledge.deadline)
  • Creator (display_name for civicrm_pb_pledge.creator_id)
  • Status: (successful or failed - as described in Pledge status chapter)
  • Active? (civicrm_pb_pledge.is_active)
• list of max 10 recent pledge signers
  • Name: (display_name for civicrm_pb_signer.signer_id), linked to contact record
  • Pledge: (literally: "...will (civicrm_pb_pledge.signer_pledge_desc)"), linked to pledge view page
  • Signed on: (civicrm_pb_signer.signing_date)
  • Anonymous? (civicrm_pb_signer.is_anonymous)
  • Done? (civicrm_pb_signer.is_done)

Screen: Find Signers

• Search form elements:
  • signer name: input text
  • pledge name: ajax selector
  • pledge deadline from: date selector
  • pledge deadline to: date selector
  • pledge done: checkbox
• Selector columns:
  • Name: (display_name for civicrm_pb_signer.signer_id), linked to contact record
  • Pledge: (literally: "...will (civicrm_pb_pledge.signer_pledge_desc)"), linked to pledge view page
  • Signed on: (civicrm_pb_signer.signing_date)
  • Anonymous? (civicrm_pb_signer.is_anonymous)
  • Done? (civicrm_pb_signer.is_done)
  • Find test signatures (civicrm_pb_signer.is_test)

Screen: Manage pledges

• Search form elements:
  • Pledge: input text (returns hit if keyword found in any of the following fields: creator_name, creator_pledge_desc, signer_description_text, signer_pledge_desc)
  • Show only result: radio group
    • successful: radio option
    • failed: radio option
    • unselect: link removing selection from both above
  • Show only finished: checkbox
  • pledge due date from: show pledges where deadline is after this date
  • pledge due date to: show pledges where deadline is before this date
• List of pledges:
  • Title: (literally: "(creator_name) will (creator_pledge_desc) but only if (signers_limit) (signer_description_text) will (signer_pledge_desc).")
  • Id (civicrm_pb_pledge.id)
  • Signers limit (civicrm_pb_pledge.signers_limit)
  • Deadline (civicrm_pb_pledge.deadline)
  • Creator (display_name for civicrm_pb_pledge.creator_id)
  • Status: (successful|failed - as described in Pledge status chapter)
  • Active? (civicrm_pb_pledge.is_active)

Wizard: New pledge

Wizard is made of three steps:

• "Pledge Settings" screen
• "Pledge location" screen
• "Tell a Friend" screen

"Pledge Settings" screen

First five fields will define pledge text itself.
(creator_name) will (creator_pledge_desc), but only if (signers_limit) (signer_description_text) will (signer_pledge_desc).

• Group: "Pledge text"
  • creator_name - input text, defaulted to: "I", validated on max length (64 characters), required
  • creator_pledge_desc - input text, validated on max length (256 characters), required
  • signers_limit - input text, validated on integer value, required
  • signer_description_text - input text, validated on max length (128 characters), required
  • signer_pledge_desc - input text, validated on max length (256 characters), required
• deadline: Pledge deadline: date selector, required
• description: Pledge detailed information: rich text field, no validation
• creator_description: Pledge owner's description: input text, validated on max length (256 characters)
• is_active: Is this Pledge active?: checkbox

"Pledge location" screen

This screens allows to define optional geographical location of the pledge:

• Does this pledge have location?: checkbox, if set to true, reveals a location form containing fields:
  • City
  • Zip / Postal Code -
  • Enter optional 'add-on' code after the dash ('plus 4' code for U.S. addresses).
  • Country
  • State / Province
  • Latitude, Longitude

"Tell a Friend" screen

Exactly as in CiviEvent wizard.

Screen: View pledge

PledgeBank for CiviCRM administrative screens

Screen: Module preferences

• Group: PledgeBank for CiviCRM Dashboard preferences
  • maximum number of pledges shown on dashboard (input text) - determines how many pledges are shown on the listing on PledgeBank for CiviCRM Dashboard screen
  • maximum number of pledge signers shown on dashboard (input text) - determines how many pledge signers are shown on the listing on PledgeBank for CiviCRM Dashboard screen

Other concepts

Pledge status

Pledge can be either successful or failed.

• Successful pledge is the one meeting following condition: before the deadline passed, it has been signed by more signers than signer_limit states
• Failed pledge is the one that didn't gather enough signatures before the deadline passed.

Cron jobs

External systems integration