Customization

custom directory structure

Place your Javascript / SCSS sources into the custom directory.

Note: I don't recommend to edit files outside the custom directory, because they will be rewritten by Builder app when updating the bundle.
Exceptions: bower.json, amd.json, config.json

Customizing PixelAdmin's components

You can change default PixelAdmin's SCSS variables by adding it to the custom/scss/_variables.scss or custom/scss/_variables-dark.scss file.

For example, to change default background of .panels:

custom/scss/_variables.scss

$panel-bg: #fafafa;

Now, all panels will have background: #fafafa by default.

Custom SCSS

You can place custom SCSS sources into the custom/scss directory. In your code you can use all PixelAdmin's SCSS variables and mixins.

The custom/custom.scss file is imported at the end of scss/pixeladmin.scss file.

To add custom SCSS:

  1. Create custom/scss/_fileName.scss file.
  2. Write some SCSS code.
  3. Add @import 'scss/fileName'; line to the custom/custom.scss file.

Example:

custom/scss/_ad-panel.scss

.ad-panel {
  padding: $panel-body-padding;

  @include clearfix();

  img {
    display: block;
    width: 100%;
  }
}
custom/custom.scss

@import 'scss/ad-panel';

Custom Javascript

You can place custom Javascript sources into the custom/js directory. Javascript sources can be written using ES5 or ES6.

Files which included in the custom/custom.js will be added to the end of pixeladmin.js file.

To add custom Javascript:

  1. Create custom/js/fileName.js file.
  2. Write some Javascript code.
  3. Note: you can skip this step if compilation of concatenated version is disabled.
    Include created file in the custom/custom.js file using the syntax:
    //= require path/to/compiled/source.js
    I.e. you need to add //= require build/fileName.js line to the custom/custom.js file.

Example:

custom/js/utils/browser.js

const browserUtils = {
  alert(message) {
    window.alert(message);
  }
};

export default browserUtils;
custom/js/app.js

import jQuery from 'jquery';
import browserUtils from 'px/custom/utils/browser';

class SomeApp {
  constructor() {
    jQuery(function() {
      browserUtils.alert('App started');
    });
  }
}

export default SomeApp;
custom/custom.js

//= require build/utils/browser.js
//= require build/app.js

Non-RequireJS usage: 


browserUtils.alert('Some alert');

new SomeApp();

RequireJS usage: 


require(['px/custom/utils/browser'], function(browserUtils) {
  browserUtils.alert('Some alert');
});

require(['px/custom/app'], function(App) {
  new App();
});

Adding Bower packages

To add custom Bower package:

  1. Add package name and version to the dependencies section in the bower.json file.
  2. Install Bower packages.
  3. Require the package's main file in the custom/custom.js file using the syntax:
    //= require ../libs/path/to/package/main/file.js

Example:

bower.json

{
  ...
  "dependencies": {
    ...
    "blazy": "*"
  }
}
custom/custom.js

//= require ../libs/blazy/blazy.min.js

Non-RequireJS usage: 


new Blazy(...);

RequireJS usage: 


require(['px-libs/blazy.min'], function(Blazy) {
  new Blazy(...);
});

Wrapping Bower package with AMD

Some Bower packages are not providing an AMD interface. To automatically add an AMD interface to the package:

  1. Add package's main file path (in the amd directory) and its dependencies to the dependencies section in the amd.json file. If package has no dependencies then just specify an empty array.
    amd.json
    
{
  "dependencies": {
    ...
    "libs/packageName.js": [
      { "name": "jquery", "param": "$", "global": "jQuery" },
      { "name": "px-bootstrap/transition", "param": "transition", "global": "Transition" }
    ],
    "libs/anotherPackage.js": []
  },
  ...
}
  2. If package must export an object, add the appropriate config to the exports section in the amd.json file:
    amd.json
    
{
  ...
  "exports": {
    "libs/packageName.js": "PackageClassToExport"
  },
}

Full example:

bower.json

{
  ...
  "dependencies": {
    ...
    "FitText.js": "*"
  }
}
custom/custom.js

