From 1aa67a08ea15ced94687264840ea1fdda455f638 Mon Sep 17 00:00:00 2001 From: REJack Date: Tue, 20 Aug 2019 17:19:08 +0200 Subject: [PATCH] migrated CardRefresh (BoxRefresh) - created CardRefresh Plugin - created docs - updated pages/UI/widgets.html --- build/js/AdminLTE.js | 4 +- build/js/CardRefresh.js | 164 ++++++++++++++++++++++++++++++++ docs/_config.yml | 4 +- docs/javascript/card-refresh.md | 85 +++++++++++++++++ pages/widgets.html | 27 +++++- 5 files changed, 279 insertions(+), 5 deletions(-) create mode 100644 build/js/CardRefresh.js create mode 100644 docs/javascript/card-refresh.md diff --git a/build/js/AdminLTE.js b/build/js/AdminLTE.js index 7d60a641a..04df64f67 100644 --- a/build/js/AdminLTE.js +++ b/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 } diff --git a/build/js/CardRefresh.js b/build/js/CardRefresh.js new file mode 100644 index 000000000..3f01929f6 --- /dev/null +++ b/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: '
', + 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 diff --git a/docs/_config.yml b/docs/_config.yml index 407e777bd..aac9c1c2d 100755 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -64,8 +64,8 @@ navigation: url: javascript/treeview.html - title: Card Widget url: javascript/card-widget.html - # - title: CardRefresh - # url: javascript/card-refresh.html + - title: CardRefresh + url: javascript/card-refresh.html - title: Control Sidebar url: javascript/control-sidebar.html - title: Direct Chat diff --git a/docs/javascript/card-refresh.md b/docs/javascript/card-refresh.md new file mode 100644 index 000000000..39f82b6f7 --- /dev/null +++ b/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: '
', + 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')` diff --git a/pages/widgets.html b/pages/widgets.html index 39d155135..508285117 100644 --- a/pages/widgets.html +++ b/pages/widgets.html @@ -1050,10 +1050,33 @@
+
+

Card Refresh

+ +
+ +
+ +
+ +
+ The body of the card +
+ +
+ +
+ The body of the card after card refresh +
+
+ +
+

All together

+ @@ -1070,7 +1093,7 @@
-
+

Loading state

@@ -1088,7 +1111,7 @@
-
+

Loading state (dark)