@cable8mm/jquery-infinite-with-template 1.0.3 → 1.1.2

package/README.md

@@ -1,219 +1,334 @@
-jQuery Infinite With Template Plugin
-======================
+# ⚡ jQuery Infinite With Template Plugin
 
-JQuery plugin for ajax-enabled infinite page scroll with template.
+[![NPM Version](https://img.shields.io/npm/v/%40cable8mm%2Fjquery-infinite-with-template)](https://www.npmjs.com/package/@cable8mm/jquery-infinite-with-template)
+[![npm bundle size](https://img.shields.io/bundlephobia/minzip/%40cable8mm%2Fjquery-infinite-with-template)](https://bundlephobia.com/package/@cable8mm/jquery-infinite-with-template)
+[![NPM Downloads](https://img.shields.io/npm/dt/%40cable8mm%2Fjquery-infinite-with-template)](https://www.npmjs.com/package/@cable8mm/jquery-infinite-with-template)
+[![jsDelivr hits (npm)](https://img.shields.io/jsdelivr/npm/hy/%40cable8mm%2Fjquery-infinite-with-template)](https://www.jsdelivr.com/package/npm/@cable8mm/jquery-infinite-with-template)
+[![NPM Type Definitions](https://img.shields.io/npm/types/%40cable8mm%2Fjquery-infinite-with-template)](https://www.npmjs.com/package/@cable8mm/jquery-infinite-with-template)
+[![NPM License](https://img.shields.io/npm/l/%40cable8mm%2Fjquery-infinite-with-template)](https://opensource.org/licenses/MIT)
+[![GitHub stars](https://img.shields.io/github/stars/cable8mm/jquery-infinite-with-template)](https://github.com/cable8mm/jquery-infinite-with-template)
+[![GitHub issues](https://img.shields.io/github/issues/cable8mm/jquery-infinite-with-template)](https://github.com/cable8mm/jquery-infinite-with-template/issues)
 
-If you like jQuery until now, this little library will help.
+> 🚀 **AJAX-powered infinite scroll with template rendering for jQuery**
 
-## Demo
+If you like jQuery until now, this little library will help you implement infinite scroll with ease.
 
-For convinient `http-server` need:
+## ✨ Features
 
-```bash
-git clone https://github.com/cable8mm/jquery-infinite-with-template
+- ⚡ **Zero Dependencies** (except jQuery & jsRender)
+- 🎨 **Template Rendering** with jsRender
+- 🔄 **Dual Loading Modes** - Scroll or Click
+- 🎯 **TypeScript Support** out of the box
+- 🛡️ **Error Handling** with callbacks
+- ⚙️ **Highly Configurable** with 12+ options
+- 🚀 **Performance Optimized** with DocumentFragment
+- 📦 **Lightweight** - Only ~3KB minified
+- ✅ **Well Tested** - 16 unit tests included
+
+## 📦 Installation
+
+### npm
+
+```sh
+npm i @cable8mm/jquery-infinite-with-template
+```
 
-cd jquery-infinite-with-template
+### CDN
 
-http-server .
+```html
+<script
+  src="https://cdn.jsdelivr.net/npm/@cable8mm/jquery-infinite-with-template@1.0.4/jquery.infiniteScrollWithTemplate.min.js"
+  integrity="sha256-bX3iyCp0T50YmDRgpUl1tY/LGlpPGsKR4TqUkpcq6WA="
+  crossorigin="anonymous"
+></script>
 ```
 
-and visit http://127.0.0.1:8080/examples/
+### ESM
+
+```html
+<script type="module">
+  import @cable8mm/jquery-infinite-with-template from https://cdn.jsdelivr.net/npm/@cable8mm/jquery-infinite-with-template@1.0.4/+esm
+</script>
+```
 
-If you are not installed `http-server`, refer to https://www.npmjs.com/package/http-server
+## 🎬 Demo
 
-You can regenerate data_sources:
+### Online Demo
+
+You can test the plugin directly in your browser:
+
+👉 **[https://www.palgle.com/jquery-infinite-with-template/examples/index.html](https://www.palgle.com/jquery-infinite-with-template/examples/index.html)**
+
+### Quick Start
+
+#### Using npm run dev (Recommended)
 
 ```bash
-# permission required
-./examples/generate > data_sources.ajax
+# Install dependencies (one-time)
+npm install
+
+# Run development server with auto-open
+npm run dev
 ```
 
-## Usage sample
+**Note:** This will start the server at `http://127.0.0.1:8080/examples/index.html` and automatically open it in your browser.
 
-Javascript part:
+Visit [http://127.0.0.1:8080/examples/index.html](http://127.0.0.1:8080/examples/index.html) in your browser.
 
-```Javascript
-$("#result").infiniteTemplate({
-	templateSelector: "#test-tmpl",
-	dataPath: "data_sources.ajax",
-	query: "word=ajax",
-	templateHelpers: {
-		authId : 354
-	},
-    zeroCallback: function () {
-        alert("zero alert");
-    },
-});
+### Regenerate Demo Data
+
+```bash
+# Using PHP CLI
+php examples/generate > examples/data_sources.json
+
+# Or if you have the generate script in examples directory
+cd examples
+php generate > data_sources.json
 ```
 
-HTML part:
+## 🚀 Usage
+
+### Basic Example
+
+**HTML:**
 
 ```html
 <div id="result"></div>
 
 <script id="test-tmpl" type="text/x-jsrender">
-	<p>{{:id}}. {{:title}} [user:{{:authId}}]</p>
+  <div class="item">
+    <h3>{{:title}}</h3>
+    <p>ID: {{:id}}</p>
+  </div>
 </script>
 ```
 
-AJAX part: `data_sources.ajax`. This should return Ajax:
+**JavaScript:**
 
 ```javascript
+$("#result").infiniteTemplate({
+  templateSelector: "#test-tmpl",
+  dataPath: "/api/posts",
+  query: "category=tech",
+  templateHelpers: {
+    userId: 123,
+  },
+  zeroCallback: function () {
+    console.log("No more posts!");
+  },
+});
+```
+
+**Server Response (JSON):**
+
+```json
 {
-	"data": [
-	{
-		"id": 885,
-		"title": "iGFIJUSPp8oXoBDqoRXKK0VEAU0IBG(word=ajax)"
-	},
-	{
-		"id": 277,
-		"title": "HM3iPLDwd3nQKNH5eOkaOh5QlSb92F(word=ajax)"
-	},
-	{
-		"id": 583,
-		"title": "O2X0VQeWFGIRQPcVquYwHx49VNhwX3(word=ajax)"
-	},
-...even more rows
+  "data": [
+    {
+      "id": 1,
+      "title": "Getting Started with jQuery",
+      "content": "..."
+    },
+    {
+      "id": 2,
+      "title": "Advanced JavaScript Patterns",
+      "content": "..."
+    }
+  ]
 }
 ```
 
-Result:
+### Click-to-Load Button
 
-```html
-<div id="result">
-	<p>885. iGFIJUSPp8oXoBDqoRXKK0VEAU0IBG(word=ajax) [user:354]</p>
-	<p>277. HM3iPLDwd3nQKNH5eOkaOh5QlSb92F(word=ajax) [user:354]</p>
-	<p>583. O2X0VQeWFGIRQPcVquYwHx49VNhwX3(word=ajax) [user:354]</p>
-	<p>179. vrEwi7hgVucCEDmuO7pOf4Gzk4gmyh(word=ajax) [user:354]</p>
-	<p>380. yviF2uDLyySLZaAPs3bKNbSZfHeQA7(word=ajax) [user:354]</p>
-	<p>329. 865t05x9DMngrETccBuqrY7ts9Xt3R(word=ajax) [user:354]</p>
-	<p>84. D6mhKuRA06ONCE5HbswSwPjZvp0bUh(word=ajax) [user:354]</p>
-	<p>528. saWL46OBtTDGIBuZL9TkmfBvPXiRqM(word=ajax) [user:354]</p>
-	<p>522. PBe0jjP1Egy6NWpHzuA86JHupxNGvc(word=ajax) [user:354]</p>
-	<p>115. vBmfL7osq2VAKIktVznrC6QZzYpc1H(word=ajax) [user:354]</p>
-	<p>722. mti7aMut4TxAygKAdfGylml9QgJoDN(word=ajax) [user:354]</p>
-	<p>401. 06kgapSQylxWJOvFmDNLIcvpSPMB7V(word=ajax) [user:354]</p>
-	<p>245. UD0TP3bMU7J4mAlGqwo52F1I0rJIyR(word=ajax) [user:354]</p>
-	<p>985. 3xSyr0m68K3Ec6y8vJgIhYgSfgcGnG(word=ajax) [user:354]</p>
-	<p>78. DWpWRzx1x4Ibfh1Gn0Lk0F3aufu34d(word=ajax) [user:354]</p>
-	<p>573. iINBTozeMIeZguTU6lLB9j76zNZ4AK(word=ajax) [user:354]</p>
-	<p>946. OEuUblddtI9vqlyL89nDXizhvryn4e(word=ajax) [user:354]</p>
-	<p>756. wsBL8dxDf6UjTiNWNnnX4XAlAonHBM(word=ajax) [user:354]</p>
-	<p>66. q3irGi5lNUXccTDTDfl2jRlzVp04uk(word=ajax) [user:354]</p>
-	<p>20. vcq8sKN4RhCEoFLVW2vbX2eR14EKp8(word=ajax) [user:354]</p>
-</div>
+```javascript
+$("#result").infiniteTemplate({
+  templateSelector: "#item-template",
+  dataPath: "/api/items",
+  loadSelector: "#load-more-btn", // Click this button to load more
+  loadAtStart: false, // Don't load automatically
+});
 ```
 
-## Options
+### With Error Handling
 
-**templateSelector** - (required) jsRender template identify
+```javascript
+$("#result").infiniteTemplate({
+  templateSelector: "#item-template",
+  dataPath: "/api/items",
+  errorCallback: function (error) {
+    console.error("Failed to load:", error);
+    alert("Something went wrong. Please try again.");
+  },
+  loadingCallback: function () {
+    $("#loading").show();
+  },
+  loadedCallback: function () {
+    $("#loading").hide();
+  },
+});
+```
 
-**dataPath** - (required) URL to load more data via AJAX
+## 📋 Options
+
+| Option               | Type       | Default      | Description                                                  |
+| -------------------- | ---------- | ------------ | ------------------------------------------------------------ |
+| **templateSelector** | `string`   | **required** | jsRender template selector (e.g., `"#my-template"`)          |
+| **dataPath**         | `string`   | **required** | URL to load data via AJAX                                    |
+| **key**              | `string`   | `"data"`     | Key for data array in JSON response                          |
+| **query**            | `string`   | `null`       | Additional query parameters (e.g., `"category=1&sort=date"`) |
+| **method**           | `string`   | `"GET"`      | HTTP method (GET, POST, PUT, DELETE)                         |
+| **templateHelpers**  | `object`   | `null`       | Helper data merged with each item                            |
+| **loadAtStart**      | `boolean`  | `true`       | Load data on initialization                                  |
+| **loadSelector**     | `string`   | `null`       | CSS selector for click-to-load button                        |
+| **initialPage**      | `number`   | `1`          | Initial page number                                          |
+| **preventCache**     | `boolean`  | `false`      | Add timestamp to prevent caching                             |
+| **scrollThreshold**  | `number`   | `2`          | Multiplier for viewport height (lower = more sensitive)      |
+| **zeroCallback**     | `function` | `null`       | Called when no data returned on first page                   |
+| **errorCallback**    | `function` | `null`       | Called on AJAX or JSON parse error                           |
+| **loadingCallback**  | `function` | `null`       | Called when loading starts                                   |
+| **loadedCallback**   | `function` | `null`       | Called when loading completes (success or error)             |
+
+## 🎯 Real-World Examples
+
+### Example 1: Blog Posts with Pagination
 
-**templateHelpers** - (optional) Merge with json to load
+```javascript
+$("#post-list").infiniteTemplate({
+  templateSelector: "#post-template",
+  dataPath: "/api/posts",
+  query: "status=published",
+  initialPage: 1,
+  scrollThreshold: 1.5,
+  templateHelpers: {
+    currentUser: window.currentUser,
+  },
+  loadingCallback: () => $("#spinner").show(),
+  loadedCallback: () => $("#spinner").hide(),
+  zeroCallback: () => $("#end-message").show(),
+});
+```
 
-**key** - (optional) data(default)
+### Example 2: E-commerce Product Grid
 
-**query** - (optional) Additional query
+```javascript
+$("#product-grid").infiniteTemplate({
+  templateSelector: "#product-card",
+  dataPath: "/api/products",
+  query: "category=electronics&sort=price",
+  loadSelector: "#load-more-products",
+  loadAtStart: true,
+  templateHelpers: {
+    currency: "$",
+    discountRate: 0.1,
+  },
+});
+```
 
-**method** - (optional) GET(default), POST, PUT, DELETE
+### Example 3: Social Media Feed
 
-**loadAtStart** - (optional) true(default), false
+```javascript
+$("#feed").infiniteTemplate({
+  templateSelector: "#feed-item",
+  dataPath: "/api/feed",
+  method: "POST",
+  query: "filter=following",
+  initialPage: 3,
+  preventCache: true,
+  templateHelpers: {
+    currentUserId: Auth.id(),
+    likedPosts: Auth.likedPosts(),
+  },
+});
+```
 
-**loadSelector** - (optional) if it set, it load more data every time the selector clicked
+### Example 4: Search Results
 
-**initialPage** - (optional) 1(default)
+```javascript
+$("#search-results").infiniteTemplate({
+  templateSelector: "#result-item",
+  dataPath: "/api/search",
+  query: `q=${encodeURIComponent(searchQuery)}`,
+  zeroCallback: () => {
+    $("#no-results").show();
+  },
+  errorCallback: (error) => {
+    console.error("Search failed:", error);
+  },
+});
+```
 
-**preventCache** - (optional) false(default) if true, Add timestamp
+## 🏗️ Project Structure
+
+```text
+jquery-infinite-with-template/
+├── jquery.infiniteScrollWithTemplate.js  # Main plugin (unminified)
+├── jquery.infiniteScrollWithTemplate.min.js  # Minified version
+├── jquery.infiniteScrollWithTemplate.d.ts  # TypeScript definitions
+├── package.json
+├── README.md
+├── LICENSE
+├── examples/
+│   ├── index.html          # Demo page
+│   ├── data_sources.json   # Demo data
+│   └── generate            # Data generator script
+└── tests/
+    ├── setup.js            # Test configuration
+    └── jquery.infiniteScrollWithTemplate.test.js  # 16 unit tests
+```
 
-**zeroCallback** - (optional) null(default) if function, call zeroCallback when result is nothing
+## 🧪 Testing
 
-## Examples
+```bash
+# Install dependencies
+npm install
 
-```html
-// https://m.holapet.com/adoption
-
-<x-adoption.rounded-card-list :selector="'adoption-rounded-card-list'">
-    @foreach($adoptions as $item)
-    <x-adoption.rounded-card :item="$item" />
-    @endforeach
-</x-adoption.rounded-card-list>
-<x-adoption.rounded-card-tmpl />
-<script>
-    $("#adoption-rounded-card-list").infiniteTemplate({
-        templateSelector: "#adoption-rounded-card-tmpl",
-        dataPath: "/api/adoption",
-        initialPage: 3,
-    });
-</script>
+# Run tests
+npm test
 ```
 
-```html
-// https://m.holapet.com/place/pensions/region/1
-
-<x-place.rounded-card-list :selector="'place-rounded-card-list'">
-    @foreach($region->placesRecent as $item)
-    <x-place.rounded-card :item="$item" />
-    @endforeach
-</x-place.rounded-card-list>
-<x-place.rounded-card-tmpl />
-<script>
-    $("#place-rounded-card-list").infiniteTemplate({
-        templateSelector: "#place-rounded-card-tmpl",
-        dataPath: "/api/place/pensions/region/{{ $region->id }}",
-        initialPage: 3,
-        templateHelpers: {
-            minColumnCount: 1
-        }
-    });
-</script>
-```
+**Test Coverage:**
 
-```html
-// https://m.holapet.com/search/show?word=%ED%8F%AC%EB%A9%94%EB%9D%BC%EB%8B%88%EC%95%88
-
-@include('shared.jtemplate.search-user')
-
-@auth
-<script>
-    $("#user-list").infiniteTemplate({
-        templateSelector: "#user-tmpl",
-        dataPath: "/api/user",
-        query: "word={{ $word }}",
-        templateHelpers: {
-            authId : {{ Auth::id() ?? 0 }},
-            followeeIds: {!! Auth::user()->followee_ids->toJson() ?? 'false' !!}
-        }
-    });
-</script>
-@endauth
-@guest
-<script>
-    $("#user-list").infiniteTemplate({
-        templateSelector: "#user-tmpl",
-        dataPath: "/api/user",
-        query: "word={{ $word }}",
-    });
-</script>
-@endguest
-```
+- ✅ Initialization & validation
+- ✅ Data loading & rendering
+- ✅ Callbacks (zero, error, loading, loaded)
+- ✅ Scroll & click loading modes
+- ✅ URL building & pagination
+- ✅ Edge cases (empty data, JSON parsing)
 
-```html
-// https://m.holapet.com/story/hot
-
-@if(!empty($hotStories))
-<x-story.grid-card-list :selector="'story-grid-card-list'">
-    @foreach($hotStories as $item)
-    <x-story.grid-card :item="$item" />
-    @endforeach
-</x-story.grid-card-list>
-@endif
-<x-story.grid-card-tmpl />
-<script>
-    $("#story-grid-card-list").infiniteTemplate({
-        templateSelector: "#story-grid-card-tmpl",
-        dataPath: "/api/story/hot",
-        initialPage: 3,
-    });
-</script>
-```
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+1. Fork the project
+2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
+3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
+4. Push to the branch (`git push origin feature/AmazingFeature`)
+5. Open a Pull Request
+
+## 📝 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## 🙏 Credits
+
+- **jsRender** - Template engine
+- **jQuery** - DOM manipulation
+
+## 💡 Tips for Getting Stars
+
+- ⭐ Star this repo if you find it useful!
+- 🐛 Report bugs and request features
+- 📢 Share with your developer friends
+- 💬 Leave feedback and suggestions
+
+## 🔗 Links
+
+- **GitHub**: [https://github.com/cable8mm/jquery-infinite-with-template](https://github.com/cable8mm/jquery-infinite-with-template)
+- **NPM**: [https://www.npmjs.com/package/@cable8mm/jquery-infinite-with-template](https://www.npmjs.com/package/@cable8mm/jquery-infinite-with-template)
+- **Issues**: [https://github.com/cable8mm/jquery-infinite-with-template/issues](https://github.com/cable8mm/jquery-infinite-with-template/issues)
+
+---
+
+**Made with ❤️ by [Sam Lee](https://github.com/cable8mm)**
+
+If this project helped you, please give it a ⭐️!

package/examples/data_sources.json

@@ -0,0 +1,84 @@
+{
+  "data": [
+    {
+      "id": 886,
+      "title": "ZjLn9jCi1w8nsFSye6A2q9cuu78U88(word=None)"
+    },
+    {
+      "id": 91,
+      "title": "VVTFOrWminUAi8E3whuFiyi76sf6L3(word=None)"
+    },
+    {
+      "id": 654,
+      "title": "Roc3yFmOHpm4Koj8hhuRr5fBNAUcxZ(word=None)"
+    },
+    {
+      "id": 788,
+      "title": "zR7rzbUz81pPYFxvm3NBDFGCUqB0cy(word=None)"
+    },
+    {
+      "id": 7,
+      "title": "1OHxyIMH9DahoskhqVbCFINH3aVysn(word=None)"
+    },
+    {
+      "id": 915,
+      "title": "9kX2B97YL0onvcE4nRETuACESX9YIM(word=None)"
+    },
+    {
+      "id": 125,
+      "title": "jc5fTJ5Y1QzYOtQy6XhiMlRxq05KAc(word=None)"
+    },
+    {
+      "id": 362,
+      "title": "rsoNXzq590AQzf6Hp0Gi8rHQfaz9KI(word=None)"
+    },
+    {
+      "id": 101,
+      "title": "1msDlWisPm0Q9oUofPdhgjOHuZtlep(word=None)"
+    },
+    {
+      "id": 206,
+      "title": "nev0CvpOKc1E0zUuvTrgMUluSowoz5(word=None)"
+    },
+    {
+      "id": 544,
+      "title": "aIMdZ9LAf5SDl9hmeFIqzCMgU2joOx(word=None)"
+    },
+    {
+      "id": 415,
+      "title": "ikYBbV7nA4S2LPCWk2TYXQ4H5Vp7ia(word=None)"
+    },
+    {
+      "id": 717,
+      "title": "H6u32LKXqbgU8rx7UTjsALjKfUPZru(word=None)"
+    },
+    {
+      "id": 536,
+      "title": "JuyIiHNlLn0H97APMtB5ng72GAVzBr(word=None)"
+    },
+    {
+      "id": 554,
+      "title": "e8cbqBh9ifoEI2nFqyryDBwE87Boy2(word=None)"
+    },
+    {
+      "id": 111,
+      "title": "yCJNeoMlqkuNazccgeKwMoj2d9xC6v(word=None)"
+    },
+    {
+      "id": 134,
+      "title": "2qZpgg3lJ3djS5RG5IZzZjdtf7Y9IJ(word=None)"
+    },
+    {
+      "id": 523,
+      "title": "LC84RteVTWGuAgDDhknpb7jREpqdfY(word=None)"
+    },
+    {
+      "id": 946,
+      "title": "q0NnpnSWosOwbxIYQE3ZiMbuqJKG40(word=None)"
+    },
+    {
+      "id": 30,
+      "title": "sHc5R2u1W0T45AMxQRx73gAFbGHXk0(word=None)"
+    }
+  ]
+}

package/examples/generate

@@ -2,36 +2,80 @@
 <?php
 
 /**
- * @example ./generate > data_sources.ajax generate new data sources
+ * jQuery Infinite With Template - Demo Data Generator
+ *
+ * @example ./generate > data_sources.json
+ * @description Generates random demo data for testing infinite scroll
  */
 
-$response['data'] = [];
+// Enable error reporting for debugging
+error_reporting(E_ALL);
+ini_set('display_errors', 0);
 
-$query = $_GET['word'] ?? 'None';
+// Set JSON header
+header('Content-Type: application/json');
 
-for ($i = 0; $i < 20; $i++) {
-    $response['data'][] = faker($query);
-}
+// Get query parameter (default to 'None' if not provided)
+$query = isset($_GET['word']) ? $_GET['word'] : 'None';
 
-header('Content-Type: application/json');
+// Generate response
+$response = [
+    'data' => [],
+    'page' => isset($_GET['page']) ? (int)$_GET['page'] : 1,
+    'total' => 100 // Simulate total count
+];
 
-echo json_encode($response, JSON_PRETTY_PRINT);
+// Generate 20 items per page
+$itemsPerPage = 30;
+for ($i = 0; $i < $itemsPerPage; $i++) {
+    $response['data'][] = generateItem($query, $response['page'], $i);
+}
 
-function faker($query)
+// Output JSON
+echo json_encode($response, JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE);
+
+/**
+ * Generate a single fake item
+ *
+ * @param string $query Search query
+ * @param int $page Current page number
+ * @param int $index Item index within page
+ * @return array Generated item
+ */
+function generateItem($query, $page, $index)
 {
+    static $usedIds = [];
+
+    // Generate unique ID
+    do {
+        $id = rand(1, 10000);
+    } while (in_array($id, $usedIds));
+
+    $usedIds[] = $id;
+
     return [
-        'id' => rand(1, 1000),
-        'title' => generateRandomString(30)."(word=$query)",
+        'id' => $id,
+        'title' => generateRandomString(30) . "(word=$query, page=$page)",
+        'page' => $page,
+        'index' => $index
     ];
 }
 
+/**
+ * Generate random string of specified length
+ *
+ * @param int $length String length
+ * @return string Random string
+ */
 function generateRandomString($length = 10)
 {
     $characters = '0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ';
     $charactersLength = strlen($characters);
     $randomString = '';
+
     for ($i = 0; $i < $length; $i++) {
         $randomString .= $characters[rand(0, $charactersLength - 1)];
     }
+
     return $randomString;
 }