This is a collaborative project w/ CivicActions to integrate a flash-based fund-raising widget that CiviCRM sites can distribute.
CiviWidget Implementation Notes
The following properties of the widget are configurable. They are currently hard-coded in Services_Widget::getCampaign() - but all or most should come from the database and be editable.
1. These are already defined in the schema (civicrm_contribution_page):
$data->money_target = goal_amount (required)
$data->campaign_start = start_date (optional)
$data->campaign_end = end_date (optional)
$data->is_active = is_active (required)
- The widget doesn't work properly if money_target is not defined, so we'll have to do some kind of validation against goal_amount when they enable/save the Configure Widget page. Maybe put up an error if they try to "get" the Widget embed code AND goal_amount is 0 or null.
- We'll need to set $data->is_active false IF current date is prior to start_date OR later than end_date OR contribution_page.is_active is false. Widget will then put up "Campaign is over message and expose the homepage_link.
2. These items are system generated / calculated via query:
$data->button_url = Live URL for this contribution page
$data->num_donors = COUNT contributions where contribution_page_id = this page, status = completed
$data->money_raised = SUM ....;
3. These need to be added to schema, and included for editing via the new "CiviContribute Widget" interface (under Configure Online Contribution Page). I've included defaults which I think we should provide when a widget is first enabled for a contribution page. (Setting useful defaults makes the config quick and easy - and I think this approach is working nicely in Tell a Friend and can work nicely here.):
$data->title = Required, default to Contribution Page title.
$data->logo = Optional (tested that widget works w/o one). Looks like a URL to an image works - altho might be easier if we allow them to upload an image and reference it in our uploaded images directory.
$data->button_title = Required, default = "Contribute!"
$data->about = Required (since About tab appears on widget even if this element is undefined in the array). Default = null
$data->homepage_link = Required, Default = userFrameworkBaseURL
I guess we can keep the colors provided by Sam as defaults. I think we need to allow them to edit these though, so I guess we need fields for each one edited in a "Configure Widget Colors" fieldset.
$data->colors["title"] = "0x000000"; Title Text Color
$data->colors["button"] = "0xCC9900"; Button Color
$data->colors["bar"] = "0xCC9900"; Progress Bar Color
$data->colors["main_text"] = "0x000000"; Additional Text Color
$data->colors["main"] = "0x96E0E0"; Inner Background Gradient from Bottom
$data->colors["main_bg"] = "0xFFFFFF"; Inner Background Top Area
$data->colors["bg"] = "0x66CCCC"; Border Color
I think we can get away with leaving these link colors hard-coded:
// these two have colors as normal hex format
// because they're being used in a CSS object
$data->colors["about_link"] = "#336699"; // links in the about section (if any)
$data->colors["homepage_link"] = "#336699"; // homepage link, shown instead of 'contribute' button when is_active = false
NOTE: The original spec included having a "Copy" button on the widget. This allow folks to get the "embed code" for the widget FROM an instance of the widget - and is quite cool for viral "spreading the word". We can either try to get Sam to add the "front end" for this now - or implement as a phase 2 item.
----- Original Specification --------------
- There will be a single compiled flash widget for all CiviCRM
distributions. Widgets will be "linked" to a webservice at the domain
of a given CiviCRM installation AND to a specific CiviContribute
contribution page (ID) via parameters in the embed src string. All
other 'configurable' widget params will be passed to the widget by the
webservice. The webservice link should be a "permalink".
- Widgets will be Flash 8 compat, and to solve the MySpace issue will
contain a transparent gif over the bottom whatever pixels of the swf
to link to the contrib page.
- Widgets will retrieve the following data from the webservice:
- Widget Title
- Button Title (default = "Contribute")
- About text (2nd tab)
- Num of donors
- Target $
- Raised $
- Start/end date for campaign (optional)
- is_active flag (0/1)
- If a start and/or end date is passed, and the current date is not
within that range, OR active = FALSE - then the widget will function
as a static "report" of donation activity (link to contrib page is
disabled / "Donate" button is hidden)
- Widgets will include a "Share / Spread the Word" button which will
expose the embed code needed to copy the widget to other web pages.
(Every widget is the same for anyone who embeds it - widgets are not
customizable by end-users via embed params. )
- CivicActions will:
- Specify the data / format needed to be supplied by the webservice
and provide sample output
- Design and build the widget. Jacob will check with Greg and others
in CA with fundraising experience for feedback on widget features and
- Flash code will be licensed under AFL or AGPL. Design
elements/graphics under CC. Widget should NOT be a clone of Chipin
NOTE: There may be some design ideas worth looking at on
- CiviCRM engineers will implement the following functionality to
support the widget:
- webservice to provide data to the widget via XML-RPC for Flash
(we'll shoot to get something into trunk pretty quickly after we get
the XML data specs and sample output)
- add "Get code for widget" functionality to "Manage Contribution
Pages" administration screens (similar to "Standalone Profile Form")
- add start and end date feature to Online Contribution Page object
- look at optimizations for webservice calls : minimize what civicrm
functions are loaded when Widgets "phone home"; consider caching the
XML output for x duration; etc.)
CivicActions code is in their repository at: