# Settings

- Ace settings functions and cookie/localStorage feature is saved inside `assets/js/ace-extra.js`
- If you want these features, it's best to include this file inside document head
- The script to restore user saved settings is placed immediately after the relevant element's HTML code:

  This will cause the element's status be restored as soon as it is inserted into DOM.
  If you call the functions after page load, for example in jQuery's document ready event, there may be a delay between the initial state and the saved state.
  It may not be noticeable for fixed navbar, etc, but for collapsed sidebar or other settings, it can get noticeable.
  The `try/catch` block is used so that if you don't want to use `ace-extra.js`, the browser doesn't raise any errors.
  In that case you can remove the code if it's not necessary.

## Page Options

### Fixed Navbar

- For fixed navbar, you should add `.navbar-fixed-top` class to `.navbar` element:

- You can also use the following javascript code to do this:

       ace.settings.navbar_fixed(null, true, true);//first parameter is null or reference to navbar element
       ace.settings.navbar_fixed(document.getElementById('navbar'), true, true);

  First parameter is a reference to navbar element. If null `#navbar` will be used.
  Second parameter determines whether navbar should become fixed or not.
  Third paramtere determines whether you want to save the changes to cookies/localStorage for later retrieval
- In smaller devices, fixed navbar content may become too large and ends up in more that two rows.
  In that case you may need to add extra padding to content area using CSS and media rules or enable auto padding option when building your custom Javascript

### Fixed Breadcrumbs

- For fixed breadcrumbs, you should add `.breadcrumbs-fixed` class to `.breadcrumbs` element:

- If you want to do this using Javascript, you can use this code:

       ace.settings.breadcrumbs_fixed(null, true, true);//first parameter is null or reference to breadcrumbs element
       ace.settings.breadcrumbs_fixed(document.getElementById('breadcrumbs'), true, true);

  First parameter is a reference to breadcrumbs element. If null `#breadcrumbs` will be used.
  Second parameter determines whether breadcrumbs should become fixed or not.
  Third paramtere determines whether you want to save the changes to cookies/localStorage for later retrieval
- Currently, fixed breadcrumbs are only available when device with is above `991px` which you can change that by modifying `@screen-fixed-breadcrumbs` variable inside `assets/css/less/variables.less` files and recompiling `ace.less`.
  The reason for this is that in smaller devices, fixed breadcrumbs and fixed navbar may take up a lot of space!
- Anyway, if in smaller devices, your fixed breadcrumbs content is too large and ends up in more that two rows, you may need to add extra padding to content area using CSS and media rules or enable auto padding option when building your custom Javascript

### Inside container

- For fixed container width, you should add `.container` class to `.navbar-container` and `.main-container` elements:

           ...

- If you want to do this using Javascript, you can use this code:

       ace.settings.main_container_fixed(null, true, true);//first parameter is null or reference to container element
       ace.settings.main_container_fixed(document.getElementById('main-container'), true, true);

  First parameter is a reference to container element. If null `#main-container` will be used.
  Second parameter determines whether navbar should become fixed or not.
  Third paramtere determines whether you want to save the changes to cookies/localStorage for later retrieval.
- Currently Bootstrap doesn't allow fixed width container on specific widths only.
  You can enable auto container option when building a custom Javascript to activate fixed container only when device width is more than 1140px.

      $(window).on('resize.auto_container', function() {
          var enable = $(this).width() > 1140;
          try {
             ace.settings.main_container_fixed(enable, false, false);
          } catch(e) {}
      }).triggerHandler('resize.auto_container');

### Sidebar Settings

- For fixed sidebar, you should add `.sidebar-fixed` class to `.sidebar` element:

- If you want to do this using Javascript, you can use this code:

       ace.settings.sidebar_fixed(null, true, true);//first element is null or reference to sidebar element
       ace.settings.sidebar_fixed(document.getElementById('sidebar'), true, true);

  First parameter is a reference to sidebar element. If null `#sidebar` will be used.
  Second parameter determines whether sidebar should become fixed or not.
  Third paramtere determines whether you want to save the changes to cookies/localStorage for later retrieval.
- For minimized sidebar, you should add `.menu-min` class to `.sidebar` element:

- If you want to do this using Javascript, you can use this code:

       ace.settings.sidebar_collapsed(null, true, true);//first param is null or reference to sidebar element
       ace.settings.sidebar_collapsed(document.getElementById('sidebar'), true, true);

  First parameter is a reference to sidebar element. If null, `#sidebar` will be used.
  Second parameter determines whether sidebar should become minimized or not.
  Third paramtere determines whether you want to save the changes to cookies/localStorage for later retrieval.
