Unslider - Documentation

Introduction

What is Unslider?

Unslider is a lightweight and dependency-free JavaScript slider. It’s designed to be easily integrated into existing projects without requiring any external libraries or frameworks. Unslider focuses on simplicity and providing a clean, responsive sliding experience with minimal code. Its core functionality revolves around creating a simple, elegant slideshow or carousel with intuitive navigation.

Features and Benefits

Installation and Setup

Unslider is distributed as a single JavaScript file. You can download it from [Insert Download Link Here] and include it in your project using a <script> tag:

<script src="unslider.min.js"></script>

Place this script tag before the closing </body> tag of your HTML document. No additional CSS files are required, although you can easily customize its appearance with your own CSS.

Basic Usage Example

First, create the HTML for your slider. This involves a container element and the slides themselves:

<div class="unslider">
  <ul>
    <li><img src="image1.jpg" alt="Slide 1"></li>
    <li><img src="image2.jpg" alt="Slide 2"></li>
    <li><img src="image3.jpg" alt="Slide 3"></li>
  </ul>
</div>

Then, initialize Unslider using JavaScript:

$('.unslider').unslider();

This simple line of code will initialize the slider on the element with the class “unslider”. Remember to include jQuery if you are using this method. For a pure JavaScript alternative see the documentation for options on how to initialize without jQuery. This will create a basic slider with default settings. You can further customize it using various options as detailed in the Unslider documentation.

Core Functionality

Initialization

Unslider can be initialized in two ways: using jQuery (if included in your project) or using plain JavaScript.

jQuery Initialization: If jQuery is available, initializing Unslider is as simple as:

$('.unslider').unslider();

This will initialize the slider on all elements with the class “unslider”.

Plain JavaScript Initialization: For projects without jQuery, use:

var myUnslider = new Unslider(document.querySelector('.unslider'));

This will initialize the slider and return an Unslider object, allowing for further control. Note that you must select the element using a method compatible with your project (e.g. document.getElementById()).

You can also pass options to customize the slider’s behavior during initialization (see the options section in the full documentation).

Unslider provides simple navigation controls:

The visual appearance of these controls is easily customizable using CSS.

Automatic Slideshow

To enable the automatic slideshow functionality, provide the speed option during initialization:

$('.unslider').unslider({
  speed: 3000 // Slide change every 3 seconds
});

The speed option defines the delay in milliseconds between automatic slide transitions. The automatic slideshow can be paused and resumed using methods described in the full documentation.

Responsive Design

Unslider automatically adapts to different screen sizes. It uses a fluid layout based on percentages, so the slider will scale proportionally to its container. No extra configuration is needed for responsive behavior.

Customizing the Appearance

The appearance of Unslider can be heavily customized using CSS. Target the relevant classes and IDs within the generated markup (check the generated HTML after initializing the slider) to modify the styles of slides, navigation controls, and the overall slider container.

For instance, to change the background color of the slides, you can use:

.unslider li {
  background-color: #f0f0f0;
}

Remember to inspect the generated HTML to identify the exact classes and IDs to target for specific styling changes.

Adding and Removing Slides

Adding and removing slides dynamically requires manipulating the underlying <ul> element within the slider container. To add a slide:

var ul = $('.unslider ul'); // or document.querySelector('.unslider ul')
var newLi = $('<li><img src="newimage.jpg" alt="New Slide"></li>'); // or createElement
ul.append(newLi);
// Re-initialize Unslider after adding/removing slides to refresh it:
$('.unslider').unslider('destroy').unslider(); // or use a similar approach with the plain JS object

To remove a slide:

$('.unslider ul li:last-child').remove();
// Re-initialize Unslider after adding/removing slides to refresh it:
$('.unslider').unslider('destroy').unslider(); // or use a similar approach with the plain JS object

Remember to re-initialize Unslider (using unslider('destroy').unslider() with jQuery or the equivalent with plain JS) after modifying the slide list to ensure the slider updates correctly. Always avoid direct manipulation of the slider’s internal state.

Advanced Techniques

