JQUERY METAL CLONE

THE COMPLETE API DOCUMENTATION, DEMO AND CONFIGURATIONS

Jquery Metal Clone is a jQuery Plugin to Clone HTML DOM element without needed doing it yourself, this plugin will take care of everything. Just seat and drink coffee!

Features

Available Features

Easy to implement together with HTML markup.
Enable placing the cloned element into defined destination.
Specified position cloned element.
Clone the element as many as you want.
With unique ID(s) auto increment.
Clone table rows even column also.
Limit the number of cloned element into specified value.
Available callback on certain action.
* Support for Font Awesome
Many more...

* This plugin by default was using Font Awesome 5 as Icon on both Remove and Create new element button. To utilize this feature, head over to Font Awesome page and download the fonts(Any options). If you're using Font Awesome 4 in your project, no worries as you still able to use by setting the fontAwesomeTheme option into basic. If for some reason, you didn't used font awesome at all, then disable font awesome option by setting enableIcon into false.

Installation

HOW TO INSTALL

Multiples options provided to install this plugin into your projects. Choose any methods that fit your project requirement.

NPM

                            
                                npm install jquery-metal-clone --dev

Yarn

                            
                                yarn add jquery-metal-clone

Bower

                            
                                bower install jquery-metal-clone --save

Or manually download

Download the .zip file, extract, copy and paste into your project directory. Reference it after jquery library:

                            
                                <link href="path/to/metalClone.css" rel="stylesheet">
                                <script src="https://ajax.googleapis.com/ajax/libs/jquery/3.3.1/jquery.js"></script>
                                <script src="path/to/jquery.metalClone.min.js"></script>

Usage

Quick Use

Directly initialized metalClone plugin straight away into HTML element you want to clone.

                        
                        $('.htmlElementYouWantToClone').metalClone();

With above code, it will create automatically for you Remove and Create New Element buttons.

Advance Usage

Example 1

Clone element immediately after last element without copy the value and define custom button to copy existing element.

HTML

Javascript

                        
                            $('.toClone_example1').metalClone({
                                btnClone 	: '.btn_example1',
                                copyValue 	: false
                            });

Output

Example 2

Clone element immediately after last element with value copied and disable animation(only when create and remove element, scrollTop not affected).

HTML

Javascript

                        
                            $('.toClone_example2').metalClone({
                                btnClone 	: '.btn_example2',
                                copyValue 	: true,
                                enableAnimation: false
                            });

Output

Example 3

Clone element [before first element] with Bootstrap class attached on remove button.

HTML

Javascript

                        
                            $('.toClone_example3').metalClone({
                                btnClone 	: '.btn_example3',
                                position	: 'before',
                                btnRemoveClass: 'btn btn-danger btn-sm'
                            });

Output

Example 4

Clone element [immediate after last element] with specified the number of element to clone/copy and disable confirm message.

HTML

Javascript

                        
                            $('.toClone_example4').metalClone({
                                btnClone 	: '.btn_example4',
                                numberToClone: 3,
                                enableConfirmMessage: false
                            });

Output

Example 5

Clone element immediately after last element with [destination to place the newly cloned element and custom remove message].

HTML

Javascript

                        
                            $('.toClone_example5').metalClone({
                                btnClone 	: '.btn_example5',
                                confirmMessageText: 'This is the custom message. Are you sure to remove this element?',
                                destination: '#toClone_example5_output',
                            });

Output

Destination

New element will placed inside here

Example 6

Clone element immediately after last element with [unique ID(s)].

HTML

Javascript

                        
                            $('.toClone_example6').metalClone({
                                btnClone 	: '.btn_example6',
                                enableConfirmMessage: false,
                                ids: ['input'] // or put [*] for all element with ID(s)
                            });

Output

Example 7

Clone element immediately after last element without [specified clone button(will create new one with name "Create New Element")]. To specify clone button text, use btnCloneText option.

HTML

Javascript

                        
                            $('.toClone_example7').metalClone();

Output

Example 8

Clone element with [limit element to clone]. Once limit reached, error message will appear. You can override its style by overriding .metal-error-limit class and overriding its message using cloneLimitText option.

HTML

Javascript

                        
                            $('.toClone_example8').metalClone({
                                cloneLimit: 3
                            });

Output

Example 9

Even work with [table rows]. To override Remove button styling, you can override .metal-btn-remove or .operationsImg or .operations.

HTML

Javascript

                        
                            $('.toClone_example9').metalClone({
                                cloneLimit: 3
                            });

Output

First Name	Last Name

Configuration Options

