├── .github ├── PULL_REQUEST_TEMPLATE.md ├── stale.yml ├── ISSUE_TEMPLATE.md ├── CONTRIBUTING.md └── GIT-WORKFLOW.md ├── src ├── SortableInputAsset.php ├── assets │ └── js │ │ ├── kv-sortable-input.min.js │ │ └── kv-sortable-input.js └── SortableInput.php ├── CHANGE.md ├── composer.json ├── LICENSE.md └── README.md /.github/PULL_REQUEST_TEMPLATE.md: -------------------------------------------------------------------------------- 1 | ## Scope 2 | This pull request includes a 3 | 4 | - [ ] Bug fix 5 | - [ ] New feature 6 | - [ ] Translation 7 | 8 | ## Changes 9 | The following changes were made (this change is also documented in the [change log](https://github.com/kartik-v/yii2-sortable-input/blob/master/CHANGE.md)): 10 | 11 | - 12 | - 13 | - 14 | 15 | ## Related Issues 16 | If this is related to an existing ticket, include a link to it as well. -------------------------------------------------------------------------------- /src/SortableInputAsset.php: -------------------------------------------------------------------------------- 1 | 17 | * @since 1.0 18 | */ 19 | class SortableInputAsset extends AssetBundle 20 | { 21 | /** 22 | * @inheritdoc 23 | */ 24 | public function init() 25 | { 26 | $this->setSourcePath(__DIR__ . '/assets'); 27 | $this->setupAssets('js', ['js/kv-sortable-input']); 28 | parent::init(); 29 | } 30 | 31 | } -------------------------------------------------------------------------------- /.github/stale.yml: -------------------------------------------------------------------------------- 1 | # Number of days of inactivity before an issue becomes stale 2 | daysUntilStale: 60 3 | # Number of days of inactivity before a stale issue is closed 4 | daysUntilClose: 7 5 | # Issues with these labels will never be considered stale 6 | exemptLabels: 7 | - bug 8 | - enhancement 9 | - pinned 10 | - security 11 | # Label to use when marking an issue as stale 12 | staleLabel: wontfix 13 | # Comment to post when marking an issue as stale. Set to `false` to disable 14 | markComment: > 15 | This issue has been automatically marked as stale because it has not had 16 | recent activity. It will be closed if no further activity occurs. Thank you 17 | for your contributions. 18 | # Comment to post when closing a stale issue. Set to `false` to disable 19 | closeComment: false -------------------------------------------------------------------------------- /CHANGE.md: -------------------------------------------------------------------------------- 1 | Change Log: `yii2-sortable-input` 2 | ================================= 3 | 4 | ## Version 1.2.1 5 | 6 | **Date:** 29-Aug-2018 7 | 8 | - (bug #12): Correct sortable input plugin for the latest `html5sortable` release. 9 | - Add github contribution and PR/issue log templates. 10 | - Fix composer settings 11 | - Update copyright year to current. 12 | - Reorganize source code in `src` directory. 13 | 14 | ## Version 1.2.0 15 | 16 | **Date:** 29-Jan-2015 17 | 18 | - (enh #1): Plugin enhancement to update parent keys for connected sortables. 19 | 20 | ## Version 1.1.0 21 | 22 | **Date:** 10-Nov-2014 23 | 24 | - Set dependency on Krajee base components 25 | - Set release to stable 26 | 27 | ## Version 1.0.0 28 | 29 | **Date:** 01-Aug-2014 30 | 31 | - Initial release 32 | - PSR4 alias change -------------------------------------------------------------------------------- /composer.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "kartik-v/yii2-sortable-input", 3 | "description": "Sortable input widget based on yii2-sortable extension.", 4 | "keywords": ["yii2", "extension", "widget", "input", "sortable", "range", "jquery", "bootstrap"], 5 | "homepage": "https://github.com/kartik-v/yii2-sortable-input", 6 | "type": "yii2-extension", 7 | "license": "BSD-3-Clause", 8 | "authors": [ 9 | { 10 | "name": "Kartik Visweswaran", 11 | "email": "kartikv2@gmail.com", 12 | "homepage": "http://www.krajee.com/" 13 | } 14 | ], 15 | "require": { 16 | "kartik-v/yii2-sortable": "~1.2" 17 | }, 18 | "autoload": { 19 | "psr-4": { 20 | "kartik\\sortinput\\": "src" 21 | } 22 | }, 23 | "extra": { 24 | "branch-alias": { 25 | "dev-master": "1.2.x-dev" 26 | } 27 | } 28 | } 29 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE.md: -------------------------------------------------------------------------------- 1 | ## Prerequisites 2 | 3 | - [ ] I have searched for similar issues in both open and closed tickets and cannot find a duplicate. 4 | - [ ] The issue still exists against the latest `master` branch of yii2-sortable-input. 5 | - [ ] This is not an usage question. I confirm having gone through and read the [documentation and demos](http://demos.krajee.com/sortable-input). 6 | - [ ] This is not a general programming / coding question. (Those should be directed to the [webtips Q & A forum](http://webtips.krajee.com/questions)). 7 | - [ ] I have attempted to find the simplest possible steps to reproduce the issue. 8 | - [ ] I have included a failing test as a pull request (Optional). 9 | 10 | ## Steps to reproduce the issue 11 | 12 | 1. 13 | 2. 14 | 3. 15 | 16 | ## Expected behavior and actual behavior 17 | 18 | When I follow those steps, I see... 19 | 20 | I was expecting... 21 | 22 | ## Environment 23 | 24 | #### Browsers 25 | 26 | - [ ] Google Chrome 27 | - [ ] Mozilla Firefox 28 | - [ ] Internet Explorer 29 | - [ ] Safari 30 | 31 | #### Operating System 32 | 33 | - [ ] Windows 34 | - [ ] Mac OS X 35 | - [ ] Linux 36 | - [ ] Mobile 37 | 38 | #### Libraries 39 | 40 | - jQuery version: 41 | - yii2-sortable-input version: 42 | 43 | ## Isolating the problem 44 | 45 | - [ ] This bug happens [on the docs and demos page](https://demos.krajee.com/sortable-input) 46 | - [ ] The bug happens consistently across all tested browsers 47 | - [ ] This bug happens when using yii2-sortable-input without other plugins. -------------------------------------------------------------------------------- /LICENSE.md: -------------------------------------------------------------------------------- 1 | Copyright (c) 2014 - 2018, Kartik Visweswaran 2 | Krajee.com 3 | All rights reserved. 4 | 5 | Redistribution and use in source and binary forms, with or without modification, 6 | are permitted provided that the following conditions are met: 7 | 8 | * Redistributions of source code must retain the above copyright notice, this 9 | list of conditions and the following disclaimer. 10 | 11 | * Redistributions in binary form must reproduce the above copyright notice, this 12 | list of conditions and the following disclaimer in the documentation and/or 13 | other materials provided with the distribution. 14 | 15 | * Neither the names of Kartik Visweswaran or Krajee nor the names of its 16 | contributors may be used to endorse or promote products derived from 17 | this software without specific prior written permission. 18 | 19 | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND 20 | ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 21 | WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 22 | DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR 23 | ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 24 | (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 25 | LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON 26 | ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 27 | (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 28 | SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 29 | -------------------------------------------------------------------------------- /src/assets/js/kv-sortable-input.min.js: -------------------------------------------------------------------------------- 1 | /*! 2 | * @copyright Copyright © Kartik Visweswaran, Krajee.com, 2014 - 2018 3 | * @version 1.2.1 4 | * 5 | * JQuery Plugin for yii2-sortable-input. 6 | * 7 | * Author: Kartik Visweswaran 8 | * Copyright: 2014, Kartik Visweswaran, Krajee.com 9 | * For more JQuery plugins visit http://plugins.krajee.com 10 | * For more Yii related demos visit http://demos.krajee.com 11 | */ 12 | !function(t){var e=function(e,i){this.$element=t(e),this.options=i,this.init(i),this.listen()};e.prototype={constructor:e,init:function(e){var i=this;i.$sortable=t("#"+e.sortableId),i.delimiter=e.delimiter,i.$form=i.$element.closest("form"),i.initialValue=i.getKeys(),i.initialContent=i.$sortable.html(),i.$element.val(i.initialValue)},listen:function(){var e=this;e.$sortable.on("sortupdate",function(i){var n=t(i.detail.origin.container);if(n.length){if(n.attr("id")!=e.$sortable.attr("id")){var a=t("input[data-sortable='"+n.attr("id")+"']");a.val(e.getKeys(n)).trigger("change")}e.$element.val(e.getKeys()).trigger("change")}}),e.$form.on("reset",function(){setTimeout(function(){e.$sortable.html(e.initialContent).sortable(e.options),e.$element.val(e.initialValue)},300)})},getKeys:function(){var e=this,i=arguments.length>0?arguments[0]:e.$sortable;return i.find("li").map(function(e,i){return t(i).data("key")}).get().join(e.delimiter)}},t.fn.sortableInput=function(i){var n=Array.apply(null,arguments);return n.shift(),this.each(function(){var a=t(this),r=a.data("sortableInput"),l="object"==typeof i&&i;r||a.data("sortableInput",r=new e(this,t.extend({},t.fn.sortableInput.defaults,l,t(this).data()))),"string"==typeof i&&r[i].apply(r,n)})},t.fn.sortableInput.defaults={sortableId:"",delimiter:","}}(jQuery); -------------------------------------------------------------------------------- /.github/CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | Contributing to yii2-sortable-input 2 | =================================== 3 | Looking to contribute something to yii2-sortable-input? **Here's how you can help.** 4 | 5 | Using the issue tracker 6 | ----------------------- 7 | When [reporting bugs][reporting-bugs] or 8 | [requesting features][requesting-features], the 9 | [issue tracker on GitHub][issue-tracker] is the recommended channel to use. 10 | 11 | The issue tracker **is not** a place for support requests. Refer the 12 | [extension documentation and demos](http://demos.krajee.com/sortable-input) and/or refer to the 13 | [webtips Q & A forum](http://webtips.krajee.com/questions) which are the better places to get help. 14 | 15 | How to contribute via a pull request? 16 | ------------------------------------- 17 | Refer this [git workflow for contributors](.github/GIT-WORKFLOW.md). 18 | 19 | Reporting bugs with yii2-sortable-input 20 | --------------------------------- 21 | We really appreciate clear bug reports that _consistently_ show an issue 22 | within _yii2-sortable-input_. 23 | 24 | The ideal bug report follows these guidelines: 25 | 26 | 1. **Use the [GitHub issue search][issue-search]** — Check if the issue 27 | has already been reported. 28 | 2. **Check if the issue has been fixed** — Try to reproduce the problem 29 | using the code in the `master` branch. 30 | 3. **Isolate the problem** — Try to share a demo or a test case that 31 | consistently reproduces the problem. 32 | 33 | Please try to be as detailed as possible in your bug report, especially if an 34 | isolated test case cannot be made. Some useful questions to include the answer 35 | to are: 36 | 37 | - What steps can be used to reproduce the issue? 38 | - What is the bug and what is the expected outcome? 39 | - What browser(s) and Operating System have you tested with? 40 | - Does the bug happen consistently across all tested browsers? 41 | - What version of jQuery are you using? And what version of yii2-sortable-input? 42 | - Are you using yii2-sortable-input with other plugins? 43 | 44 | All of these questions will help others fix and identify any potential bugs. 45 | 46 | Requesting features in yii2-sortable-input 47 | ------------------------------------ 48 | Before starting work on a major feature for yii2-sortable-input, **read the 49 | [documentation](http://demos.krajee.com/sortable-input) first** or you may risk spending a considerable amount of 50 | time on something which the project developers are not interested in bringing into the project. 51 | 52 | Licensing 53 | --------- 54 | 55 | It should also be made clear that **all code contributed to yii2-sortable-input** must be 56 | licensable under the [BSD-3 license][licensing]. Code that cannot be released 57 | under this license **cannot be accepted** into the project. 58 | 59 | [issue-search]: https://github.com/kartik-v/yii2-sortable-input/search?q=&type=Issues 60 | [issue-tracker]: https://github.com/kartik-v/yii2-sortable-input/issues 61 | [licensing]: https://github.com/kartik-v/yii2-sortable-input/blob/master/LICENSE.md 62 | [reporting-bugs]: #reporting-bugs-with-yii2-sortable-input 63 | [requesting-features]: #requesting-features-in-yii2-sortable-input -------------------------------------------------------------------------------- /src/assets/js/kv-sortable-input.js: -------------------------------------------------------------------------------- 1 | /*! 2 | * @copyright Copyright © Kartik Visweswaran, Krajee.com, 2014 - 2018 3 | * @version 1.2.1 4 | * 5 | * JQuery Plugin for yii2-sortable-input. 6 | * 7 | * Author: Kartik Visweswaran 8 | * Copyright: 2014, Kartik Visweswaran, Krajee.com 9 | * For more JQuery plugins visit http://plugins.krajee.com 10 | * For more Yii related demos visit http://demos.krajee.com 11 | */ 12 | (function ($) { 13 | var SortableInput = function (element, options) { 14 | this.$element = $(element); 15 | this.options = options; 16 | this.init(options); 17 | this.listen(); 18 | }; 19 | 20 | SortableInput.prototype = { 21 | constructor: SortableInput, 22 | init: function (options) { 23 | var self = this, $form; 24 | self.$sortable = $('#' + options.sortableId); 25 | self.delimiter = options.delimiter; 26 | self.$form = self.$element.closest('form'); 27 | self.initialValue = self.getKeys(); 28 | self.initialContent = self.$sortable.html(); 29 | self.$element.val(self.initialValue); 30 | }, 31 | listen: function () { 32 | var self = this; 33 | self.$sortable.on('sortupdate', function (e) { 34 | var $parent = $(e.detail.origin.container); 35 | if (!$parent.length) { 36 | return; 37 | } 38 | if ($parent.attr('id') != self.$sortable.attr('id')) { 39 | var $parentEl = $("input[data-sortable='" + $parent.attr('id') + "']"); 40 | $parentEl.val(self.getKeys($parent)).trigger('change'); 41 | } 42 | self.$element.val(self.getKeys()).trigger('change'); 43 | }); 44 | self.$form.on('reset', function () { 45 | setTimeout(function () { 46 | self.$sortable.html(self.initialContent).sortable(self.options); 47 | self.$element.val(self.initialValue); 48 | }, 300); 49 | }); 50 | }, 51 | getKeys: function () { 52 | var self = this, $sortable = arguments.length > 0 ? arguments[0] : self.$sortable; 53 | return $sortable.find('li').map(function (i, n) { 54 | return $(n).data('key'); 55 | }).get().join(self.delimiter); 56 | 57 | }, 58 | }; 59 | 60 | // sortableInput plugin definition 61 | $.fn.sortableInput = function (option) { 62 | var args = Array.apply(null, arguments); 63 | args.shift(); 64 | return this.each(function () { 65 | var $this = $(this), 66 | data = $this.data('sortableInput'), 67 | options = typeof option === 'object' && option; 68 | 69 | if (!data) { 70 | $this.data('sortableInput', (data = new SortableInput(this, $.extend({}, $.fn.sortableInput.defaults, options, $(this).data())))); 71 | } 72 | 73 | if (typeof option === 'string') { 74 | data[option].apply(data, args); 75 | } 76 | }); 77 | }; 78 | 79 | $.fn.sortableInput.defaults = {sortableId: '', delimiter: ','}; 80 | }(jQuery)); -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 |

