Merge pull request #14 from dnadesign/2

Merging Branch 2 into master

README.md

@@ -1,13 +1,113 @@
 # Ubiquity for Silverstripe - IN DEVELOPMENT
+
 ## Introduction
+
 Integrate data with https://www.qrious.co.nz/products/ubiquity
-##Requirements
-Silverstripe 3.7 (Silverstripe 4 compatibility is coming)
-##Set Up
-To set this up,
-- 1. first log into the cms
-- 2. then go to site settings
-- 3. Enter your Ubiquity database information
-- 4. Enter the user defined form you wish to edit.
-- 5. Under the Ubiquity Config, select the Ubiquity database you want to work with.
-- 6. You will be able to add the ubiquity form ids to a user defined form.
+
+This module integrates with User Defined Forms to provide a way to post data to a Ubiquity form upon submission.
+
+**Note:** This is a new version of the module which requires a Ubiquity form to be created to act as an intermediary between SilverStripe and the Ubiquity database.
+The SS3 and dev-SS4 branch can post to the Ubiquity database directly without posting to a Ubiquity form, and would optionally post the form afterward, but this mechanism is flawed and deemed inefficient.
+
+**Note:** Ubiquity offers to create forms that can be customised and embedded into a website. This module requires a Ubiquity form to be created, but will not embed it on the site, but will rather use the API to trigger the form when a UDF is submitted.
+
+## Requirements
+
+```
+ "silverstripe/framework": "^4"
+ "silverstripe/cms": "^4"
+ "silverstripe/userforms": "^5"
+```
+
+## Ubiquity requirements
+
+Before you can start populating the Ubiquity database from a SilverStripe form, you need to:
+
+- `Get an API token` from https://engage.ubiquity.co.nz/api/account
+
+- `Create a form` https://engage.ubiquity.co.nz/forms/dashboard/
+This form will be used by UDF to post data to a Ubiquity form, which will add/update an entry in the Ubiquity database as well as optionally trigger some extra actions, eg: sending a welcome email.
+Add the fields you wish to populate to the form and note their ID.
+
+**Note:** Depending on your level of permission, you may not be able to access these interfaces or create/edit the relevant objects. You may need to contact the account owner to do so or request a `Super User` level of permission.
+
+More documentation can be found at https://help.ubiquity.co.nz/
+
+## Set up
+
+### Global settings
+
+Part of the set up is done in the Settings section of the CMS:
+
+- Create a Ubiquity database in `Settings > Ubiquity setup` and add your API token.
+The name of the database doesn't need to match the Ubiquity name, but it is best practice to keep them consistent.
+
+- `Enable Ubiquity` globally. You will later be able to disable it on a per UDF basis.
+Note that if you use the Ubiquity service class provided by this module, without using UDF, the global global still applies.
+
+- Optionally `Activate Ubiquity Analytics`. If you have a Analytics key for Ubiquity, a javascript script will be added to UDF pages to provide extra tracking data (similar to Google Analytics).
+
+![Silverstripe Ubiquity Settings](docs/images/ss-ubiquity-settings.png)
+
+### User Defined Form
+
+On a User Defined Form page, in the `Ubiquity` tab, you need to:
+
+- `Enable Ubiquity`. Note that if Ubiquity is disabled globally, this config has no effect.
+
+- Select which `Ubiquity Database` you want to use. Databases are essentially an API token that will be used to communicate with Ubiquity. 
+
+- Provide the `Ubiquity form ID` you want to post to. This is required for the process to work. The ID can be found on https://engage.ubiquity.co.nz/api/IdList in the Forms section.
+**Note:** the form should be in the same database as previously selected.
+
+![Silverstripe UDF Settings](docs/images/udf-ubiquity-settings.png)
+
+#### Form Fields
+
+- Add form fields as you would normally do on a User Defined Form
+
+- If you wish to include the value of a field in the payload sent to Ubiquity, add a `Ubiquity field ID`. These IDs can be found in https://engage.ubiquity.co.nz/api/IdList and optionally in the CMS Settings > Ubiquity setup > Database (edit).
+**Note:** Use only the IDs of the fields that have been added to the Ubiquity form.
+
+- Optionally, you can supply a value that will replace the value provided by the user. This is useful in the case of a checkbox, where you want to submit a string other than Yes/No to Ubiquity.
+You also have the option to use `[submission_date]` to post the date at which the form has been submitted.
+
+![Silverstripe UDF Fields Settings](docs/images/udf-field-ubiquity-settings.png)
+
+#### Special Fields
+
+This module provides the user with 2 new editable field types:
+
+##### Editable Hidden Field
+
+This field is useful to sent data to Ubiquity without needing a user input, especially if a field is required on the Ubiquity form. Usually a `Source` field or `Date` field is required to track from where and when a user has subscribed.
+
+This field will not be visible on the front end, but will be included in the data sent to ubiquity if a Ubiquity field ID is provided.
+
+Use the `Default Value` field to set the value sent to Ubiquity. You can also use `[submission_date]` to automatically populate the field with the current date.
+
+##### Editable Sign up Field
+
+This is basically a checkbox allowing the user to opt in/out of the sending their data to Ubiquity.
+
+If this field is included on the form, the data will only be submitted to Ubiquity if the user has tick the checkbox.
+
+This field can also sent data to Ubiquity.
+
+##### Editable Multi OptionChoice Field
+
+This field is included out of the box with User Defined Form and is displayed as a Dropdown or Radio boxes.
+If a Ubiquity ID is matched to this field, the selected value will be sent to Ubiquity.
+
+In addition, each of its options can have their own Ubiquity field ID. If the option is selected by the user, then a another Ubiquity field can be sent the same value (or the overwritten one). The main application is to record different dates in the database, eg:
+
+Ubiquity database has 3 fields:
+- Is subscribed ?
+- Opt in date
+- Opt out date
+
+The the user defined form has one Multi choice field with 2 options:
+
+- Multi choice field post its value `(Yes or No)` to the "Is Subscribed" field 
+- Option 1 (Yes) post the `submission_date]` to the "Opt in date" field
+- Option 2 (No) post the `submission_date]` to the "Opt out date" field

