We use https://waffle.io/softlayer/sl-ember-components to work our issues.
An Ember CLI Addon that provides UI components compatible with Ember.js and Twitter Bootstrap.
This addon is currently BETA. View the Roadmap we're following for a 1.0.0+ release.
Examples and documentation on how to use each component can be viewed at http://softlayer.github.io/sl-ember-components/ which is served from the gh-pages branch of this repository.
Components provided
- sl-alert
- sl-button
- sl-calendar
- sl-chart (only free for non-commercial use without a Highcharts license)
- sl-checkbox
- sl-date-picker
- sl-date-range-picker
- sl-date-time
- sl-drop-button
- sl-grid
- sl-input
- sl-menu
- sl-modal
- sl-pagination
- sl-panel
- sl-progress-bar
- sl-radio
- sl-radio-group
- sl-select
- sl-span
- sl-tab-panel
- sl-textarea
- sl-tooltip
Mixins provided
sl-component-input-id
Provides unique id that a component can assign to an input and a label's "for" attribute.
sl-input-based
Provides state properties for input element based components.
sl-namespace
Namespace component events by elementId
sl-tooltip-enabled
Provides Bootstrap tooltip functionality bindings, for both popovers and plain tooltips.
Utility Classes provided
containsValue
Check whether a value is a valid value in object.
warn
Provides a mechanism for initiating console.warn()s
error
Provides a way for individual components to throw errors that are able to be recognized by methods inside of a consuming application's Ember.onerror() function. For more details reference the Error Handling section below.
CSS Classes provided
sl-loading
Apply a loading indicator to an element. See the Loading Indicator section for more information.
All of this functionality is provided through a combination of leveraging the best-of-breed of other component offerings as well as our own implementations when the existing offerings were deficient. Existing offerings that were leveraged include:
While this library is MIT licensed not all of the third-party component libraries are. Specifically, Highcharts is only free for non-commercial use and requires a license for any other use. See this FAQ page for more information.
Other libraries that are not MIT licensed, though it should not pose a problem, are:
See http://softlayer.github.io/sl-ember-components/#/browsers
http://softlayer.github.io/sl-ember-components/#/demos
git clonethis repositorynpm installbower install
ember serve- View the demo at http://localhost:4200
For more information on using ember-cli, visit http://www.ember-cli.com/.
ember ember-cli-jsocornpm run docs(shortcut setup in this repo)- Visit http://localhost:4200/docs
ember install sl-ember-components
The components in sl-ember-components will throw errors if the components are used incorrectly. For example, the sl-radio-group component requires that a name property be passed with the component. If one is not passed an error will be thrown with the name of the component that is throwing the error (sl-radio-group) and the message saying "The name property must be set".
If you wish to capture these errors and pass them along to your error logging application you can do so by adding the following lines to your application's app/app.js file:
import { errorWasThrown, isErrorInstanceOf } from 'sl-ember-components/utils/error';
var App;
...
Ember.onerror = function( error ) {
if ( errorWasThrown( error ) ) {
// This will catch any errors coming from the sl-ember-components addon
// Insert the code you would use to send to your error logging application here
}
if ( isErrorInstanceOf( 'radioGroup' ) ) {
// Use this option if you want granularity at the individual component level
// Insert the code you would use to send to your error logging application here
}
...Repeat the above for each component that you want to watch for where "radioGroup"
is the name of the component "sl-radio-group". So if you wanted to watch "sl-menu" you
would replace "radioGroup" with "menu". To see what can be used look at addon/utils/error.js.
console.error( error ); // Still send the error to the console
};
If fingerprinting is enabled in the consuming application, then by default the following font types are fingerprinted:
eot, svg, ttf, woff, woff2
IMPORTANT: If you list extensions that are not exact matches to the default ones
set by broccoli-asset-rev, you will need to add the desired font extensions to the extensions property in the consuming application's fingerprinting settings in the ember-cli-build.js file, as demonstrated below:
const EmberApp = require( 'ember-cli/lib/broccoli/ember-app' );
const env = require( './config/environment' );
module.exports = function( defaults ) {
const app = new EmberApp( defaults, {
fingerprint: {
enabled: true,
exclude: [],
extensions: [ 'png', 'jpg', 'gif', 'eot', 'svg', 'ttf', 'woff', 'woff2' ],
prepend: env().baseAssetsURL,
replaceExtensions: [ 'html', 'css', 'js' ]
}
});
return app.toTree();
};
If you wish to modify the styling of the components you have two options for doing so.
The first is to define your CSS declarations in your application's app/styles folder.
The second is to build the CSS declarations from the LESS source files. This will layer any of your LESS values on top of this addon's LESS values which are then in turn laid on top of Twitter Bootstrap's. This does require you though to use LESS for your entire application's CSS generation. To use LESS, run
npm install --save-dev ember-cli-less
then create a app/styles/app.less file and add this to it:
@import 'sl-ember-components';
Finally, you will need to run broccoli-autoprefixer against the updated Twitter Bootstrap and/or LESS files. To do so, run
npm install --save-dev broccoli-autoprefixer
and set the browsers option in your ember-cli-build.js file to:
var autoprefixer = require( 'broccoli-autoprefixer' );
...
tree = autoprefixer(
tree,
{
browsers: [
'Android 2.3',
'Android >= 4',
'Chrome >= 20',
'Firefox >= 24',
'Explorer >= 8',
'iOS >= 6',
'Opera >= 12',
'Safari >= 6'
]
}
);
The options listed in browsers above are the recommended settings by Twitter Bootstrap
Each component has its own unique CSS class selector so that it is easy to target and style specific components. Refer to each component's respective documentation at http://softlayer.github.io/sl-ember-components for these values.
All components share a common CSS prefix, namely, sl-ember-components. To target and style a particular component, for example the sl-grid component, one would use the CSS class selector .sl-ember-components-grid. The reason for such a verbose selector is to prevent styling conflicts with other libraries. You can customize the prefix value and change it from the default sl-ember-components to whatever you would like. Depending on what option you picked in the Styling section, the steps below describe how you would go about customizing the CSS prefix.
To get started, you will need to add a config value to your ember-cli-build.js
var app = new EmberApp(defaults, {
'sl-ember-components': {
componentClassPrefix: 'custom-prefix' // specify your custom prefix here
}
});
If you are not using LESS as a preprocessor then nothing else needs to be done on your part. You should now be able to target components using your custom prefix (e.g. in the case of sl-grid you should now be able to use the CSS class selector .custom-prefix-grid).
If you are using LESS then you will need to set a @component-class-prefix variable below the line of code which imports the sl-ember-components as shown below.
@import 'sl-ember-components'
@component-class-prefix: custom-prefix;
You should now be able to target components using your custom prefix (e.g. in the case of sl-grid you should now be able to use the CSS class selector .custom-prefix-grid).
Note: If you have already served your application, remember to re-serve after making changes to the ember-cli-build.js file so changes can take affect.
If you wish to use different Glyphicons than the defaut ones, you simply only need to redefine
the content definition for the appropriate styles. For example, to replace the "Show All" icon
used for the sl-menu component, use the following declaration:
.sl-ember-components-menu .sl-icon-show-all:before {
content: "\e011";
}
If you wish to use a font library other than Glyphicons Halflings you will need to take a few
extra steps but it is still very easy to do. The first step is to make sure you have properly
installed, and are including, your desired font library. Next, you need to define a
[class^="sl-icon-"], [class*=" sl-icon-"] declaration and copy your font library's main css
declaration into it. The example below demonstrates this, replacing Glyphicons Halflings with
Font Awesome:
[class^="sl-icon-"], [class*=" sl-icon-"] {
display: inline-block;
font: normal normal normal 14px/1 FontAwesome;
font-size: inherit;
text-rendering: auto;
-webkit-font-smoothing: antialiased;
-moz-osx-font-smoothing: grayscale;
}
Then you only need to redefine the content definition in the appropriate styles, as
previously explained above:
.sl-ember-components-menu .sl-icon-show-all:before {
content: "\f270";
}
A loading indicator can be made to display over an element's content, masking it from view, by simply adding the "sl-loading" class to it. This class blurs the content via a dark-colored mask. If a lighter mask is desired then add the additional "inverse" class to the same element.
Examples
If you wish to modify the loading image displayed when applying the "sl-loading" class you can do so by either defining CSS declarations or setting LESS variable values, depending on which Styling approach you are using in your application.
To do so via CSS declarations, define the background-image property for the .sl-loading:after and
.sl-loading.inverse:after selectors.
To do so via LESS, assign values to the @loading-spinner-light and @loading-spinner-dark variables.
Additional modifications can be applied to any of these selectors as well:
- .sl-loading
- .sl-loading:before
- .sl-loading:after
- .sl-loading.inverse:before
- .sl-loading.inverse:after
Examples and documentation on how to use each component can be viewed at http://softlayer.github.io/sl-ember-components
Employs Semantic Versioning 2.0.0
sl-ember-components and its source files are Copyright © 2014-2015 SoftLayer Technologies, Inc. The software is MIT Licensed
sl-ember-components leverages several third-party libraries which are not all MIT licensed. Specifically, Highcharts is only free for non-commercial use and requires a license for any other use. See this FAQ page for more information.
Other libraries that are not MIT licensed, though it should not pose a problem, are:
This software is provided “as is” and without any express or implied warranties, including, without limitation, the implied warranties of merchantability and fitness for a particular purpose.