https://github.com/thomasdev-de/bs-layer
https://github.com/thomasdev-de/bs-layer
Last synced: 5 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/thomasdev-de/bs-layer
- Owner: ThomasDev-de
- License: mit
- Created: 2025-07-15T08:14:28.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2025-07-15T21:49:22.000Z (11 months ago)
- Last Synced: 2025-07-16T00:54:39.433Z (11 months ago)
- Size: 15.6 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# bs-layer
A lightweight sliding layer system for jQuery and Bootstrap 5.
Supports stacking multiple layers, custom AJAX content, animation, and full keyboard support.
---
## Features
- Stackable sliding layers (like modals, but multi-level)
- Smooth open/close animations
- AJAX content loading support
- Close all layers with a single call, stacked "top-down"
- Callback support for all key events
- Full Bootstrap 5 compatibility
- Easily extensible with custom logic
---
## Installation
Install with Composer (Bootstrap 5, Bootstrap-Icons & jQuery must be present):
```
composer require twbs/bootstrap twbs/bootstrap-icons components/jquery
```
**Or include JS/CSS manually:**
```html
```
---
## Getting Started
**HTML Example:**
```html
Open layer
```
**JavaScript Usage:**
```javascript
// Initialize a layer trigger
const layerLogin = $('#layerLogin').bsLayer({
name: 'login-layer',
// url: 'login.html',
onPostBody: function ($content) {
// Callback after content loaded
}
});
// You can send your own events to the layer
$.bsLayer.customEvent('login-layer', 'event-name', ...params);
// Or close all layers with once
$.bsLayer.closeAll();
```
---
## API
### Global Configuration
Global configuration options control the technical behavior and default appearance of **all** layers.
They are set on the `$.bsLayer.config` object and can be changed at runtime using `$.bsLayer.setConfig()`.
These settings affect AJAX requests, default breakpoints, animation speed, stacking order, and icon classes.
Changes to the global config apply to all subsequently created layers unless overridden per-layer.
See the table below for all available global configuration options:
| Option | Type | Default / Example | Description |
|-------------------------|----------|----------------------------------------------------|------------------------------------------------------------------------------------|
| ajax.method | string | 'GET' | HTTP method used for AJAX requests (usually 'GET' or 'POST') |
| ajax.contentType | string | 'application/x-www-form-urlencoded; charset=UTF-8' | Content-Type for AJAX submissions |
| fullWidthBreakpoint | number | 576 | Below this window width (px), layers use 100% of width (Bootstrap 'sm' breakpoint) |
| firstLayerWithInPercent | number | 0.80 | Percentage (e.g. 0.8 = 80%) of window width for first layer |
| distanceBetweenLayers | number | 100 | Distance in px between stacked layers |
| animationDuration | number | 600 | Show/hide animation duration in milliseconds |
| zIndexStart | number | 1050 | z-index for bottom-most layer; each additional layer is placed higher |
| parent | string | 'body' | CSS selector: Where layers are appended in the DOM |
| icons.close | string | 'bi bi-x-lg' | Icon class for the close (X) button (Bootstrap Icons) |
| icons.refresh | string | 'bi bi-arrow-clockwise' | Icon class for refresh button |
| icons.maximize | string | 'bi bi-arrows-angle-expand' | Icon class for maximize button |
| icons.minimize | string | 'bi bi-arrows-angle-contract' | Icon class for minimize button |
| onError | function | `function($message) {}` | Global error handler; called on AJAX or layer errors |
**Usage Example:**
```javascript
// Example: Centrally adjust global configuration for all layers
$.bsLayer.setConfig({
fullWidthBreakpoint: 768, // Default is 576, here changed to 768 px
animationDuration: 400, // Layer animation now lasts 400 ms
icons: {
close: 'bi bi-x',
maximize: 'bi bi-fullscreen',
minimize: 'bi bi-fullscreen-exit',
refresh: 'bi bi-arrow-clockwise'
}
});
// Optional: Overwrite the global onError callback function
$.bsLayer.onError = function ($msg) {
// Custom error handling
alert('Layer error: ' + $msg);
};
```
---
### Layer Settings
Layer settings define the configuration and behavior of **individual layers**.
They can be passed when initializing a layer via `$(selector).bsLayer(options)` or set as `data-` attributes on the
layer trigger element.
These settings control properties such as title, width, styles, AJAX URL, refreshability, closing/maximizing, and all
event callbacks.
Any setting not explicitly defined will fall back to the global defaults.
See the table below for all available settings you can use per layer:
| Option | Type | Default / Example | Description |
|-----------------------|------------------------------|--------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| name | string | 'layer01' | Unique layer name or identifier |
| title | string/HTML | undefined | Optional: Layer title (can be string or HTML) |
| width | number/string | undefined | Optional: Width in px or as CSS string |
| bgStyle | object | `{ classes: 'text-dark', css: {...} }` | Style for background and text color (see below) |
| ↳ classes | string | 'text-dark' | Additional CSS classes for the layer |
| ↳ css | object | `{ background: ..., boxShadow: ..., ... }` | Inline CSS styles for the layer background |
| backdrop | bool/string | true | Show backdrop: `true`, `false`, or `'static'` |
| url | string \| Function (Promise) | undefined | URL für AJAX-Inhalte **oder** Funktion/Promise für asynchronen Content. Falls eine Funktion verwendet wird, bekommt sie ein `params`-Objekt übergeben (die von `queryParams` zurückgegebenen/erweiterten Parameter). Die Funktion muss ein Promise zurückgeben, welches mit dem gewünschten Content (HTML/String oder Daten) aufgelöst wird. || refreshable | bool | false | Enable content refresh |
| closeable | bool | true | Show close (X) button in header |
| expandable | bool | true | Allow layer to be maximized |
| queryParams | function | `(params) => params` | Modify AJAX query parameters |
| onAll | function | `function(eventName, ...args) {}` | Callback for all triggered events |
| onPostBody | function | `function($content) {}` | After content is loaded |
| onShow | function | `function() {}` | Before layer is shown |
| onShown | function | `function() {}` | After layer is fully visible |
| onHide | function | `function() {}` | Before layer is hidden |
| onHidden | function | `function() {}` | After layer is fully hidden |
| onRefresh | function | `function($content) {}` | When the layer is refreshed |
| onCustomEvent | function | `function(eventName, ...params) {}` | For user-defined custom events |
**Usage Example:**
```javascript
$('#btnLayerExample').bsLayer({
ajax: {
method: 'POST'
},
name: 'example-layer',
title: 'My Example Layer',
width: 600,
backdrop: true,
url: 'example-content.php',
refreshable: true,
closeable: true,
expandable: false,
queryParams: function (params) {
params.userId = 123;
return params;
},
onShown: function ($content) {
console.log('Layer wurde angezeigt');
},
onAll: function (eventName, ...args) {
console.log('Event:', eventName, args);
}
});
// You can also supply a function to the `url` option that returns a Promise. This allows you to load dynamic content asynchronously, for example via an API call or any custom logic.
// The function can be defined either as an `async` function or as a regular function returning a Promise. The most important point is that the return value is a Promise that resolves with the HTML/string content.
$('#btnLayerExample').bsLayer({
name: 'promise-layer',
title: 'Async Content Layer',
width: 600,
backdrop: true,
queryParams(params) {
// You can dynamically modify or extend parameters here
params.id = 1;
params.token = 'demo-123'; // Example: add extra parameter
return params;
},
// `url` as a Promise function: receives params and can use them
url: async function(params) {
// Example: use params for dynamic content or API call
return new Promise(function (resolve, reject) {
setTimeout(function () {
// You can use params.id, params.token, etc. as needed
resolve(
`
Async loaded content 🚀
This content was loaded via Promise!
Params: ${JSON.stringify(params)}
`
);
}, 1000);
});
},
refreshable: true,
onShown: function ($content) {
console.log('Async layer shown');
}
});
```
---
### Plugin Methods
These instance methods can be called on any jQuery element that has been initialized as a layer trigger:
| Method | Parameters | Description |
|------------|----------------|---------------------------------------------------------------------------------------|
| `setTitle` | `title` | Dynamically sets the layer’s title (as string or HTML) for the current trigger. |
| `show` | `...args` | Programmatically opens/displays the layer (simulates a click on the trigger element). |
| `refresh` | `options = {}` | Reloads or refreshes the layer content, e.g. via AJAX, using supplied options if any. |
| `close` | none | Closes/hides the layer that belongs to the current trigger element. |
**Usage Example:**
```javascript
$('#myLayerBtn').bsLayer('setTitle', 'New Title');
$('#myLayerBtn').bsLayer('show');
$('#myLayerBtn').bsLayer('refresh');
$('#myLayerBtn').bsLayer('close');
```
## License
Proprietary
See [composer.json](composer.json) for author information.# bs-layerSlideMenu