# Scrollbars

### 1. Scrollbars

- Trying different scrollbar plugins, I wasn't able to find a lightweight and easy to use one, which is also touch friendly.
  So I thought it's better to make one.
  It's minimal but should be enough for most cases.
  You can also use other more advanced plugins if necessary. There should be no conflicts.
- Here is a simple snippet which add vertical scrollbars to an element and limits its size to 400:

       $('#my-content').ace_scroll({size: 400});

### 2. Options

- `size` which is 200px by default

       $('#my-content').ace_scroll({size: 400});

  You can also specify size using `data-size` attribute:

         ...

- `horizontal` default=false. If true, horizontal scrollbars will be added

      $('#my-content').ace_scroll({horizontal: true});

- `mouseWheel` default=true. Scrolls content on mouse wheel event. When end of content is reached, mouse wheel event will be propagated to window
- `mouseWheelLock` default=false. If true and we have reached end of scrolling on our element, mouse wheel event won't be propagated to window
  `lockAnyway` default=false. If true, even if scrollbars are not needed and are not visible yet, mouse wheel event won't be propagated to window

       $('#my-content').ace_scroll({size: 300, mouseWheelLock: true});

- `styleClass` additional style classes you can add to scrollbars. See next section for more info.
- `hoverReset` default=true, because of window size changes and other document layout changes, content sizes may change and we may need to reset scrollbar size.
  It can be done on mouseenter event, which is set to true by default.
- `reset` default=false. If true, content will be scrolled to 0, on initialization.
  Does not work when the element is hidden at first.
- `dragEvent` default=false. If true an event will be triggered when user starts dragging scrollbars using mouse.
- `scrollEvent` default=false. If true an event will be triggered when content is scrolled.
- `touchDrag` default=true, which adds touch drag event for touch devices.
- `hideOnIdle` will hide scrollbars when user is not scrolling content
  You may also want to use `hideDelay` which specifies time before hiding scrollbars and also `observeContent` which specifies whether content and scrollbar size should be reset before making it visible:

       $('#my-content').ace_scroll({
          //other options
          hideOnIdle: true,
          hideDelay: 1500,
          observeContent: true
      });

### 3. Styles

- Some additional classes you can add using `styleClass` option:
  1. `scroll-margin` which add 1px space between content and scrollbars
  2. `scroll-left` shows scrollbars on left instead of right
  3. `scroll-top` shows horizontal scrollbars on top instead of bottom
  4. `scroll-dark` darker scrollbars
  5. `scroll-light` lighter scrollbars
  6. `no-track` hides scroll track
  7. `scroll-visible` scrollbars always visible
  8. `scroll-thin` thinner scrollbars
  9. `scroll-chrome` similar to latest version of Google Chrome scrollbars

-      $('#my-content').ace_scroll({
          size: 300,
          styleClass: 'scroll-dark scroll-left scroll-thin'
       });

### 4. Events

- If you set `scrollEvent` to true, a scroll event will be triggered when element is scrolled:

       $('#my-content')
       .ace_scroll({
          scrollEvent: true
       })
       .on('scroll', function() {
          //element scrolled
       });

  But it's better to listen to the inner content's native scroll event:

       $('#my-content').find('.scroll-content').on('scroll', function() {
          //element scrolled
       });

- If you set `dragEvent` to true, some drag events will be triggered when scrollbars are dragged:

       $('#my-content')
       .ace_scroll({
          dragEvents: true
       })
       .on('drag.start', function() {
          //started dragging
       })
       .on('drag._end', function() {
          //ended dragging
       })

### 5. Touch Drag Event

- There is also a custom touch drag event specifically for use on scrollbars.
  You can use it with other elements as well, though I recommend a more advanced library such as Hammer.js
- You can use it like this:

      $('#some-element').on('ace_drag', function(event) {
        //var dir = event.direction;// up down left right
        //var distanceX = event.dx
        //var distanceY = event.dy
      })

### 6. Functions

- The following functions are available for scroller plugin:
  1. `reset` resets scrollbar size
  2. `disable` disables scrollbars
  3. `enable` enables scrollbars
  4. `end` scroll to end
  5. `start` scroll to start
  6. `update` updates an option (currently only size, style and mousewheel options)

-     $('#my-content').ace_scroll('reset');
      $('#my-content').ace_scroll('disable');

      $('#my-content').ace_scroll('update', {size: 250});
      $('#my-content').ace_scroll('modify', completely_new_options);

### 7. Horizontal

- Horizontal scrollbars can be created by specifying `horizontal` option:

      $('#my-content').ace_scroll({
          horizontal: true,
          size: 600,
          styleClass: 'scroll-top',
          mouseWheelLock: true
      });

- Sometimes you may need to add some padding to the element if scrollbars appear above content:

      $('#my-content').ace_scroll({
          horizontal: true,
          //options here
      }).css('padding-top', 15);

- If you are using RTL (right to left) direction, please note that horizontal scrolling is inconsistent between browsers.
  So it's better to change scrollbars to LTR and make the content RTL again.
  You can use `.make-ltr` and `.make-rtl` classes:

       $('#my-content').addClass('make-ltr')
       .find('.scroll-content').wrapInner('<div class="make-rtl" />');

Or statically inside your HTML:

         ...

    $('#my-content').ace_scroll({
        horizontal: true,
        //other options here
    })

### 8. Sidebar Scrollbars

- You can also use scrollbar for sidebar whether it's fixed or not.
- I have used two approaches for sidebar
- The first one which is used by default, does not use `overflow:hidden` and can be used only on fixed sidebar.
  The advantage is that .hover submenus or mininized sidebar can also have scrollbars and submenus will be shown outside of sidebar area without problem.
Second one uses real scrollbars and has `overflow:hidden` applied to it.
It can be used on both normal and fixed sidebar.
To enable it you should build a custom JS using 2nd sidebar scrollbar style.
- Each one has several options which you can edit inside:
  1. `assets/js/ace/ace.js`
  2. `assets/js/ace.js`
  3. `dist/js/ace.min.js`
  Look for `sidebar_scrollable` and change options as needed.
- Options for first style (fixed sidebar only):
  1. `scroll_to_active` If true, sidebar will be scrolled down to show active menu item on page load
  2. `include_shortcuts` If true, shortcuts will also be inside scroll area. Otherwise it will be above scroll area
  3. `include_toggle` If true, sidebar toggle(minimize button) will also be inside scroll area. Otherwise it will be below scroll area
  4. `smooth_scroll` If true, sidebar scrolling will be smooth using CSS3 transition
  5. `outside` If true, scrollbar will be outside of scroll area
- Options for secod style (normal/fixed sidebar):
  1. `only_fixed` If true, scrollbars will be enabled for fixed sidebar only
  2. `scroll_to_active` If true, sidebar will be scrolled down to show active menu item on page load
  3. `include_shortcuts` If true, shortcuts will also be inside scroll area. Otherwise it will be above scroll area
  4. `include_toggle` If true, sidebar toggle(minimize button) will also be inside scroll area. Otherwise it will be below scroll area