Custom Events and Callbacks

Unslider triggers several events during its operation. You can listen for these events and execute custom code in response. While specific event names might vary depending on the initialization method (jQuery vs. plain Javascript), you can generally listen for events like beforeSlide, afterSlide, complete, etc. The exact events and their usage will be documented in the main Unslider documentation. Use these events to integrate custom actions with your slider’s state transitions. For instance, you could trigger an animation or update other elements on the page when a slide changes.

Example using jQuery (adapt for plain JS as needed):

$('.unslider').on('beforeSlide', function(e, data) {
  console.log('Before slide transition to index: ' + data.to);
});

Integrating with Other Libraries

Because Unslider is dependency-free, it can easily integrate with other JavaScript libraries. You can use other libraries to enhance its functionality (e.g., animation libraries for more sophisticated transitions, or lazy loading libraries for managing large images). Just be mindful to ensure that no naming conflicts exist between Unslider and other libraries.

Keyboard Navigation

Unslider supports keyboard navigation by default. Users can use the left and right arrow keys to navigate between slides. This feature is automatically enabled and requires no additional configuration.

Touch Support

Unslider supports touch events on mobile devices. Swiping left and right on the slider will navigate between slides. This touch support is built-in and doesn’t require any special configuration.

Accessibility Considerations

For improved accessibility:

Troubleshooting Common Issues

If you encounter issues not resolved through these steps, consult the Unslider project’s issue tracker or support channels for assistance. Provide detailed information about your setup, the error messages (if any), and relevant code snippets to facilitate efficient troubleshooting.

API Reference

Unslider Options

Unslider accepts several options during initialization to customize its behavior. These options can be passed as a JavaScript object to the unslider() function or the Unslider constructor. The most commonly used options include:

Example usage (jQuery):

$('.unslider').unslider({
  speed: 1000,
  delay: 5000,
  dots: false,
  complete: function() {
    console.log('Slide transition complete!');
  }
});

Example usage (Plain JavaScript):

var myUnslider = new Unslider(document.querySelector('.unslider'), {
    speed: 1000,
    delay: 5000,
    dots: false,
    complete: function() {
        console.log('Slide transition complete!');
    }
});

Methods

Unslider provides several methods to control the slider after initialization. These methods are usually chained to the slider object. The specific methods available will depend on the type of initialization (jQuery or plain Javascript) and might vary across different versions. The available methods might include (but are not limited to):

Example usage (jQuery):

$('.unslider').unslider('next');
var currentIndex = $('.unslider').unslider('current');
$('.unslider').unslider('destroy');

Example usage (Plain Javascript): Assuming myUnslider is the object returned by the Unslider constructor

myUnslider.next();
var currentIndex = myUnslider.current();
myUnslider.destroy();

Events

Unslider triggers various custom events during its operation. These events allow you to integrate custom functionality with the slider’s behavior. The events and their parameters are likely to be:

Consult the specific Unslider documentation for the definitive list of events and their parameters. Remember that event handling will differ slightly depending on your chosen method for initialization (jQuery or plain Javascript). jQuery uses .on() or .bind(), while plain Javascript uses addEventListener().

Examples

These examples assume you have included the Unslider JavaScript file in your project. Remember to adjust paths to images as needed.

Simple Slider

This example demonstrates the most basic implementation of Unslider.

HTML:

<div class="unslider">
  <ul>
    <li><img src="image1.jpg" alt="Slide 1"></li>
    <li><img src="image2.jpg" alt="Slide 2"></li>
    <li><img src="image3.jpg" alt="Slide 3"></li>
  </ul>
</div>

JavaScript (jQuery):

$('.unslider').unslider();

JavaScript (Plain Javascript):

new Unslider(document.querySelector('.unslider'));

Slider with Custom Navigation

This example shows how to replace the default navigation with custom buttons.

HTML:

<div class="unslider">
  <ul>
    <li><img src="image1.jpg" alt="Slide 1"></li>
    <li><img src="image2.jpg" alt="Slide 2"></li>
    <li><img src="image3.jpg" alt="Slide 3"></li>
  </ul>