- For other sidebar options and settings please see Sidebar options

### Setting Events

- When a settings box option or sidebar collapse/expand button is clicked an event is triggered which may be useful in case you use settings box and want to respond to user changes
- The event name is `settings.ace` and has two extra arguments.
  The first is event name and the second is the new status:

      $(document).on('settings.ace', function(event, name, status) {
          //name is one of the following
          //navbar_fixed
          //sidebar_fixed
          //breadcrumbs_fixed
          //main_container_fixed
          //sidebar_collapsed

          //status is either true or false

          if(name == 'sidebar_fixed' && status == false) {
              //sidebar was unfixed by user, do something
          }
      }

### Skins

- There are currently 4 skins available which changes sidebar and navbar colors, which are:
  1. `.no-skin`
  2. `.skin-1`
  3. `.skin-2`
  4. `.skin-3` To use .skin-3 you should add `.no-skin` class as well
- To use a skin simply update `body` element's class name:

      <body class="skin-2">
      ...

- Inside settings box when you select a skin some other parts change as well.
  For example shortcut buttons or navbar user dropdown buttons.
  For that you should update some class names in your HTML code:

- ...
- Default skin in included and compiled with `ace.css` but for other skins you should include `ace-skins.css`
- You can also compile main css `ace.css` using another skin.
  Please refer to Ace Skins section for more info.
- If you want to save a selected skin and retrieve it when user navigates to a different page or refreshes page, there are several approaches for that depending on your application.
  One way is to save selected skin inside a cookie and apply changes in your server side code when user requests a page:

       $('#ace-settings-skin').on('change', function() {
         ace.settings.set('skin', this.value);
       })

  And in your server side code:

      $skin = $_COOKIE['ace_skin'];
      echo '<body class="'.$skin.'">';
      //...
      //...
      echo '<li class="'.some_modification_based_on_selected_skin($skin).'">';

  Of course it's the simplest way and things would be different depending on your application

### RTL

- RTL (right to left) direction is used for Arabic, Hebrew and Persian languages
- It's best to make RTL changes directly inside your HTML rather than using Javascript dynamically at runtime.
- You should make the following changes for RTL:
  1. Include `assets/css/ace-rtl.css`
  2. Add `.rtl` class to `body` element
  3. Switch classes that have `-right` or `-left`
     For example:
     `.pull-right` & `.pull-left`
     or
     `.no-padding-left` & `.no-padding-right`
     or
     `.arrowed` & `.arrowed-right`
  Also please note that RTL 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" />');

  Some plugins support RTL and you should specify the options when initiating plugins:
  1. For Chosen plugin add `.chosen-rtl` to the element
  2. For jqGrid plugin specify `direction:'rtl'` option
  3. For jQuery UI datepicker specify `isRTL:true` option
  4. For FullCalendar plugin set `isRTL:true` option
- Sometimes when using RTL option of settings box for multiple times, you elements are misplaced in some browsers.
  This is probably because browsers don't redraw elements.
  It won't be a problem in your application, because you should enable RTL inside your server side response and not dynamically inside browser.

### Cookies & Storage

- Cookie and localStorage functionality has been added to save/load variables and settings which is defined inside `ace-extra.js`

-     //cookie functions
      ace.cookie.set(name, value, expires, path, domain, secure);
      ace.cookie.get(name);
      ace.cookie.remove(name, path);

      //localStorage functions
      ace.storage.set(key, value);
      ace.storage.get(key);
      ace.storage.remove(key);

- `ace.data_storage` is a wrapper which by default chooses localStorage if available.
  Otherwise it will use cookies for saving data which you can change that by specifying an optional argument:

      ace.data = new ace.data_storage();//use localStorage if available otherwise use cookies
      ace.data = new ace.data_storage(1);//use localStorage
      ace.data = new ace.data_storage(2);//use cookies

      //save/load values with namespace (for example 'settings')
      //ace.data.set(namespace, key, value);
      ace.data.set('settings', 'sidebar-collapsed', 1);
      var collapsed = ace.data.get('settings', 'sidebar-collapsed');
      ace.data.remove('settings', 'sidebar-collapsed');

      //save/load values without namespace
      ace.data.set('username', 'alex');
      var username = ace.data.get('username');
      ace.data.remove('username');

### Settings Box

- Settings container (`.ace-settings-container`) should be the first child of `.page-content`
  It contains `.ace-settings-btn` and `.ace-settings-box` which consists of several `.ace-settings-item` elements:

                   Fixed Navbar

      		...

        .
        .
        .