@fonticonpicker/fonticonpicker
v3.1.1
Published
jQuery Plugin which allows you to include a simple icon picker with search and pagination inside your administration forms.
Downloads
13,508
Readme
jQuery fontIconPicker v3.1.1
jQuery fontIconPicker is a small (4.05KB
gzipped) jQuery plugin which allows you to include an elegant icon picker with categories, search and pagination inside your administration forms. The list of icons can be loaded manually using a SELECT
field, an Array
or Object
of icons or directly from a Fontello config.json
or IcoMoon selection.json
file. Go to the official plugin page for examples and documentation.
fontIconPicker v3.x supports jQuery 1.12.4
through 3.3.0
.
Originally developed at micc83/fontIconPicker and now moved into separate organization for better collaboration.
Installation
With NPM/YARN
fontIconPicker has been released over NPM. So you can either use NPM to install or download a release.
npm install [email protected] @fonticonpicker/fonticonpicker --save
Now use with webpack or browserify.
const jQuery = require( 'jquery' );
const fip = require( '@fonticonpicker/fonticonpicker' )( jQuery );
jQuery( '.selector' ).fontIconPicker( {
// Options
} );
Global script
/ CDN support
You can put fontIconPicker dependencies directly in your html
with <script>
and <link>
tags. Go to fontIconPicker Releases and download the
fontIconPicker.zip
file from latest Assets. It will contain all scripts and
styles built for production use.
You can also use CDN from unpkg.com.
<!-- styles -->
<!-- base | always include -->
<link rel="stylesheet" type="text/css" href="https://unpkg.com/@fonticonpicker/fonticonpicker/dist/css/base/jquery.fonticonpicker.min.css">
<!-- default grey-theme -->
<link rel="stylesheet" type="text/css" href="https://unpkg.com/@fonticonpicker/fonticonpicker/dist/css/themes/grey-theme/jquery.fonticonpicker.grey.min.css">
<!-- optional themes | no need to include default theme -->
<link rel="stylesheet" type="text/css" href="https://unpkg.com/@fonticonpicker/fonticonpicker/dist/css/themes/bootstrap-theme/jquery.fonticonpicker.bootstrap.min.css">
<link rel="stylesheet" type="text/css" href="https://unpkg.com/@fonticonpicker/fonticonpicker/dist/css/themes/dark-grey-theme/jquery.fonticonpicker.darkgrey.min.css">
<link rel="stylesheet" type="text/css" href="https://unpkg.com/@fonticonpicker/fonticonpicker/dist/css/themes/inverted-theme/jquery.fonticonpicker.inverted.min.css">
<!-- scripts -->
<script type="text/javascript" src="https://unpkg.com/@fonticonpicker/fonticonpicker/dist/js/jquery.fonticonpicker.min.js"></script>
Using ES6 Module
If you wish to use ES6
module, then you have to initialize manually.
import jQuery from 'jquery';
import initFontIconPicker from '@fonticonpicker/fonticonpicker';
// Initiate the jQuery plugin
initFontIconPicker( jQuery );
jQuery( '.selector' ).fontIconPicker( {
// Options
} );
Right now, the only feasible way to properly initiate fontIconPicker
through
rollupjs is to pass jQuery directly in the initFontIconPicker
function. If
you know a better way, feel free to suggest.
How it works
Just include a copy of jQuery, the fontIconPickers script, the fontIconPickers theme and your Font Icons. Now you can trigger it on a SELECT
or INPUT[type="text"]
element.
Include the JavaScript
<!-- jQuery -->
<script type="text/javascript" src="jquery-1.12.4.min.js"></script>
<!-- fontIconPicker JS -->
<script type="text/javascript" src="js/jquery.fonticonpicker.min.js"></script>
Include the CSS
<!-- fontIconPicker core CSS -->
<link rel="stylesheet" type="text/css" href="css/base/jquery.fonticonpicker.min.css" />
<!-- required default theme -->
<link rel="stylesheet" type="text/css" href="css/themes/grey-theme/jquery.fonticonpicker.grey.min.css" />
<!-- optional themes -->
<link rel="stylesheet" type="text/css" href="css/themes/dark-grey-theme/jquery.fonticonpicker.darkgrey.min.css" />
<link rel="stylesheet" type="text/css" href="css/themes/bootstrap-theme/jquery.fonticonpicker.bootstrap.min.css" />
<link rel="stylesheet" type="text/css" href="css/themes/inverted-theme/jquery.fonticonpicker.inverted.min.css" />
Include Font Icons
<!-- Font -->
<link rel="stylesheet" type="text/css" href="fontello-7275ca86/css/fontello.css" />
<link rel="stylesheet" type="text/css" href="icomoon/icomoon.css" />
Initialize with jQuery
Finally call the fontIconPicker on a SELECT
or INPUT[type="text"]
element.
<!-- SELECT element -->
<select id="myselect" name="myselect" class="myselect">
<option value="">No icon</option>
<option>icon-user</option>
<option>icon-search</option>
<option>icon-right-dir</option>
<option>icon-star</option>
<option>icon-cancel</option>
<option>icon-help-circled</option>
<option>icon-info-circled</option>
<option>icon-eye</option>
<option>icon-tag</option>
<option>icon-bookmark</option>
<option>icon-heart</option>
<option>icon-thumbs-down-alt</option>
<option>icon-upload-cloud</option>
<option>icon-phone-squared</option>
<option>icon-cog</option>
<option>icon-wrench</option>
<option>icon-volume-down</option>
<option>icon-down-dir</option>
<option>icon-up-dir</option>
<option>icon-left-dir</option>
<option>icon-thumbs-up-alt</option>
</select>
<!-- JavaScript -->
<script type="text/javascript">
// Make sure to fire only when the DOM is ready
jQuery(document).ready(function($) {
$('#myselect').fontIconPicker(); // Load with default options
});
</script>
<!-- INPUT element -->
<input type="text" name="mytext" id="mytext" />
<script type="text/javascript">
jQuery(document).ready(function($) {
$('#mytext').fontIconPicker({
source: ['icon-heart', 'icon-search', 'icon-user', 'icon-tag', 'icon-help'],
emptyIcon: false,
hasSearch: false
});
});
</script>
Plugin Options
Here's fontIconPicker options:
var $picker = $('.picker').fontIconPicker({
theme : 'fip-grey', // The CSS theme to use with this fontIconPicker. You can set different themes on multiple elements on the same page
source : false, // Icons source (array|false|object)
emptyIcon : true, // Empty icon should be shown?
emptyIconValue : '', // The value of the empty icon, change if you select has something else, say "none"
autoClose : true, // Whether or not to close the FIP automatically when clicked outside
iconsPerPage : 20, // Number of icons per page
hasSearch : true, // Is search enabled?
searchSource : false, // Give a manual search values. If using attributes then for proper search feature we also need to pass icon names under the same order of source
appendTo : 'self', // Where to append the selector popup. You can pass string selectors or jQuery objects
useAttribute : false, // Whether to use attribute selector for printing icons
attributeName : 'data-icon', // HTML Attribute name
convertToHex : true, // Whether or not to convert to hexadecimal for attribute value. If true then please pass decimal integer value to the source (or as value="" attribute of the select field)
allCategoryText : 'From all categories', // The text for the select all category option
unCategorizedText : 'Uncategorized', // The text for the select uncategorized option
iconGenerator : null, // Icon Generator function. Passes, item, flipBoxTitle and index
windowDebounceDelay: 150, // Debounce delay while fixing position on windowResize
searchPlaceholder : 'Search Icons' // Placeholder for the search input
});
Plugin APIs
fontIconPicker provides three public APIs to manipulating the icon picker.
setIcon( String
newIcon )
Use this method to set an icon programmatically.
$picker.setIcon( 'fa fa-arrow-down' );
setIcons( Array|Object
newIcons, Array|Object
iconSearch )
Use this method to dynamically change icons on the fly. newIcons
and iconSearch
(optional) have same datatypes as source
and searchSource
options.
$picker.setIcons(['icon-one', 'icon-two']);
$picker.setIcons(['icon-one', 'icon-two'], ['Icon one will be searched by this', 'Icon two will be searched by this']);
setPage( String|Number
pageNum )
Use this method to programmatically set pagination in the fip popup. This persists between open and close state until user has changed pagination manually.
$picker.setPage( 2 );
$picker.setPage( 'first' );
$picker.setPage( 'last' );
Method accepts numbers and only two special strings.
- Number corresponds to the page number starting from 1.
first
will set the pagination to first page.last
will set the pagination to last page.
destroyPicker()
Use this to remove the icon picker and restore the original element.
$picker.destroyPicker();
refreshPicker( Object|Boolean
newOptions )
Refresh the icon picker from DOM or passed options. Useful when DOM has been changed or reinitializing after calling the destroy method or changing the options values.
$picker.refreshPicker({
theme: 'fip-bootstrap',
hasSearch: false
});
repositionPicker()
Reposition picker dropdown in the window. Use this if DOM has changed and dropdown is open. Or if your picker is inside a scrolling container.
var picker = $('.myselect').fontIconPicker();
$('.mycontainer').on( 'scroll', function() {
picker.repositionPicker();
} );
Options and APIs are discussed in details with live examples at the project page.
Important notes for local demo
Only when loading demo locally: In firefox fontIconPicker icons won't be shown correctly because of CORS. For the same reason "Load icons from Fontello JSON config file" won't work on Chrome or IE 10. If you need to do some local testing you can disable strict_origin_policy at your risk.
Use the bundled Browsersync server to run the demo instead. See Setup to learn how.
Browser Compatibility
jQuery iconPicker has been successfully tested on: Firefox (edge), Safari (edge), Chrome (edge), IE8+ and Opera (edge).
jQuery Compatibility
jQuery
>= 1.12.4 has been set as peerDependencies
in the package.json
. We have
tested with 1.x
and 3.x
branch. jQuery Migrate doesn't produce any error when
using with 3.x
.
Development Environment
If you want to contribute keep a few things in mind.
- Any code shouldn't produce any error with ESLint and Stylelint. We check for errors during build and if it does produce any error, then it will be rejected.
- All new JS code should have unit or integration test implemented with jest.
Setup
First make sure Node >= v8 is installed. Then clone the repository
git clone [email protected]:fontIconPicker/fontIconPicker.git
and run
cd fontIconPicker
npm install
npm install -g npx
Which will install all dependencies. You do not need to install jquery
as it
is defined in devDependencies
.
Now edit the files in src
as needed and while you do, run
npx gulp serve
This will serve the changes live in your browser. Access it through http://localhost:3000
.
Coding Standards
- All additional modules should go inside
src/js/modules
with unit tests in__tests__/unit
. - Write JS in ES6. This is a great place to learn. It will be compiled with babel on the go.
- Do not write CSS files directly. Write SCSS. It will
be compiled when
npx gulp serve
is running. - If you are writing a theme, include in the first box of
demo/index.html
. - If you are writing an option or API, include in a separate box of
demo/index.html
. - All new JS features should have unit/integration and/or e2e tests. We use cypress for e2e tests and jest for unit/integration tests.
Automated git hooks
When you run npm install
for the first time, husky setups a few git hooks. It specifically
does two things.
- Checks for proper commit message.
- Runs linting of
js
andscss
files to avoid any error before push.
Continuous Integration (CI)
Additionally we run test suits for each push on travis ci.
Make sure it passes by running
npm run test
locally on your machine. It lints all files and runs jest
tests.
Running tests locally
fontIconPicker has two sets of tests.
Unit & Integration test with jest
npx jest
End2End test with cypress
npx cypress open
Then run the tests from the app. Or
npx cypress run
To run the tests in the terminal from a headless browser. You do not need to worry about setting up test environment as it is taken care of automatically by cypress.
Available Gulp Commands
default
- Builds all scripts/styles and put them indist
folder.build
- Same as default.lint
- Lint all CSS and JS files.lint:script
- Lint all JS files.lint:style
- Lint all SCSS files.
fonts
- Copy font files todist
directory.serve
- Build the files, init browsersync and watch files to create dev env.
Run these commands with npx
.
Credits
jQuery fontIconPicker has been made by Alessandro Benoit & swashata. You can use the issue tracker for reporting bugs or feature requests.
Special thanks to miniMAC for the idea, Zeno Rocha for jQuery plugin boilerplate, Dave Gandy & KeyaMoon for the beautiful sets of icons and Elliot Condon for the amazing Advanced Custom Field WordPress plugin.