README.md in activeadmin_dynamic_fields-0.2.8 vs README.md in activeadmin_dynamic_fields-0.3.0

- old
+ new

@@ -1,111 +1,110 @@ -# ActiveAdmin Dynamic Fields [![Gem Version](https://badge.fury.io/rb/activeadmin_dynamic_fields.svg)](https://badge.fury.io/rb/activeadmin_dynamic_fields) +# ActiveAdmin Dynamic Fields [![Gem Version](https://badge.fury.io/rb/activeadmin_dynamic_fields.svg)](https://badge.fury.io/rb/activeadmin_dynamic_fields) [![CircleCI](https://circleci.com/gh/blocknotes/activeadmin_dynamic_fields.svg?style=svg)](https://circleci.com/gh/blocknotes/activeadmin_dynamic_fields) -An Active Admin plugin to add dynamic behaviors to fields. +An Active Admin plugin to add dynamic behaviors to some fields. Features: - - set conditional checks on fields -- trigger some actions on other fields +- trigger actions on target elements - inline field editing - create links to load some content in a dialog The easiest way to show how this plugin works is looking the examples [below](#examples). ## Install - - Add to your Gemfile: `gem 'activeadmin_dynamic_fields'` - Execute bundle - Add at the end of your ActiveAdmin javascripts (_app/assets/javascripts/active_admin.js_): -`//= require activeadmin/dynamic_fields` -## Options +```js +//= require activeadmin/dynamic_fields +``` +## Options Options are passed to fields using *input_html* parameter as *data* attributes: - - **data-if**: check a condition, values: + **checked**: check if a checkbox is checked + **not_checked**: check if a checkbox is not checked + **blank**: check if a field is blank + **not_blank**: check if a field is not blank + **changed**: check if the value of an input is changed (dirty) - **data-eq**: check if a field has a specific value - **data-not**: check if a field hasn't a specific value - **data-target**: target css selector (from parent fieldset, look for the closest match) - **data-gtarget**: target css selector globally -- **data-action**: the action to trigger, values: +- **data-then**: the action to trigger (alias **data-action**), values: + **hide**: hides elements + **slide**: hides elements (using sliding) + **fade**: hides elements (using fading) + **addClass**: adds classes + **setValue**: set a value + **callback**: call a function - **data-function**: check the return value of a custom function - **data-arg**: argument passed to the custom set function (as array of strings) +A check condition or a custom check function are required. A trigger action is required too, unless you are using a custom function (in that case it is optional). + ## Examples ### Dynamic fields examples - - A checkbox that hides other fields if is checked (ex. model *Article*): ```rb form do |f| f.inputs 'Article' do - f.input :published, input_html: { data: { if: 'checked', action: 'hide', target: '.grp1' } } + f.input :published, input_html: { data: { if: 'checked', then: 'hide', target: '.grp1' } } f.input :online_date, wrapper_html: { class: 'grp1' } f.input :draft_notes, wrapper_html: { class: 'grp1' } end f.actions end ``` - Add 3 classes (*first*, *second*, *third*) if a checkbox is not checked: -`f.input :published, input_html: { data: { if: 'not_checked', action: 'addClass first second third', target: '.grp1' } }` +`f.input :published, input_html: { data: { if: 'not_checked', then: 'addClass first second third', target: '.grp1' } }` - Set another field value if a string field is blank: -`f.input :title, input_html: { data: { if: 'blank', action: 'setValue 10', target: '#article_position' } }` +`f.input :title, input_html: { data: { if: 'blank', then: 'setValue 10', target: '#article_position' } }` - Use a custom function for conditional check (*title_not_empty()* must be available on global scope) (with alternative syntax for data attributes): -`f.input :title, input_html: { 'data-function': 'title_empty', 'data-action': 'slide', 'data-target': '#article_description_input' }` +`f.input :title, input_html: { 'data-function': 'title_empty', 'data-then': 'slide', 'data-target': '#article_description_input' }` ```js -function title_empty( el ) { - return ( $('#article_title').val().trim() === '' ); +function title_empty(el) { + return ($('#article_title').val().trim() === ''); } ``` - Call a callback function as action: -`f.input :published, input_html: { data: { if: 'checked', action: 'callback set_title', args: '["Unpublished !"]' } }` +`f.input :published, input_html: { data: { if: 'checked', then: 'callback set_title', args: '["Unpublished !"]' } }` ```js -function set_title( args ) { - if( $('#article_title').val().trim() === '' ) { - $('#article_title').val( args[0] ); - $('#article_title').trigger( 'change' ); +function set_title(args) { + if($('#article_title').val().trim() === '') { + $('#article_title').val(args[0]); + $('#article_title').trigger('change'); } } ``` - Custom function without action: `f2.input :category, as: :select, collection: [ [ 'Cat 1', 'cat1' ], [ 'Cat 2', 'cat2' ], [ 'Cat 3', 'cat3' ] ], input_html: { 'data-function': 'on_change_category' }` ```js -function on_change_category( el ) { - var target = el.closest( 'fieldset' ).find( '.pub' ); - target.prop( 'checked', ( el.val() == 'cat2' ) ); - target.trigger( 'change' ); +function on_change_category(el) { + var target = el.closest('fieldset').find('.pub'); + target.prop('checked', (el.val() == 'cat2'); + target.trigger('change'); } ``` ### Inline editing examples - - Prepare a custom member action to save data, an *update* helper function is available (third parameter is optional, allow to filter using strong parameters): ```rb member_action :save, method: [:post] do render ActiveAdmin::DynamicFields.update(resource, params) @@ -139,11 +138,10 @@ div row.title, ActiveAdmin::DynamicFields.edit_string(:title, save_admin_article_path(row.id)) end ``` ### Dialog example - Example with 2 models: *Author* and *Article* Prepare the content dialog - in Active Admin Author config: ```rb @@ -183,17 +181,15 @@ ``` The link url is loaded via AJAX before opening the dialog. ## Do you like it? Star it! - If you use this component just star it. A developer is more motivated to improve a project when there is some interest. Take a look at [other ActiveAdmin components](https://github.com/blocknotes?utf8=✓&tab=repositories&q=activeadmin&type=source) that I made if you are curious. ## Contributors - - [Mattia Roccoberton](http://blocknot.es): author +- The good guys that opened issues and pull requests from time to time ## License - -[MIT](LICENSE.txt) +The gem is available as open-source under the terms of the [MIT](LICENSE.txt).