_config/ubiquity.yml

@@ -2,24 +2,24 @@
 Name: ubiquityconfig
 ---
 
-SiteConfig:
+SilverStripe\SiteConfig\SiteConfig:
   extensions:
-    - UbiquitySiteConfigExtension
-UserDefinedForm:
+    - Ubiquity\Extensions\UbiquitySiteConfigExtension
+SilverStripe\UserForms\Model\UserDefinedForm:
   extensions:
-    - UbiquityFormExtension
-SubmittedForm:
+    - Ubiquity\Extensions\UbiquityFormExtension
+SilverStripe\UserForms\Model\Submission\SubmittedForm:
   extensions:
-    - UbiquityUserFormControllerExtension
-EditableFormField:
+    - Ubiquity\Extensions\UbiquityUserFormControllerExtension
+SilverStripe\UserForms\Model\EditableFormField:
   extensions:
-    - UbiquityEditableFormFieldExtension
-EditableOption:
+    - Ubiquity\Extensions\UbiquityEditableFormFieldExtension
+SilverStripe\UserForms\Model\EditableFormField\EditableOption:
   extensions:
-    - UbiquityEditableOptionExtension
-EditableMultipleOptionField:
+    - Ubiquity\Extensions\UbiquityEditableOptionExtension
+SilverStripe\UserForms\Model\EditableFormField\EditableMultipleOptionField:
   extensions:
-    - UbiquityMultipleOptionExtension
-Page_Controller:
+    - Ubiquity\Extensions\UbiquityMultipleOptionExtension
+PageController:
   extensions:
-    - UbiquityPageControllerExtension
+    - Ubiquity\Extensions\UbiquityPageControllerExtension

composer.json

