%META:TOPICINFO{author="ProjectContributor" comment="" date="1761842198" format="1.1"  version="1"}%
%META:TOPICPARENT{name="JQueryPlugin"}%
---+!! %TOPIC%
%JQPLUGINS{"loader"
  format="
    Homepage: $homepage <br />
    Author(s): $author <br />
    Version: $version
  "
}%

%STARTSECTION{"summary"}%
This plugin allows to reload parts of a page, either automatically or manually.
%ENDSECTION{"summary"}%

%TOC%

---++ Usage

Add the =%<nop>JQREQUIRE{"loader"}%= macro to the page that you want to use this module on.
Then add the ==jqLoader== css class to the div element which will serve as
a container for the content to be loaded. Any ==jqLoader== container requires either
an ==url== or a ==section== parameter to specify the location from where to load the content.

Parameter are specified using HTML5 data, as in 

<verbatim class="html">
<div class="jqLoader" data-key1="value1" data-key2="value2" ...></div>
</verbatim>

| *Parameter* | *Description* | *Default* |
| url | the full url from where the content, e.g. =url:'%SCRIPTURL{"view"}%/MyWeb/MyTopic= | =%<nop>SCRIPTURLPATH{"view"}/&lt;web>/&lt;topic>= |
| web | the web from where to load content | current web |
| topic | the topic from where to load content | current topic |
| section | the section within the topic (see %SYSTEMWEB%.VarSTARTSECTION) | |
| caching | boolean if disabled will prevent browser caching | true |
| select | jQuery selector to extract a specific node from the retrieved data | |
| params | url parameter that are sent to the server | ={"skin":"text"}= |
| mode | specify whether the content is either loaded automatically or by clicking on the container; \
         possible values: =auto=, =manual= | =manual= |
| reload-after | reload the content after the given milliseconds | 0 |
| show-effect | the effect used when showing the loaded content; possible values are listed in [[JQueryAnimate]] | =fadeIn= |
| hide-effect | the effect when hiding the loaded content; possible values are listed in [[JQueryAnimate]] | =fadeOut= |
| delay | additional time in miliseconds to delay fetching the content from the content; specifying =0= means load the content immediately; any other value will wait that time until issuing the request | 0 |
| onload | a !JavaScript function called when the content has been loaded | |
| beforeload | a !JavaScript function called before the content is requested | |
| finished | a !JavaScript function called when the content has been loaded and displayed on the page | |

The =jqLoader= element is able to receive !JavaScript events and process them accordingly. Similarly these
events can be used to hook your own callbacks to be processed when they are fired.

| *Event* | *Description* |
| refresh.jqloader | when triggered will reload the content from the backend |
| beforeload.jqloader | is triggered before requesting the content from the backend (see =beforeload= parameter above) |
| afterload.jqloader | is triggered when the content has been successfully been loaded (see =onload= parameter above) |
| finished.jqloader | is triggered when content has been loaded and finally been displayed on the page (see =finished= parameter above) |

A button to manually trigger a loader can be defined using the =.jqLoaderButton= class:

<verbatim class="html">
%BUTTON{"Click to load" 
   icon="fa-refresh" 
   class="jqLoaderButton" 
   data_target="..." 
   data_icon_class="..." 
   data_spin_class="..."
}%
</verbatim>

| *Parameters* | *Description* | *Default* |
| target | jQuery selector to specify the loader element | next node following the button |
| icon-class | class of the icon | =fa= |
| spin-classs | class added to the icon while loading is in progress | =fa-spin= |

---++ Examples

<verbatim class="tml">
%JQREQUIRE{"loader"}%
<div class="jqLoader" data-section="recentchanges" id="myLoader">
%STARTSECTION{"recentchanges"}%%SEARCH{
    "'1'" 
    web="%BASEWEB%" 
    type="query" 
    nonoise="on" 
    order="modified" 
    reverse="on"
    limit="10"
    format="<p class='foswikiSearchResult'>[[$web.$topic]] $date - $rev - $wikiusername</p>"
}%%ENDSECTION{"recentchanges"}%
</div>
</verbatim>

... if installed:

%JQREQUIRE{"loader"}%
<div class="jqLoader" id="myLoader" data-section="recentchanges" data-effect="bounce" data-mode="auto"></div>

<div class="foswikiLeft">
  <b>Effect:</b>
  <select id="effects" class="foswikiSelect"></select>
  &nbsp;
</div>
%BUTTON{
  "%MAKETEXT{"Refresh"}%" 
  icon="fa-refresh" 
  class="jqLoaderButton"
  data_target="#myLoader"
}%
<literal>
<script>
jQuery(function($) {
   var sel = $("#effects");

   $.each($.animateCSS.EFFECTS, function(group, effects) {
      var groupElem = $("<optgroup>").attr("label", group).appendTo(sel);

      $.each(effects.sort(), function(i, val) {
         groupElem.append("<option>"+val+"</option>");
      });
   });
});
</script>
</literal>
