📓 add documentation

README.md

@@ -1,44 +1,84 @@
-# de.forumzfd.twinglecampaign
+# Twingle Campaign
 
-![Screenshot](/images/screenshot.png)
+![Screenshot](images/screenshot.png)
 
-(*FIXME: In one or two paragraphs, describe what the extension does and why one would download it. *)
+This extension allows you:
+
+- to manage [Twingle](https://www.twingle.de/) projects and events as campaigns in CiviCRM (including almost all
+  donation form settings)
+- to automatically assign donations that arrive via Twingle donation forms to the corresponding campaign
+- to track the origin of your donations
 
 The extension is licensed under [AGPL-3.0](LICENSE.txt).
 
 ## Requirements
 
-* PHP v7.0+
+* PHP v7.2+
-* CiviCRM (*FIXME: Version number*)
+* CiviCRM 5.14+
+* Extension: [Twingle API](https://github.com/systopia/de.systopia.twingle)
+* Extension: [Campaign Manager](https://github.com/systopia/de.systopia.campaign)
+* Extension: [Extended Contact Matcher (XCM)](https://github.com/systopia/de.systopia.xcm)
 
-## Installation (Web UI)
+The **[Twingle API](https://github.com/systopia/de.systopia.twingle)** allows you to receive API calls from Twingle to
+create donations. The **Twingle Campaign** extension enhances this functionality by automatically creating campaigns for
+each donation form (project) and peer-to-peer event and assigning the incoming donations to them. While you can use
+the **Twingle API** extension on its own, there is no point in using the **Twingle Campaign** extension without the
+other.
 
-This extension has not yet been published for installation via the web UI.
+The **[Campaign Manager](https://github.com/systopia/de.systopia.campaign)** is required to visualize the projects and
+events within the campaign tree as parent and child campaigns.
 
-## Installation (CLI, Zip)
+The **[XCM](https://github.com/systopia/de.systopia.xcm)** is needed to match or create contacts for people which start
+a peer-to-peer event.
 
-Sysadmins and developers may download the `.zip` file for this extension and
+## Concept
-install it with the command-line tool [cv](https://github.com/civicrm/cv).
 
-```bash
+The idea of the **Twingle Campaign** extension is to represent Twingle donation forms (projects) and peer-to-peer events
-cd <extension-dir>
+as campaigns in CiviCRM. Therefore, the extension creates new campaign types:
-cv dl de.forumzfd.twinglecampaign@https://github.com/FIXME/de.forumzfd.twinglecampaign/archive/master.zip
-```
 
-## Installation (CLI, Git)
+- [Twingle Project](docs/Twingle_Project.md)
+- [Twingle Event](docs/Twingle_Event.md)
 
-Sysadmins and developers may clone the [Git](https://en.wikipedia.org/wiki/Git) repo for this extension and
+There is another campaign type: [Twingle Campaign](docs/Twingle_Campaign.md)
-install it with the command-line tool [cv](https://github.com/civicrm/cv).
+Please don't get confused: this campaign type is named after this extension because it's a really clever thing that
+allows you to track the origin a donation.
 
-```bash
+![Concept](images/Concept.png)
-git clone https://github.com/FIXME/de.forumzfd.twinglecampaign.git
-cv en twinglecampaign
-```
 
-## Usage
+Together with normal campaigns, the three Twingle campaign types can be used to build complex campaign trees. This
+allows you to keep track of the performance of every single donation form, peer-to-peer event and newsletter (with
+TwingleCampaign cid link) while it sums up all donations in the parent campaigns.
 
-(* FIXME: Where would a new user navigate to get started? What changes would they see? *)
+![Campaign Trees](images/Campaign_Trees.png)
+
+To assign the incoming donations to the corresponding campaigns, the *Twingle Campaign* extension uses
+an [API Wrapper](docs/API_Wrapper.md) that extends the function of the **Twingle API** (extension).
+
+## Configuration
+
+Bevore you can synchronize your Twingle projects and events, you have to enter your Twingle API key on the Twingle
+Campaign Configuration page.
+
+![Extension Settings](images/extension_settings.png)
+
+If you would like to match or create contacts for event initiators (people who start their own peer-to-peer event) via
+the XCM, make sure to create a [new XCM configuration](docs/Example Settings/XCM_profile.md) for this purpose.
+
+On default, this extension will synchronize all Twingle projects and events once every hour. You can increase or
+decrease this interval by changing the configuration of the scheduled job named *TwingleSync*.
+
+![Scheduled Job](images/scheduled_job.png)
+
+Furthermore, the synchronization may get triggered also if a donation for an unknown event arrives via the Twingle API
+extension.
 
 ## Known Issues
 
-(* FIXME *)
+- The **Campaign Manager** displays a *«Campaign XY has been saved»* message even if the input validation failed and the
+  campaign was **not saved or sent** to Twingle.
+
+## To Do's
+
+- [ ] Make the Twingle Event Settings for contact matching, case creation and creation of soft credits an individual
+  setting in each project
+- [ ] Make more payment methods available

docs/API_Wrapper.md

@@ -0,0 +1,15 @@
+# API Wrapper
+
+The **Twingle API** extension uses profiles to process every incoming donation. When Twingle calls the
+*TwingleDonation.submit* API, provided by the **Twingle API** extension, the API assigns the donation to the
+corresponding profile by looking up the project id which comes with the call. The profile settings then specifies how
+the donation should be treated.
+
+![TwingleDonation.submit](../images/TwingleDonation.submit.png)
+
+The **Twingle Campaign** extension puts an API wrapper around the *TwingleDonation.submit* API. This first it searches
+the call for either a project id, an event id or a campaign id and depending on the result, it searches CiviCRM for the
+
+![API Wrapper](../images/API_Wrapper.png)
+
+Furthermore, the API wrapper enables you to create soft credits for peer-to-peer event initiators.

docs/Example Settings/XCM_profile.md

@@ -0,0 +1,13 @@
+# XCM example settings
+The contact information that Twingle provides about the peer-to-peer event initiators are:
+- First Name
+- Last Name
+- Email
+
+So make sure you set only these fields as rules for matching.
+
+![XCM Settings](../../images/XCM_settings.png)
+
+
+
+

docs/Twingle_Campaign.md

@@ -0,0 +1,15 @@
+# Twingle Campaign
+
+The *Twingle Campaign* campaign type does, unlike the other campaign types (*Twingle Project* & *Twingle Event*), not
+represent an entity on the Twingle side.
+
+The *Twingle Campaign*  is can be used to track the origin of a donation. In order to achieve this, it takes the URL of
+it's *Twingle Project* parent campaign and adds a `cid` parameter to its end that will be sent to Twingle and back. With
+the `cid` coming back from Twingle via API call to *TwingleDonation.submit* (provided by the **Twingle API** extension)
+the donation can get assigned to the originally *Twingle Campaign*.
+
+**Attention:** The *Twingle Campaign* must always be the child (or grandchild) of a *Twingle Project*.
+
+You can use the *Twingle Campaign* url for example for newsletters or social media posts. The url will lead the users to
+the Twingle donation form of the parent *Twingle Project* but thanks to the `cid`, the donation will be assigned to
+the *Twingle Campaign*.

docs/Twingle_Event.md

@@ -0,0 +1,9 @@
+# Twingle Event
+
+The *Twingle Event* campaign type represents peer-to-peer events created by users. The campaigns get synchronized
+between Twingle and CiviCRM in only one direction: from Twingle to CiviCRM. There is no need to synchronize them through
+the other direction, because usually it is not necessary to change their values. *Twingle Events* are created by users
+through a *Twingle Project* of type event.
+
+You can activate the creation of soft credits for event initiators. In this case a donation by person A will be linked
+as soft credit to person B which is the event initiator.

docs/UML/Campaigns.uml

@@ -0,0 +1,36 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Diagram>
+  <ID>PHP</ID>
+  <OriginalElement>\CRM_TwingleCampaign_BAO_Campaign</OriginalElement>
+  <nodes>
+    <node x="1052.5454545454545" y="675.0">\CRM_TwingleCampaign_BAO_TwingleCampaign</node>
+    <node x="512.2727272727273" y="675.0">\CRM_TwingleCampaign_BAO_TwingleEvent</node>
+    <node x="-40.0" y="675.0">\CRM_TwingleCampaign_BAO_TwingleProject</node>
+    <node x="241.0" y="-47.27272727272725">\CRM_TwingleCampaign_BAO_Campaign</node>
+  </nodes>
+  <notes />
+  <edges>
+    <edge source="\CRM_TwingleCampaign_BAO_TwingleEvent" target="\CRM_TwingleCampaign_BAO_Campaign" relationship="GENERALIZATION">
+      <point x="0.0" y="-138.5" />
+      <point x="718.7727272727273" y="614.0" />
+      <point x="432.0" y="614.0" />
+      <point x="0.0" y="294.5" />
+    </edge>
+    <edge source="\CRM_TwingleCampaign_BAO_TwingleProject" target="\CRM_TwingleCampaign_BAO_Campaign" relationship="GENERALIZATION">
+      <point x="0.0" y="-174.5" />
+      <point x="172.5" y="614.0" />
+      <point x="432.0" y="614.0" />
+      <point x="0.0" y="294.5" />
+    </edge>
+  </edges>
+  <settings layout="Hierarchic" zoom="0.55" showDependencies="false" x="821.0" y="542.9999999999999" />
+  <SelectedNodes>
+    <node>\CRM_TwingleCampaign_BAO_Campaign</node>
+  </SelectedNodes>
+  <Categories>
+    <Category>Fields</Category>
+    <Category>Methods</Category>
+  </Categories>
+  <VISIBILITY>private</VISIBILITY>
+</Diagram>
+

docs/UML/Custom_Data.uml

@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Diagram>
+  <ID>PHP</ID>
+  <OriginalElement>\CRM_TwingleCampaign_BAO_CampaignType</OriginalElement>
+  <nodes>
+    <node x="448.0" y="0.0">\CRM_TwingleCampaign_BAO_CampaignType</node>
+    <node x="0.0" y="0.0">\CRM_TwingleCampaign_BAO_CustomField</node>
+    <node x="916.0" y="0.0">\CRM_TwingleCampaign_BAO_OptionValue</node>
+  </nodes>
+  <notes />
+  <edges />
+  <settings layout="Hierarchic" zoom="0.7" showDependencies="false" x="853.12987012987" y="165.0" />
+  <SelectedNodes />
+  <Categories>
+    <Category>Fields</Category>
+    <Category>Methods</Category>
+  </Categories>
+  <VISIBILITY>private</VISIBILITY>
+</Diagram>
+