M#12 - Proposed Strategy

README.md

@@ -1,44 +1,78 @@
 ![Build Status](https://github.com/DiscipleTools/disciple-tools-media/actions/workflows/ci.yml/badge.svg?branch=master)
-## Dev notes, delete me:
-This is a starter plugin to jumpstart your work with Disciple.Tools.
-Click the "Use this template" button above.
-See instructions for refactoring and getting started in the [wiki](https://github.com/DiscipleTools/disciple-tools-media/wiki)
-See instructions for creating releases and publishing your plugin: [wiki](https://github.com/DiscipleTools/disciple-tools-media/wiki)
-In order to display the banner correctly on the Disciple.Tools Community Plugins Site, don't change the 'Plugin Banner' text on line 12; only the URL.
-
-## readme format:
-
-![Plugin Banner](https://raw.githubusercontent.com/DiscipleTools/disciple-tools-media/b30402d97895e3f911efcb47fb8f29ccd1eb92e5/documentation/banner.png)
 
 # Disciple.Tools - Media
 
-Description Description Description Description Description Description Description
-Description Description Description Description Description Description Description
+Disciple.Tools - Media is intended to help manage connections with remote object storage services, such as AWS S3, Backblaze, etc.
 
 ## Purpose
 
-Purpose purpose purpose purpose purpose purpose purpose purpose purpose purpose purpose
-Purpose purpose purpose purpose purpose purpose purpose purpose purpose purpose purpose
+Provide the ability to store/retrieve all media content within 3rd party object storage services; offering greater security.
 
-Purpose purpose purpose purpose purpose purpose purpose purpose purpose purpose purpose
-Purpose purpose purpose purpose purpose purpose purpose purpose purpose purpose purpose
+A detailed description of the typical usage flow for creating and using connections is provided below.
 
 ## Usage
 
 #### Will Do
 
-- Item
-- Item
-- Item
+- Create multiple object storage services connections.
+- Test supplied connection credentials.
+- Select default media connection to be used for file storage within D.T theme.
+- Edit user profile pictures.
 
 #### Will Not Do
 
-- Item
-- Item
+- Add media content to comments.
+- Add media content to records.
+
+#### Typical Usage Flow
+
+- In order to use the new D.T Media Plugin, ensure PHP version 8.1 or greater has been installed.
+
+![0](documentation/readme/imgs/0.png)
+
+- Once D.T Media Plugin has been installed, create a new connection.
+
+![1](documentation/readme/imgs/1.png)
+
+- The following connection types (3rd Party Object Storage Services) are currently supported:
+  - [AWS S3](https://aws.amazon.com/s3/)
+  - [BackBlaze](https://www.backblaze.com/)
+  - [MinIO](https://min.io/)
+
+
+- Enter required connection details; ensuring specified bucket has already been created within 3rd party object storage service.
+
+![2](documentation/readme/imgs/2.png)
+
+> If no endpoint protocol scheme is specified; then https:// will be used.
+
+- Test connection, to ensure supplied credentials are valid.
+
+![3](documentation/readme/imgs/3.png)
+
+- The following will be shown for failed connection tests.
+
+![4](documentation/readme/imgs/4.png)
+
+> Some important things to note when working with Backblaze services:
+>
+> - Currently, due to API version restrictions, Backblaze connections are unable to be validated and will typically fail, with Network Error exceptions, when attempting to test connection. However, you should be able to upload and retrieve files freely within the D.T Frontend UI.
+> - Ensure sufficient CORS permissions have been applied to target Backblaze bucket, as shown below:
+
+![5](documentation/readme/imgs/5.png)
+
+- Once new connection has been validated and saved, navigate to Media Settings section within D.T General Settings and select connection to be used for the default media storage within D.T.
+
+![6](documentation/readme/imgs/6.png)
+
+- Currently, media connections are only available when editing user profile pictures.
+
+![7](documentation/readme/imgs/7.png)
 
 ## Requirements
 
-- Disciple.Tools Theme installed on a Wordpress Server
+- Disciple.Tools Theme installed on a Wordpress Server.
+- Ensure PHP v8.1 or greater, has been installed.
 
 ## Installing
 
@@ -53,8 +87,3 @@ in the [Discussions](https://github.com/DiscipleTools/disciple-tools-media/discu
 code contributions are welcome using the [Pull Request](https://github.com/DiscipleTools/disciple-tools-media/pulls)
 system for git. For a more details on contribution see the
 [contribution guidelines](https://github.com/DiscipleTools/disciple-tools-media/blob/master/CONTRIBUTING.md).
-
-
-## Screenshots
-
-![screenshot](documentation/community/starter-banners/banner-blue-green.png)

admin/connections-tab.php

@@ -67,7 +67,7 @@ public function process_scripts() {
         wp_enqueue_script( 'aws-sdk-s3', 'https://sdk.amazonaws.com/js/aws-sdk-2.1583.0.min.js', [ 'jquery' ], '2.1583.0', true );
 
         dt_theme_enqueue_style( 'material-font-icons-local', 'dt-core/dependencies/mdi/css/materialdesignicons.min.css', array() );
-        wp_enqueue_style( 'material-font-icons', 'https://cdn.jsdelivr.net/npm/@mdi/[email protected]/css/materialdesignicons.min.css' );
+        wp_enqueue_style( 'material-font-icons', 'https://cdn.jsdelivr.net/npm/@mdi/[email protected]/css/materialdesignicons.min.css', array(), '6.6.96' );
 
         wp_enqueue_script( 'dt_media_script', plugin_dir_url( __FILE__ ) . 'js/connections-tab.js', [
             'jquery',

admin/js/connections-tab.js

@@ -171,6 +171,21 @@ jQuery(function ($) {
                 $('#connection_type_s3_region').val( type['region'] );
                 $('#connection_type_s3_bucket').val( type['bucket'] );
                 $('#connection_type_s3_endpoint').val( type['endpoint'] );
+
+                // Disable Test Connection button for Backblaze connection types; which is currently not supported with aws s3 v2 api!
+                if (connection_type['key'] === 'backblaze') {
+                  const test_but = $('#connection_type_s3_test_but');
+                  const test_but_content = $('#connection_type_s3_test_but_content');
+                  $(test_but).prop('disabled', true);
+                  $(test_but_content).text('Test Connection Not Supported!');
+                }
+              };
+            } else if (connection_type['key'] === 'backblaze') {
+              connection_type_refresh = function () {
+                const test_but = $('#connection_type_s3_test_but');
+                const test_but_content = $('#connection_type_s3_test_but_content');
+                $(test_but).prop('disabled', true);
+                $(test_but_content).text('Test Connection Not Supported!');
               };
             }
 
@@ -235,11 +250,25 @@ jQuery(function ($) {
     `;
   }
 
+  function validate_url( url ) {
+    try {
+
+      // Convert to url object.
+      const url_obj = new URL(url);
+
+      // Ensure correct protocols have been specified.
+      return ( ( url_obj.protocol === 'http:' ) || ( url_obj.protocol === 'https:' ) ) ?  url : ( 'https://' + url );
+
+    } catch (err) {
+      return 'https://' + url;
+    }
+  }
+
   function handle_connection_test_for_s3() {
 
     // Trigger spinner!
     const test_but_content = $('#connection_type_s3_test_but_content');
-    $(test_but_content).text('').removeClass('mdi mdi-lan-disconnect').removeClass('mdi mdi-lan-connect').addClass('loading-spinner active');
+    $(test_but_content).text('').addClass('loading-spinner active');
 
     try {
 
@@ -248,7 +277,7 @@ jQuery(function ($) {
       const secret_access_key = $('#connection_type_s3_secret_access_key').val();
       const region = $('#connection_type_s3_region').val();
       const bucket = $('#connection_type_s3_bucket').val();
-      const endpoint = $('#connection_type_s3_endpoint').val();
+      const endpoint = validate_url( $('#connection_type_s3_endpoint').val() );
 
       // Create aws s3 object.
       const s3 = new AWS.S3({
@@ -259,16 +288,14 @@ jQuery(function ($) {
         },
         endpoint: endpoint
       });
-      console.log( s3 );
 
       // A successful listing of buckets, shall constitute as a validated connection.
       s3.listBuckets({}, function(err, data) {
         if (err) {
           console.log(err, err.stack);
-          $(test_but_content).removeClass('loading-spinner active').addClass('mdi mdi-lan-disconnect');
+          $(test_but_content).removeClass('loading-spinner active').text('Connection Failed!');
 
         } else {
-          console.log(data);
 
           // Ensure configured bucket is also listed.
           let valid_connection = false;
@@ -282,17 +309,17 @@ jQuery(function ($) {
 
           // Report back accordingly on connection test.
           if ( valid_connection ) {
-            $(test_but_content).removeClass('loading-spinner active').addClass('mdi mdi-lan-connect');
+            $(test_but_content).removeClass('loading-spinner active').text('Connection Successful!');
 
           } else {
-            $(test_but_content).removeClass('loading-spinner active').addClass('mdi mdi-lan-disconnect');
+            $(test_but_content).removeClass('loading-spinner active').text('Connection Failed!');
           }
         }
       });
 
     } catch ( error ) {
       console.log( error );
-      $(test_but_content).removeClass('loading-spinner active').addClass('mdi mdi-lan-disconnect');
+      $(test_but_content).removeClass('loading-spinner active').text('Connection Failed!');
     }
   }