</div>
<button id="prev">Previous</button>
<button id="next">Next</button>

JavaScript (jQuery):

var slider = $('.unslider').unslider();
$('#prev').click(function() { slider.prev(); });
$('#next').click(function() { slider.next(); });

JavaScript (Plain Javascript):

var slider = new Unslider(document.querySelector('.unslider'));
document.getElementById('prev').addEventListener('click', function() { slider.prev(); });
document.getElementById('next').addEventListener('click', function() { slider.next(); });

Slider with Autoplay

This example demonstrates how to enable the automatic slideshow functionality.

HTML: (same as Simple Slider)

JavaScript (jQuery):

$('.unslider').unslider({ speed: 3000 }); // Change slide every 3 seconds

JavaScript (Plain Javascript):

new Unslider(document.querySelector('.unslider'), { speed: 3000 }); //Change slide every 3 seconds

Responsive Slider

Unslider is responsive by default. No extra code is needed. Ensure your container (<div class="unslider">) is set up with appropriate CSS for responsive design (e.g., using percentages for width).

Complex Slider with Multiple Features

This example combines several features: autoplay, custom navigation, and a complete callback.

HTML: (similar to Slider with Custom Navigation)

JavaScript (jQuery):

var slider = $('.unslider').unslider({
  speed: 4000,
  complete: function(e,data) {
    console.log("Current Slide: " + data.to);
    // Add any other actions here
  }
});
$('#prev').click(function() { slider.prev(); });
$('#next').click(function() { slider.next(); });

JavaScript (Plain Javascript):

var slider = new Unslider(document.querySelector('.unslider'), {
    speed: 4000,
    complete: function(e,data) {
        console.log("Current Slide: " + data.to);
        // Add any other actions here
    }
});
document.getElementById('prev').addEventListener('click', function() { slider.prev(); });
document.getElementById('next').addEventListener('click', function() { slider.next(); });

Remember that these are simplified examples. You can adapt them and add more features based on your project’s requirements and the options and methods provided by the Unslider API. Consult the complete API documentation for a full list of options and methods available.

Contributing

We welcome contributions to Unslider! Whether you’re fixing bugs, adding features, or improving the documentation, your help is valuable. Please follow these guidelines to ensure a smooth and collaborative contribution process.

Contribution Guidelines

  1. Fork the Repository: Start by forking the official Unslider repository on GitHub.

  2. Create a Branch: Create a new branch for your changes. Use a descriptive name that clearly reflects the purpose of your contribution (e.g., “fix-bug-navigation”, “add-feature-lazy-loading”).

  3. Make Your Changes: Implement your changes, following consistent coding styles and best practices. Keep your changes focused and well-organized. Thoroughly test your modifications to ensure they work correctly and don’t introduce new issues.

  4. Write Tests: If you’re adding or modifying functionality, write corresponding unit tests to ensure the code works as expected and remains robust.

  5. Update Documentation: If your contribution affects the API, options, or usage, update the relevant sections of the documentation to reflect the changes. Ensure the documentation remains clear, concise, and up-to-date.

  6. Commit Your Changes: Commit your changes with clear and concise commit messages that explain what you’ve done and why. Follow a consistent commit message style.

  7. Submit a Pull Request: Submit a pull request to the official Unslider repository, clearly explaining your changes and their purpose. Be prepared to address any feedback or suggestions from the maintainers.

Code of Conduct

We expect all contributors to adhere to a professional and respectful code of conduct. Be polite, considerate, and constructive in your interactions with other contributors and maintainers. Harassment, discrimination, and abusive behavior will not be tolerated. We strive to foster a welcoming and inclusive community where everyone feels comfortable contributing.

Reporting Issues

If you discover a bug or have a feature request, please report it through the issue tracker on the Unslider GitHub repository. Provide as much detail as possible, including:

Submitting Pull Requests

When submitting a pull request, please ensure:

We appreciate your contributions and look forward to working with you to improve Unslider!