Options	Description
destination default: null	Specify the destination to place the cloned element, if not specified, the cloned element will be placed after the last element or before depend on the position option. Destination should be container. E.g: Then the destination should be #myDestination.
position default: 'after'	Specify the position to place the cloned element. Available options before and after.
numberToClone default: 1	Number of clone element you want to clone at the same time. Please don't put big number as it might slow down cloning process.
ids default: []	Any HTML tag element that have an id attribute to make these ID(s) unique. Accept multiples values as array list. E.g : `ids: ['div','input', 'select']` If you want to serialize all the ID(s) of HTML elements within cloned element, then put [*].
btnClone default: null	Put your selector(button class or id name or any css selector(not recommended)). If not specified, the plugin will create a new one for clone button. E.g : `btnClone: '.clickMe' // #btnClone` .clickMe might be a button.
copyValue default: false	Should copy including field's value or just leave empty. Available options either true and false.
btnRemoveText default: 'Remove'	Text to appear on remove button.
btnRemoveClass default: null	Specify class name for remove button. Very convenient if you want to decorate remove button with your own css styling or you can specify bootstrap's class name. E.g: `btnRemoveClass: 'btn btn-danger btn-sm'` To give you more control, this plugin provide metal-btn-remove class name to override. E.g: `.metal-btn-remove { // do any styling }`
btnCloneText default: 'Create New Element'	Text to appear on clone button. Only available when you didn't specify btnClone option.
btnCloneClass default: null	Specify class name for clone button. Very convenient if you want to decorate clone button with your own css styling or you can specify bootstrap's class name. E.g: `btnCloneClass: 'btn btn-primary btn-sm' // or use your own css class name`
cloneLimit default: 'infinity'	Accept integer number. This option limit the number of clone element being cloned. After reach the value provided, user no longer can clone element unless remove the cloned element and message will appeared right after the clone button. To give you more control, this plugin provide metal-clone-limit class name to override. E.g: `.metal-clone-limit { // do any styling }`
cloneLimitText default: 'Clone limit reached'	Text to appear when clone limit reached.
cloneLimitClass default: null	Specify class name for clone limit message's element. Very convenient if you want to decorate clone limit message with your own css styling. E.g: `cloneLimitClass: '.my-own-limit-styling'`
enableIcon default: true	This plugin by default was using Font Awesome 5 as Icon on both Remove and Create new element button. To utilize this feature, head over to Font Awesome page and download the fonts(Any options). If you're using Font Awesome 4 in your project, no worries as you still able to use by setting the fontAwesomeTheme option into basic. If for some reason, you didn't used font awesome at all, then disable font awesome option by set this option into false.
fontAwesomeTheme default: 'solid'	Font awesome theme used by this plugin. Available options regular, solid, brand, light and basic (for Font awesome 4) . If you set this option as a basic, then you might need to set both fontAwesomeRemoveClass and fontAwesomeAddClass options to available class(see font awesome 4 for more details). Only available when enableIcon option is set to true.
fontAwesomeRemoveClass default: 'fa-trash-alt'	Font awesome class's name for remove button. You might need to choose font awesome class's name that available with fontAwesomeTheme option. Refer Font Awesome for more details. Only available when enableIcon option is set to true.
fontAwesomeAddClass default: 'fa-plus'	Font awesome class's name for clone button. You might need to choose font awesome class's name that available with fontAwesomeTheme option. Refer Font Awesome for more details. Only available when enableIcon and btnClone option is set to true and not null respectively.
fontAwesomeAddDataTransform default: ''	Enabling data transform for clone button. Only available when enableIcon option is set to true. E.g : If you set this option to shrink-8, behind the scene the plugin will create for you below markup. Refer Font Awesome for more details.
fontAwesomeAddDataMask default: ''	Enabling data masking for clone button. Only available when enableIcon option is set to true. E.g : If you set this option to fas fa-comment class's name, behind the scene the plugin will create for you below markup. Refer Font Awesome for more details.
fontAwesomeRemoveDataTransform default: ''	Enabling data transform for remove button. Only available when enableIcon option is set to true. E.g : If you set this option to shrink-8, behind the scene the plugin will create for you below markup. Refer Font Awesome for more details.
fontAwesomeRemoveDataMask default: ''	Enabling data masking for remove button. Only available when enableIcon option is set to true. E.g : If you set this option to fas fa-comment class's name, behind the scene the plugin will create for you below markup. Refer Font Awesome for more details.
enableConfirmMessage default: true	By default, plugin will popup confirm message when remove button was clicked. Set this option to false to disable. Available options true and false.
confirmMessageText default: 'Are you sure?'	Specify confirm message text. Only available when enableConfirmMessage option set to true.
enableAnimation default: true	By default, plugin will animate(slideDown) clone element being cloned when clone button is clicked. To disable animation, set this option to false. Available options true and false.
animationSpeed default: 400	Animation's(slideDown) speed. Accept integer value. Only available when enableAnimation option set to true.
enableScrollTop default: true	Plugin will scroll page to the top of cloned element's position. To disable scroll top, set this option to false. Available options true and false.
scrollTopSpeed default: 1000	ScrollTop's speed. Accept integer value. Only available when enableScrollTop option set to true.
Callback Function
onStart default: null	OnStart callback triggered at very first plugin Initialization. At here you can setup any behaviours. Accept one argument: element : element to clone E.g: `$('.htmlElementToClone').metalClone({ onStart: function(element) { console.log(element); } });`
onClone default: null	OnClone callback triggered when clone button was clicked. Accept 2 arguments: element : element to clone obj : object itself This callback triggered before the cloning element occur. During this time you can check for element that want to clone or anything. At here, the only function can be invoked is .cancelClone(true or false). This function will stop current progress of cloning element if called. E.g: `$('.htmlElementToClone').metalClone({ onClone: function(element, obj) { obj.cancelClone(true); } });`
onComplete default: null	OnComplete callback were triggered when cloning process of element done/complete/finish. Accept 3 arguments: element : element to clone obj : object itself clonedElem : The cloned element. At here, the only function can be invoked is .removeCloned(true or false). This function will remove cloned element and only available on this callback. Eg: `$('.htmlElementToClone').metalClone({ onComplete: function(element, obj) { obj.removeCloned(true); } });` When obj.removeCloned(true) is called, onClonedRemoved callback also triggered.
onClonedRemoved default: null	onClonedRemoved callback triggered after remove button was clicked AND element is completely removed from page. Accept 1 argument: removedElem : Which is the element that are being removed `$('.htmlElementToClone').metalClone({ onClonedRemoved: function(removedElem) { console.log(removedElem); } });`

License

MIT License

JQUERY METAL CLONE is licensed under MIT.

Copyright (c) 2018 Norlihazmey Ghazali

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Donation

I hope you like this project, fork this repo or chip in for a cup of Coffee. Thank You very much! ~ "One good turn deserves another".