@@ -1,7 +1,7 @@
 {
 	"name": "dnadesign/silverstripe-ubiquity",
 	"description": "Implements Ubiquity extensions for User Defined Forms",
-	"type": "silverstripe-module",
+	"type": "silverstripe-vendormodule",
 	"keywords": ["silverstripe", "ubiquity", "newsletter"],
 	"license": "MIT",
 	"authors": [{
@@ -10,11 +10,14 @@
 	}],
 	"minimum-stability": "dev",
 	"require": {
-		"silverstripe/framework": "~3.7",
-		"silverstripe/cms": "~3.7"
+		"silverstripe/framework": "^4",
+		"silverstripe/cms": "^4",
+		"silverstripe/userforms": "^5",
+		"symbiote/silverstripe-gridfieldextensions": "^3",
+		"silverstripe/display-logic" : "^2"
 	},
     "require-dev": {
-        "phpunit/PHPUnit": "~3.7@stable"
+		"phpunit/phpunit": "7.5.x"
     },
 	"extra": {
 		"installer-name": "silverstripe-ubiquity"

src/Extensions/UbiquityEditableFormFieldExtension.php

@@ -1,35 +1,42 @@
 <?php
 
+namespace Ubiquity\Extensions;
+
+use SilverStripe\Forms\CheckboxField;
+use SilverStripe\Forms\FieldList;
+use SilverStripe\Forms\TextField;
+use SilverStripe\ORM\DataExtension;
+
 /**
  * Extension to add additional fields to EditableFormField
  * to enable a field to submit to an ubiquity form field.
- * UbiquityFieldID: the ID of the coreesponding field in the Ubiquity form
+ * 
+ * UbiquityFieldID: the ID of the corresponding field in the Ubiquity form
+ * 
  * UbiquityValue: If set, the will override the value of the field to send to Ubiquity
- * AllowOverride: if checked, the eixting value in the Ubiquity database for this field
- * will be overriden with the new value submitted
+ * 
+ * AllowOverride: if checked, the existing value in the Ubiquity database for this field
+ * will be overwritten with the new value submitted
  */
 class UbiquityEditableFormFieldExtension extends DataExtension
 {
     private static $db = [
         'UbiquityFieldID' => 'Varchar',
-        'UbiquityValue' => 'Varchar',
-        'AllowOverride' => 'Boolean',
+        'UbiquityValue' => 'Varchar'
     ];
 
     public function updateCMSFields(FieldList $fields)
     {
         $database = $this->owner->Parent()->UbiquityDatabase();
 
         if ($database && $database->exists()) {
-            $fields->addFieldToTab('Root.Main', TextField::create('UbiquityFieldID', 'Ubiquity Field ID'));
-
             $value = TextField::create('UbiquityValue', 'Value override to submit to Ubiquity Form');
             $value->setRightTitle('Use [submission_date] to send the date on which the form has been submitted.');
-            $fields->addFieldToTab('Root.Main', $value);
 
-            $update = CheckboxField::create('AllowOverride', 'Allow Override Ubiquity DB ')
-                ->setDescription('Allow to update the information of this field when a user already exists in DB.');
-            $fields->addFieldToTab('Root.Main', $update);
+            $fields->addFieldsToTab('Root.Main', [
+                TextField::create('UbiquityFieldID', 'Ubiquity Field ID'),
+                $value
+            ]);
         }
 
         return $fields;

src/Extensions/UbiquityEditableOptionExtension.php

@@ -1,5 +1,12 @@
 <?php
 
+namespace Ubiquity\Extensions;
+
+use SilverStripe\Forms\CheckboxField;
+use SilverStripe\Forms\FieldList;
+use SilverStripe\Forms\TextField;
+use SilverStripe\ORM\DataExtension;
+
 /**
  * Extension for EditableOption
  * Allows sending a different value to Ubiquity that the value of the option selected
@@ -8,21 +15,18 @@ class UbiquityEditableOptionExtension extends DataExtension
 {
     private static $db = [
         'UbiquityFieldID' => 'Varchar',
-        'UbiquityValue' => 'Varchar',
-        'AllowOverride' => 'Boolean'
+        'UbiquityValue' => 'Varchar'
     ];
 
     public function updateCMSFields(FieldList $fields)
     {
         $database = $this->owner->Parent()->UbiquityDatabase;
 
         if (isset($database)) {
-            $fields->addFieldToTab('Root.Main', TextField::create('UbiquityFieldID', 'Ubiquity Field ID'));
-            $fields->addFieldToTab('Root.Main', TextField::create('UbiquityValue', 'Value override to submit to Ubiquity Form'));
-
-            $update = CheckboxField::create('AllowOverride', 'Allow Override Ubiquity DB ')
-                ->setDescription('Allow to update the information of this field when a user already exists in DB.');
-            $fields->addFieldToTab('Root.Main', $update);
+            $fields->addFieldsToTab('Root.Main', [
+                TextField::create('UbiquityFieldID', 'Ubiquity Field ID'),
+                TextField::create('UbiquityValue', 'Value override to submit to Ubiquity Form')
+            ]);
         }
 
         return $fields;

src/Extensions/UbiquityFormExtension.php

@@ -1,86 +1,53 @@
 <?php
 
+namespace Ubiquity\Extensions;
+
+use SilverStripe\Core\Extension;
+use SilverStripe\Forms\CheckboxField;
+use SilverStripe\Forms\DropdownField;
+use SilverStripe\Forms\FieldList;
+use SilverStripe\Forms\LiteralField;
+use SilverStripe\Forms\TextField;
+use Ubiquity\Models\UbiquityDatabase;
+use Ubiquity\Services\UbiquityService;
+
 /**
  * Adds Ubiquity setup to a DataObject that contains a form.
  */
-class UbiquityFormExtension extends \Extension
+class UbiquityFormExtension extends Extension
 {
     private static $db = [
         'UbiquityEnabled' => 'Boolean',
-        'UbiquitySuccessFormID' => 'Varchar(100)',
-        'UbiquitySuccessFormEmailTriggerID' => 'Varchar(100)',
-        'UbiquitySuccessFormAction' => 'Varchar(100)',
-        'UbiquitySourceFieldID' => 'Varchar(100)',
-        'UbiquitySourceName' => 'Varchar(100)',
-        'UbiquitySubmitSource' => 'Boolean',
+        'UbiquityFormID' => 'Varchar(100)'
     ];
 
     private static $has_one = [
-        'UbiquityDatabase' => 'UbiquityDatabase'
+        'UbiquityDatabase' => UbiquityDatabase::class
     ];
 
-    public function updateCMSFields(\FieldList $fields)
+    public function updateCMSFields(FieldList $fields)
     {
         // Check if Ubiquity is enabled and display a message if not
         if (!UbiquityService::get_ubiquity_enabled()) {
-            $fields->addFieldToTab('Root.UbiquityConfig', new LiteralField('Warning', "<p class=\"message\">Ubiquity is not enabled in siteconfig.</p>"));
+            $fields->addFieldToTab('Root.UbiquityConfig', new LiteralField('Warning', "<p class=\"message\">Ubiquity is not enabled in site config.</p>"));
             return;
         }
 
-        // Check if Ubiquity databases exist for the current development
-        // environment - staging (dev/test) or production (live)
-        $databaseOptions = UbiquityDatabase::get_database_options();
-        if (empty($databaseOptions)) {
-            $fields->addFieldToTab('Root.UbiquityConfig', new LiteralField('Warning', sprintf(
-                "<p class=\"message\">No Ubiquity databases are set up for this environment (%s) in SiteConfig</p>",
-                Director::get_environment_type()
-            )));
-            return;
-        }
+        $enabled = CheckboxField::create('UbiquityEnabled', 'Enable Ubiquity');
 
-        $enabled = CheckboxField::create('UbiquityEnabled', 'Ubiquity Enabled');
-
-        // Ubiquity Database to post data to (from a list of databases for the current
-        // development enviornment - staging (dev/test) or production (live)
+        // Ubiquity Database to post data to
+        $databaseOptions = UbiquityDatabase::get_database_options();
         $database = DropdownField::create('UbiquityDatabaseID', 'Ubiquity Database', $databaseOptions)
             ->setEmptyString('-- Select one --');
-
-        // Ubiquity allows submitting data to a form as well, usually tied to the Ubiquity database
-        // By populating the Sucess Form ID, you can automatically trigger an email response to
-        // be sent to the user, as if the Form was submitted directly.
-        $formID = TextField::create('UbiquitySuccessFormID', 'Ubiquity Success Form ID')
-            ->setDescription('ID of the form that will be used to send confirmation email once the user has signed up.');
-
-        // To trigger emails of the form, you must define which field the form needs to have the email sent.
-        $formFieldID = TextField::create('UbiquitySuccessFormEmailTriggerID', 'Ubiquity Success Form Field ID')
-            ->setDescription('ID of the field that will be used to send the form action (ususally named EmailTrigger)');
-
-        // Ubiquity forms can send different emails, define the Action that will send the email
-        $formAction = TextField::create('UbiquitySuccessFormAction', 'Ubiquity Success Form Action')
-            ->setDescription('Name of the Email that should be sent.');
-
-        // Allows Ubiquity to track the soure of the submission, eg newsletter signup, event form, feedback form
-        // Define the FieldID of the Ubiquity Field
-        $sourceID = TextField::create('UbiquitySourceFieldID', 'Ubiquity Source Field ID')
-            ->setDescription('ID of the field that will be use as primary source for the user.');
-
-        // Define the Name of the source to populate the above field
-        $sourceName = TextField::create('UbiquitySourceName', 'Ubiquity Source Name')
-            ->setDescription('Reference of this form as source.');
 
-        // Submit the source even if  a T&C's field is included yet is not checked
-        $submitSource = CheckboxField::create('UbiquitySubmitSource', 'Submit Source')
-            ->setDescription('Submit the source data even if a T&C\'s field exists but is not ticked');
+        // Ubiquity allows submitting data to a form as well, usually tied to the Ubiquity database
+        $formID = TextField::create('UbiquityFormID', 'Ubiquity Form ID')
+            ->setDescription('ID of the form used to send the data to.');
 
         $fields->addFieldsToTab('Root.Ubiquity', [
             $enabled,
             $database,
-            $formID,
-            $formFieldID,
-            $formAction,
-            $sourceID,
-            $sourceName,
-            $submitSource
+            $formID
         ]);
     }
 }