2 | 3 | Krajee Logo 4 | 5 |
6 | yii2-sortable-input 7 |
8 | 10 | Donate 11 | 12 |

13 | 14 | [![Stable Version](https://poser.pugx.org/kartik-v/yii2-sortable-input/v/stable)](https://packagist.org/packages/kartik-v/yii2-sortable-input) 15 | [![Unstable Version](https://poser.pugx.org/kartik-v/yii2-sortable-input/v/unstable)](https://packagist.org/packages/kartik-v/yii2-sortable-input) 16 | [![License](https://poser.pugx.org/kartik-v/yii2-sortable-input/license)](https://packagist.org/packages/kartik-v/yii2-sortable-input) 17 | [![Total Downloads](https://poser.pugx.org/kartik-v/yii2-sortable-input/downloads)](https://packagist.org/packages/kartik-v/yii2-sortable-input) 18 | [![Monthly Downloads](https://poser.pugx.org/kartik-v/yii2-sortable-input/d/monthly)](https://packagist.org/packages/kartik-v/yii2-sortable-input) 19 | [![Daily Downloads](https://poser.pugx.org/kartik-v/yii2-sortable-input/d/daily)](https://packagist.org/packages/kartik-v/yii2-sortable-input) 20 | 21 | An input widget for Yii 2.0 widget based on the [yii2-sortable](http://demos.krajee.com/sortable) extension that allows you to create sortable-input lists and grids and manipulate them using simple drag and drop. It extends the yii2-sortable features by allowing you to store the sort order in a form input (which is hidden by default). The widget stores the order as delimited list item keys. The widget includes additional jQuery enhancements to initialize the list, trap sortable order change, and reset order on form reset. 22 | 23 | ### Demo 24 | You can see detailed [documentation](http://demos.krajee.com/sortable-input) on usage of the extension. 25 | 26 | ## Installation 27 | 28 | The preferred way to install this extension is through [composer](http://getcomposer.org/download/). 29 | 30 | > NOTE: Check the [composer.json](https://github.com/kartik-v/yii2-sortable-input/blob/master/composer.json) for this extension's requirements and dependencies. Read this [web tip /wiki](http://webtips.krajee.com/setting-composer-minimum-stability-application/) on setting the `minimum-stability` settings for your application's composer.json. 31 | 32 | Either run 33 | 34 | ``` 35 | $ php composer.phar require kartik-v/yii2-sortable-input "dev-master" 36 | ``` 37 | 38 | or add 39 | 40 | ``` 41 | "kartik-v/yii2-sortable-input": "dev-master" 42 | ``` 43 | 44 | to the ```require``` section of your `composer.json` file. 45 | 46 | ## Usage 47 | 48 | ### SortableInput 49 | 50 | ```php 51 | use kartik\sortinput\SortableInput; 52 | echo SortableInput::widget([ 53 | 'model' => $model, 54 | 'attribute' => 'sort_list', 55 | 'hideInput' => false, 56 | 'delimiter' => '~', 57 | 'items' => [ 58 | 1 => ['content' => 'Item # 1'], 59 | 2 => ['content' => 'Item # 2'], 60 | 3 => ['content' => 'Item # 3'], 61 | 4 => ['content' => 'Item # 4', 'disabled'=>true], 62 | ] 63 | ]); 64 | ``` 65 | 66 | ## License 67 | 68 | **yii2-sortable-input** is released under the BSD-3-Clause License. See the bundled `LICENSE.md` for details. -------------------------------------------------------------------------------- /src/SortableInput.php: -------------------------------------------------------------------------------- 1 | 19 | * @since 1.0 20 | */ 21 | class SortableInput extends \kartik\base\InputWidget 22 | { 23 | /** 24 | * @var array the widget options for `kartik\sortable\Sortable` widget. 25 | */ 26 | public $sortableOptions = ['type' => Sortable::TYPE_LIST]; 27 | 28 | /** 29 | * @var string the delimiter that will be used for separating the id keys 30 | * to store the sorted values in the hidden input 31 | */ 32 | public $delimiter = ','; 33 | 34 | /** 35 | * @var array the sortable data list. You must set it up as `$key => $value` format, where 36 | * - key: int/string, the unique identifier (key) for the item, which will be internally stored. 37 | * - value: array, is the configuration for the items array in sortable widget and can consist of the following properties: 38 | * - content: string, the content to display for the item (this is not HTML encoded). If this is not set, 39 | * it will default the `key` setting. 40 | * - disabled: bool, whether the list item is disabled 41 | * - options: array, the HTML attributes for the list item. 42 | */ 43 | public $items; 44 | 45 | /** 46 | * @var bool whether to hide the input which stores the sorted order. 47 | * Defaults to `true`. 48 | */ 49 | public $hideInput = true; 50 | 51 | /** 52 | * @var array HTML attributes for the input which stores the sorted order. 53 | */ 54 | public $options = ['class' => 'form-control']; 55 | 56 | /** 57 | * @inheritdoc 58 | */ 59 | public function init() 60 | { 61 | parent::init(); 62 | $this->initItems(); 63 | $id = $this->options['id'] . '-sortable'; 64 | $this->sortableOptions['options']['id'] = $id; 65 | $this->options['data-sortable'] = $id; 66 | $this->registerAssets(); 67 | $input = $this->hideInput ? 'hiddenInput' : 'textInput'; 68 | echo Sortable::widget($this->sortableOptions) . PHP_EOL . $this->getInput($input); 69 | } 70 | 71 | /** 72 | * Initialize the sortable input items 73 | * 74 | * @throws InvalidConfigException 75 | */ 76 | protected function initItems() 77 | { 78 | $items = []; 79 | $this->arrangeItems(); 80 | foreach ($this->items as $key => $item) { 81 | if (!isset($item['content'])) { 82 | $item['content'] = $key; 83 | } 84 | $item['options']['data-key'] = $key; 85 | $items[] = $item; 86 | } 87 | $this->sortableOptions['items'] = $items; 88 | } 89 | 90 | /** 91 | * Arranges items based on initial value 92 | */ 93 | protected function arrangeItems() 94 | { 95 | if (empty($this->value)) { 96 | return; 97 | } 98 | $keys = explode($this->delimiter, $this->value); 99 | if (!is_array($keys) || count($keys) == 0) { 100 | return; 101 | } 102 | $items = []; 103 | foreach ($keys as $key) { 104 | $items[$key] = $this->items[$key]; 105 | } 106 | $this->items = $items; 107 | } 108 | 109 | /** 110 | * Register client assets 111 | */ 112 | public function registerAssets() 113 | { 114 | $view = $this->getView(); 115 | SortableInputAsset::register($view); 116 | $this->pluginOptions = [ 117 | 'sortableId' => $this->sortableOptions['options']['id'], 118 | 'delimiter' => $this->delimiter 119 | ]; 120 | $this->registerPlugin('sortableInput'); 121 | } 122 | } -------------------------------------------------------------------------------- /.github/GIT-WORKFLOW.md: -------------------------------------------------------------------------------- 1 | Git workflow for yii2-sortable-input contributors 2 | ========================================= 3 | 4 | So you want to contribute to yii2-sortable-input? Great! But to increase the chances of your changes being accepted quickly, please 5 | follow the following steps. If you are new to Git and GitHub, you might want to first check out [GitHub help](http://help.github.com/), [try Git](https://try.github.com) 6 | or learn something about [Git internal data model](http://nfarina.com/post/9868516270/git-is-simpler). 7 | 8 | Setup the development environment 9 | --------------------------------- 10 | 11 | Assuming you already have a yii2 development environment, carry out the following steps to create a development environment for the repo. 12 | 13 | ### 1. [Fork](http://help.github.com/fork-a-repo/) the yii2-sortable-input repository on GitHub and clone your fork to your development environment 14 | 15 | ``` 16 | git clone git@github.com:YOUR-GITHUB-USERNAME/yii2-sortable-input.git 17 | ``` 18 | 19 | If you have trouble setting up Git with GitHub in Linux, or are getting errors like "Permission Denied (publickey)", 20 | then you must [setup your Git installation to work with GitHub](http://help.github.com/linux-set-up-git/) 21 | 22 | > Tip: if you're not fluent with Git, we recommend reading excellent free [Pro Git book](https://git-scm.com/book/en/v2). 23 | 24 | ### 2. Add the main yii2-sortable-input repository as an additional git remote called "upstream" 25 | 26 | Change to the directory where you cloned yii2-sortable-input, normally, "yii2-sortable-input". Then enter the following command: 27 | 28 | ``` 29 | git remote add upstream git://github.com/kartik-v/yii2-sortable-input.git 30 | ``` 31 | 32 | ### 3. Prepare the testing environment 33 | 34 | - You should have a working yii 2 development environment in which you have already installed `yii2-sortable-input` and includes latest and updated `yii2-sortable-input` fork from source. 35 | - Ensure you have the latest `dev-master` releases of all dependent extensions via your composer updates 36 | - Ensure you use the above cloned latest `yii2-sortable-input` code in your testing environment 37 | 38 | **Now you have a working playground for hacking on yii2-sortable-input.** 39 | 40 | Working on bugs and features 41 | ---------------------------- 42 | 43 | Having prepared your development environment as explained above you can now start working on the feature or bugfix. 44 | 45 | ### 1. Make sure there is an issue created for the thing you are working on if it requires significant effort to fix 46 | 47 | All new features and bug fixes should have an associated issue to provide a single point of reference for discussion 48 | and documentation. Take a few minutes to look through the existing issue list for one that matches the contribution you 49 | intend to make. If you find one already on the issue list, then please leave a comment on that issue indicating you 50 | intend to work on that item. If you do not find an existing issue matching what you intend to work on, please 51 | open a new issue or create a pull request directly if it is straightforward fix. This will allow the team to 52 | review your suggestion, and provide appropriate feedback along the way. 53 | 54 | > For small changes or documentation issues or straightforward fixes, you don't need to create an issue, a pull request is enough in this case. 55 | 56 | ### 2. Fetch the latest code from the main yii2-sortable-input branch 57 | 58 | ``` 59 | git fetch upstream 60 | ``` 61 | 62 | You should start at this point for every new contribution to make sure you are working on the latest code. 63 | 64 | ### 3. Create a new branch for your feature based on the current yii2-sortable-input master branch 65 | 66 | > That's very important since you will not be able to submit more than one pull request from your account if you'll 67 | use master. 68 | 69 | Each separate bug fix or change should go in its own branch. Branch names should be descriptive and start with 70 | the sortable-input of the issue that your code relates to. If you aren't fixing any particular issue, just skip sortable-input. 71 | For example: 72 | 73 | ``` 74 | git checkout upstream/master 75 | git checkout -b 999-name-of-your-branch-goes-here 76 | ``` 77 | 78 | ### 4. Do your magic, write your code 79 | 80 | Make sure you have first updated the testing environment as mentioned in [prepare-the-testing-environment][prepare-the-testing-environment]. 81 | 82 | Then make sure you have the updated code with your change and it works :). 83 | 84 | Unit tests are always welcome. Tested and well covered code greatly simplifies the task of checking your contributions. 85 | Failing unit tests as issue description are also accepted. 86 | 87 | ### 5. Update the CHANGE log 88 | 89 | Edit the `CHANGE.md` file to include your change, you should insert this at the top of the file under the 90 | first heading (the version that is currently under development), the line in the change log should look like one of the following: 91 | 92 | ``` 93 | Bug #999: a description of the bug fix (Your Name) 94 | Enh #999: a description of the enhancement (Your Name) 95 | ``` 96 | 97 | `#999` is the issue sortable-input that the `Bug` or `Enh` is referring to. 98 | The changelog should be grouped by type (`Bug`,`Enh`) and ordered by issue sortable-input. 99 | 100 | For very small fixes, e.g. typos and documentation changes, there is no need to update the `CHANGE.md`. 101 | 102 | ### 6. Commit your changes 103 | 104 | add the files/changes you want to commit to the [staging area](http://gitref.org/basic/#add) with 105 | 106 | ``` 107 | git add path/to/my/file.php 108 | ``` 109 | 110 | You can use the `-p` option to select the changes you want to have in your commit. 111 | 112 | Commit your changes with a descriptive commit message. Make sure to mention the ticket sortable-input with `#XXX` so GitHub will 113 | automatically link your commit with the ticket: 114 | 115 | ``` 116 | git commit -m "A brief description of this change which fixes #999 goes here" 117 | ``` 118 | 119 | ### 7. Pull the latest yii2-sortable-input code from upstream into your branch 120 | 121 | ``` 122 | git pull upstream master 123 | ``` 124 | 125 | This ensures you have the latest code in your branch before you open your pull request. If there are any merge conflicts, 126 | you should fix them now and commit the changes again. This ensures that it's easy for the yii2-sortable-input team to merge your changes 127 | with one click. 128 | 129 | ### 8. Having resolved any conflicts, push your code to GitHub 130 | 131 | ``` 132 | git push -u origin 999-name-of-your-branch-goes-here 133 | ``` 134 | 135 | The `-u` parameter ensures that your branch will now automatically push and pull from the GitHub branch. That means 136 | if you type `git push` the next time it will know where to push to. This is useful if you want to later add more commits 137 | to the pull request. 138 | 139 | ### 9. Open a [pull request](http://help.github.com/send-pull-requests/) against upstream. 140 | 141 | Go to your repository on GitHub and click "Pull Request", choose your branch on the right and enter some more details 142 | in the comment box. To link the pull request to the issue put anywhere in the pull comment `#999` where 999 is the 143 | issue sortable-input. 144 | 145 | > Note that each pull-request should fix a single change. For multiple, unrelated changes, please open multiple pull requests. 146 | 147 | ### 10. Someone will review your code 148 | 149 | Someone will review your code, and you might be asked to make some changes, if so go to step #6 (you don't need to open 150 | another pull request if your current one is still open). If your code is accepted it will be merged into the main branch 151 | and become part of the next yii2-sortable-input release. If not, don't be disheartened, different people need different features and yii2-sortable-input 152 | can't be everything to everyone, your code will still be available on GitHub as a reference for people who need it. 153 | 154 | ### 11. Cleaning it up 155 | 156 | After your code was either accepted or declined you can delete branches you've worked with from your local repository 157 | and `origin`. 158 | 159 | ``` 160 | git checkout master 161 | git branch -D 999-name-of-your-branch-goes-here 162 | git push origin --delete 999-name-of-your-branch-goes-here 163 | ``` 164 | 165 | ### Command overview (for advanced contributors) 166 | 167 | ``` 168 | git clone git@github.com:YOUR-GITHUB-USERNAME/yii2-sortable-input.git 169 | git remote add upstream git://github.com/kartik-v/yii2-sortable-input.git 170 | ``` 171 | 172 | ``` 173 | git fetch upstream 174 | git checkout upstream/master 175 | git checkout -b 999-name-of-your-branch-goes-here 176 | 177 | /* do your magic, update changelog if needed */ 178 | 179 | git add path/to/my/file.php 180 | git commit -m "A brief description of this change which fixes #999 goes here" 181 | git pull upstream master 182 | git push -u origin 999-name-of-your-branch-goes-here 183 | ``` 184 | 185 | [prepare-the-testing-environment]: #3-prepare-the-testing-environment --------------------------------------------------------------------------------