//= require ../libs/FitText.js/jquery.fittext.js
amd.json

{
  "dependencies": {
    ...
    "libs/jquery.fittext.js": [
      { "name": "jquery", "param": "jQuery", "global": "jQuery" }
    ]
  },
  ...
}

Now you can use FitText.js plugin with AMD:


require(['jquery', 'px-libs/jquery.fittext'], function($) {
  $('.responsive-text').fitText();
});

Creating custom colors

You can customize UI elements using custom color classes. To generate a custom color just include the pixel-color-variant mixin in your SCSS code using the next syntax:

@include pixel-color-variant(color-name, #bg-color, #text-color);

Let's take the example of color creation:

custom/scss/_colors.scss

@include pixel-color-variant(facebook, #3b5998, #fff);
custom/custom.scss

@import 'scss/colors';

The call above will generate the next classes:

Now, after the sources recompilation, you can change the style of an element by adding the appropriate class: 


<button type="button" class="btn btn-facebook">...</button>

<ul class="dropdown-menu dropdown-menu-facebook">
  ...
</ul>

<div class="progress">
  <div class="progress-bar progress-bar-facebook"></div>
</div>

<label class="custom-control custom-checkbox custom-control-facebook">
  <input type="checkbox" class="custom-control-input">
  <span class="custom-control-indicator"></span>
  ...
</label>

Theming

You can easily create your own themes using built-in pixel-theme mixin. To create theme:

  1. Create custom/scss/themes/theme-name/theme-name.scss file.
  2. Setup your theme colors using the pixel-theme mixin.
  3. Compile SCSS sources. Compiled themes are placed into the dist/css/themes directory.
  4. Include compiled theme file in the page's <head> element:
    <link href="path/to/assets/css/themes/theme-name.css" rel="stylesheet" type="text/css">
  5. Done!

Let's take the example of theme configuration:

custom/scss/themes/brand-blue/brand-blue.scss

// If you're creating a dark theme do not forget to import dark scheme variables

// @import '../../../../scss/variables-dark';
@import '../../../../scss/variables';
@import '../../../../libs/bootstrap-sass/assets/stylesheets/bootstrap/variables';
// @import '../../variables-dark';
@import '../../variables';
@import '../../../../libs/bootstrap-sass/assets/stylesheets/bootstrap/mixins';
@import '../../../../scss/mixins';


$theme-primary-color: #2383F4;


// Generate theme
//

@include pixel-theme(

  // Basic
  //

  $primary-color:        $theme-primary-color,             // Primary color
  $primary-text-color:   #fff,                             // Primary text color
  $primary-border-color: darken($theme-primary-color, 6%), // Primary border color

  $body-bg:              #f6f6f6,            // Body background
  $panel-border-color:   #e2e2e2,            // Border color of panel
  $header-bg:            transparent,        // [Optional] [Default: transparent] Background of page header
  $header-border-color:  rgba(0, 0, 0, .07), // [Optional] [Default: false] Border color of page header

  // Px-Navbar element
  //

  $px-navbar: (
    bg:                             $theme-primary-color,    // Navbar background
    border-color:                   rgba(0, 0, 0, .09),      // Border color of navbar item on md, lg and xl screens
    link-color:                     #fff,                    // Link color
    link-hover-color:               rgba(255, 255, 255, .8), // Link color in hover state
    link-hover-bg:                  rgba(0, 0, 0, .04),      // Link background in hover state
    shadow:                         "none",                  // [Optional] [Default: "none"] Navbar shadow

    // Navbar brand styling (take effect when .px-nav is expanded on lg and xl screens)
    brand-bg:                       $theme-primary-color, // Brand background
    brand-link-color:               #fff,                 // Brand link color
    brand-link-hover-color:         #fff,                 // Brand link color in hover state

    collapse-bg:                    #2578da,                  // [Optional] [Default: px-navbar[bg]] Background of navbar collapse on xs and sm screens; Background of dropdown menu on md, lg and xl screens
    collapse-border-color:          #216CC5,                  // Border color of navbar item on xs and sm screens; Border color of dropdown menu divider on md, lg and xl screens
    collapse-dropdown-bg:           rgba(255, 255, 255, .06), // Background of dropdown menu on xs and sm screens
    collapse-dropdown-border-color: #5898E3,                  // Border color of dropdown menu item on xs and sm screens

    form-control-bg:                rgba(255, 255, 255, .3), // Background of navbar form control
    form-control-border-color:      transparent,             // Border color of navbar form control
    form-control-color:             #fff,                    // Text color of navbar form control

    scrollbar-color:                rgba(255, 255, 255, .5), // Scrollbar color
    scrollbar-rail-color:           transparent,             // Scrollbar rail color

    enable-transitions:             false // [Optional] [Default: true] Enable transitions
  ),

  // Px-Nav element
  //

  $px-nav: (
    toggle-color:                #fff,    // Text color of toggler
    toggle-bg:                   #2977d3, // Background of toggler

    bg:                          #545d64,            // Nav background
    color:                       #aabcca,            // Text and link color
    link-hover-color:            #fff,               // Link color in hover state
    link-hover-bg:               rgba(0, 0, 0, .08), // Link background in hover state

    // Dropdowns
    dropdown-bg:                 #485056,              // Background of dropdown
    dropdown-menu-title-color:   #fff,                 // Text color of floating dropdown title 
    dropdown-menu-title-bg:      $theme-primary-color, // Background of floating dropdown title

    // Active
    active-color:                #fff,                 // Text color of active nav item
    active-bg:                   #3687e6,              // Background of active nav item
    active-icon-color:           #fff,                 // Icon color of active nav item
    active-dropdown-icon-color:  $theme-primary-color, // [Optional] [Default: px-nav[active-icon-color]] Icon color of active nav dropdown

    scrollbar-color:             rgba(255, 255, 255, .3), // Scrollbar color
    scrollbar-rail-color:        transparent,             // Scrollbar rail color

    toggle-border-color:         #3372bc, // [Optional] [Default: false] Border color of toggler
    border-color:                false,   // [Optional] [Default: false] Border color of nav
    item-border-color:           #4D565C, // [Optional] [Default: false] Border color of nav item
    dropdown-item-border-color:  #41494E, // [Optional] [Default: false] Border color of dropdown item
    box-border-color:            #445059, // [Optional] [Default: transparent] Border color of .px-nav-box

    tooltip-bg:                  $theme-primary-color, // [Optional] [Default: px-nav[active-bg]] Background of tooltip
    tooltip-color:               #fff,                 // [Optional] [Default: px-nav[active-color]] Text color of tooltip

    dimmer-bg:                   rgba(#485056, .5), // [Optional] [Default: $px-nav-dimmer-bg] Background of dimmer

    animate-items:               true // [Optional] [Default: false] Add transitions to nav items
  ),

  // Px-Footer element
  //

  $px-footer: (
    color:            rgba(255, 255, 255, .5), // Text color
    bg:               #5d676f,                 // Background of footer

    link-color:       rgba(255, 255, 255, .6), // Link color
    link-hover-color: #fff,                    // Link color in hover state

    muted-color:      #939ea7, // [Optional] [Default: false] Text color of .text-muted element
    border-color:     false,   // [Optional] [Default: false] Border color of footer
    hr-color:         #6d7881  // [Optional] [Default: false] Border color of 
 element
  )
);

// Custom styles
//

// PxNavbar
@if mixin-exists(px-nav-theme) {
  @media (min-width: $screen-md-min) {
    .px-navbar .dropdown-menu {
      border: none;
    }
  }
}

// Pace.js
.pace-progress { background: darken($theme-primary-color, 13%); }
  

<html>
  <head>
    ...
    <link href="path/to/assets/css/themes/brand-blue.min.css" rel="stylesheet" type="text/css">
    ...
  </head>
  <body>
    ...
  </body>
</html>

The result:










Have a question or problem? You can try to find the solution or create an issue at

https://github.com/smnedelko/PixelAdmin/issues