migrated CardRefresh (BoxRefresh)

- created CardRefresh Plugin
- created docs
- updated pages/UI/widgets.html

build/js/AdminLTE.js

@@ -5,6 +5,7 @@ import Treeview from './Treeview'
 import DirectChat from './DirectChat'
 import TodoList from './TodoList'
 import CardWidget from './CardWidget'
+import CardRefresh from './CardRefresh'
 
 export {
   ControlSidebar,
@@ -13,5 +14,6 @@ export {
   Treeview,
   DirectChat,
   TodoList,
-  CardWidget
+  CardWidget,
+  CardRefresh
 }

build/js/CardRefresh.js

@@ -0,0 +1,164 @@
+/**
+ * --------------------------------------------
+ * AdminLTE CardRefresh.js
+ * License MIT
+ * --------------------------------------------
+ */
+
+const CardRefresh = (($) => {
+  /**
+   * Constants
+   * ====================================================
+   */
+
+  const NAME               = 'CardRefresh'
+  const DATA_KEY           = 'lte.cardrefresh'
+  const EVENT_KEY          = `.${DATA_KEY}`
+  const JQUERY_NO_CONFLICT = $.fn[NAME]
+
+  const Event = {
+    LOADED: `loaded${EVENT_KEY}`,
+    OVERLAY_ADDED: `overlay.added${EVENT_KEY}`,
+    OVERLAY_REMOVED: `overlay.removed${EVENT_KEY}`,
+  }
+
+  const ClassName = {
+    CARD: 'card',
+  }
+
+  const Selector = {
+    CARD: `.${ClassName.CARD}`,
+    DATA_REFRESH: '[data-card-widget="card-refresh"]',
+  }
+
+  const Default = {
+    source: '',
+    sourceSelector: '',
+    params: {},
+    trigger: Selector.DATA_REFRESH,
+    content: '.card-body',
+    loadInContent: true,
+    loadOnInit: true,
+    responseType: '',
+    overlayTemplate: '<div class="overlay"><i class="fas fa-2x fa-sync-alt fa-spin"></i></div>',
+    onLoadStart: function () {
+    },
+    onLoadDone: function (response) {
+      return response;
+    }
+  }
+
+  class CardRefresh {
+    constructor(element, settings) {
+      this._element  = element
+      this._parent = element.parents(Selector.CARD).first()
+      this._settings = $.extend({}, Default, settings)
+      this._overlay = $(this._settings.overlayTemplate)
+
+      if (element.hasClass(ClassName.CARD)) {
+        this._parent = element
+      }
+
+      if (this._settings.source === '') {
+        throw new Error('Source url was not defined. Please specify a url in your CardRefresh source option.');
+      }
+
+      this._init();
+
+      if (this._settings.loadOnInit) {
+        this.load();
+      }
+    }
+
+    load() {
+      this._addOverlay()
+      this._settings.onLoadStart.call($(this))
+
+      $.get(this._settings.source, this._settings.params, function (response) {
+        if (this._settings.loadInContent) {
+          if (this._settings.sourceSelector != '') {
+            response = $(response).find(this._settings.sourceSelector).html()
+          }
+
+          this._parent.find(this._settings.content).html(response)
+        }
+
+        this._settings.onLoadDone.call($(this), response)
+        this._removeOverlay();
+      }.bind(this), this._settings.responseType !== '' && this._settings.responseType)
+
+      const loadedEvent = $.Event(Event.LOADED)
+      $(this._element).trigger(loadedEvent)
+    }
+
+    _addOverlay() {
+      this._parent.append(this._overlay)
+
+      const overlayAddedEvent = $.Event(Event.OVERLAY_ADDED)
+      $(this._element).trigger(overlayAddedEvent)
+    };
+
+    _removeOverlay() {
+      this._parent.find(this._overlay).remove()
+
+      const overlayRemovedEvent = $.Event(Event.OVERLAY_REMOVED)
+      $(this._element).trigger(overlayRemovedEvent)
+    };
+
+
+    // Private
+
+    _init(card) {
+      $(this).find(this._settings.trigger).on('click', () => {
+        this.load()
+      })
+    }
+
+    // Static
+
+    static _jQueryInterface(config) {
+      let data = $(this).data(DATA_KEY)
+      let options = $(this).data()
+
+      if (!data) {
+        data = new CardRefresh($(this), options)
+        $(this).data(DATA_KEY, typeof config === 'string' ? data: config)
+      }
+
+      if (typeof config === 'string' && config.match(/load/)) {
+        data[config]()
+      } else if (typeof config === 'object') {
+        data._init($(this))
+      }
+    }
+  }
+
+  /**
+   * Data API
+   * ====================================================
+   */
+
+  $(document).on('click', Selector.DATA_REFRESH, function (event) {
+    if (event) {
+      event.preventDefault()
+    }
+
+    CardRefresh._jQueryInterface.call($(this), 'load')
+  })
+
+  /**
+   * jQuery API
+   * ====================================================
+   */
+
+  $.fn[NAME] = CardRefresh._jQueryInterface
+  $.fn[NAME].Constructor = CardRefresh
+  $.fn[NAME].noConflict  = function () {
+    $.fn[NAME] = JQUERY_NO_CONFLICT
+    return CardRefresh._jQueryInterface
+  }
+
+  return CardRefresh
+})(jQuery)
+
+export default CardRefresh

docs/_config.yml

@@ -64,8 +64,8 @@ navigation:
       url: javascript/treeview.html
     - title: Card Widget
       url: javascript/card-widget.html
-    # - title: CardRefresh
+    - title: CardRefresh
-    #   url: javascript/card-refresh.html
+      url: javascript/card-refresh.html
     - title: Control Sidebar
       url: javascript/control-sidebar.html
     - title: Direct Chat

docs/javascript/card-refresh.md

@@ -0,0 +1,85 @@
+---
+layout: page
+title: Card Refresh Plugin
+---
+
+The card refresh plugin provides the functionality for loading ajax content into the card. 
+
+##### Usage
+This plugin can be activated as a jQuery plugin or using the data api. 
+
+###### Data API
+{: .text-bold }
+
+Activate the plugin by adding a button with `data-card-widget="card-refresh"` to the card and provide the required `data-source="/URL-TO-CONTENT"` option. By doing that, the plugin will automatically create a GET request to the provided URL and render the returned response the `.card-body` section of the card. If you need to process the returned response before rendering, you should use the jQuery API, which provides hooks to deal with the response. 
+
+
+
+###### jQuery
+{: .text-bold }
+The jQuery API provides more customizable options that allows the developer to pre-process the request before rendering and post-process it after rendering. 
+
+```js
+("#my-card").refreshBox(options)
+```
+
+##### Options
+{: .mt-4}
+
+|---
+| Name | Type | Default | Description
+|-|-|-|-
+
+
+    source: '',
+    sourceSelector: '',
+    params: {},
+    trigger: Selector.DATA_REFRESH,
+    content: '.card-body',
+    loadInContent: true,
+    loadOnInit: true,
+    responseType: '',
+    overlayTemplate: '<div class="overlay"><i class="fas fa-2x fa-sync-alt fa-spin"></i></div>',
+    onLoadStart: function () {
+    },
+    onLoadDone: function (response) {
+      return response;
+    }
+
+| source | String | '' | The URL to the source.
+| sourceSelector | String | '' | A selector to get return only the content of the selector.
+| params | Object | {} | GET query paramaters (example: {search_term: 'layout'}, which renders to URL/?search_term=layout)
+| trigger | String | `[data-card-widget="card-refresh"]` | The CSS selector to the refresh button
+| content | String | `.card-body` | The CSS selector to the target where the content should be rendered. This selector should exist within the card.
+| loadInContent | Boolean | TRUE | Whether to automatically render the content.
+| loadOnInit | Boolean | TRUE | Init plugin on page load.
+| responseType | String | '' | Response type (example: 'json' or 'html')
+| overlayTemplate | String | TRUE | The HTML template for the ajax spinner
+| onLoadStart | Function | Anonymous Function | Called before the ajax request is made
+| onLoadDone | Function | Anonymous Function | Called after the ajax request is made. A `response` parameter is passed to the function that hold the server response. 
+{: .table .table-bordered .bg-light}
+
+##### Events
+{: .mt-4}
+
+|---
+| Event Type | Description
+|-|-
+|loaded.lte.cardrefresh | Triggered after a card is refreshed.
+|overlay.added.lte.cardrefresh | Triggered after the overlay added to the card.
+|overlay.removed.lte.cardrefresh | Triggered after the overlay removed from the card.
+{: .table .table-bordered .bg-light}
+
+Example: `$('#my-card [data-card-widget="card-refresh"]').on('loaded.lte.cardrefresh', handleLoadedEvent)`
+
+
+##### Methods
+{: .mt-4}
+
+|---
+| Method | Description
+|-|-
+|load | Reloads the content and runs the `onLoadStart` and `onLoadDone` hooks
+{: .table .table-bordered .bg-light}
+
+Example: `$('#my-card-widget').Widget('toggle')`

pages/widgets.html

@@ -1050,10 +1050,33 @@
         <div class="row">
           <div class="col-md-3">
             <div class="card card-primary">
+              <div class="card-header">
+                <h3 class="card-title">Card Refresh</h3>
+
+                <div class="card-tools">
+                  <button type="button" class="btn btn-tool" data-card-widget="card-refresh" data-source="/pages/widgets.html" data-source-selector="#card-refresh-content"><i class="fas fa-sync-alt"></i></button>
+                </div>
+                <!-- /.card-tools -->
+              </div>
+              <!-- /.card-header -->
+              <div class="card-body">
+                The body of the card
+              </div>
+              <!-- /.card-body -->
+            </div>
+            <!-- /.card -->
+            <div class="d-none" id="card-refresh-content">
+                The body of the card after card refresh
+            </div>
+          </div>
+          <!-- /.col -->
+          <div class="col-md-3">
+            <div class="card card-success">
               <div class="card-header">
                 <h3 class="card-title">All together</h3>
 
                 <div class="card-tools">
+                  <button type="button" class="btn btn-tool" data-card-widget="card-refresh" data-source="/pages/widgets.html" data-source-selector="#card-refresh-content"><i class="fas fa-sync-alt"></i></button>
                   <button type="button" class="btn btn-tool" data-card-widget="maximize"><i class="fas fa-expand"></i></button>
                   <button type="button" class="btn btn-tool" data-card-widget="collapse"><i class="fas fa-minus"></i></button>
                   <button type="button" class="btn btn-tool" data-card-widget="remove"><i class="fas fa-times"></i></button>
@@ -1070,7 +1093,7 @@
           </div>
           <!-- /.col -->
           <div class="col-md-3">
-            <div class="card card-success">
+            <div class="card card-warning">
               <div class="card-header">
                 <h3 class="card-title">Loading state</h3>
               </div>
@@ -1088,7 +1111,7 @@
           </div>
           <!-- /.col -->
           <div class="col-md-3">
-            <div class="card card-warning">
+            <div class="card card-danger">
               <div class="card-header">
                 <h3 class="card-title">Loading state (dark)</h3>
               </div>