{"id":22056835,"url":"https://github.com/letsjump/yii2-easy-ajax","last_synced_at":"2025-05-12T16:03:27.774Z","repository":{"id":57014184,"uuid":"84583945","full_name":"letsjump/yii2-easy-ajax","owner":"letsjump","description":"Relax your keyboard with Yii2 EasyAjax","archived":false,"fork":false,"pushed_at":"2021-10-01T09:38:36.000Z","size":212,"stargazers_count":4,"open_issues_count":1,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-10-28T13:24:26.543Z","etag":null,"topics":["ajax","bootstrap","crud","modals","yii2"],"latest_commit_sha":null,"homepage":"https://yii.beintech.it/","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/letsjump.png","metadata":{"files":{"readme":"README.md","changelog":"changelog.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null}},"created_at":"2017-03-10T17:22:04.000Z","updated_at":"2023-05-19T13:36:39.000Z","dependencies_parsed_at":"2022-08-21T14:50:30.632Z","dependency_job_id":null,"html_url":"https://github.com/letsjump/yii2-easy-ajax","commit_stats":null,"previous_names":[],"tags_count":22,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/letsjump%2Fyii2-easy-ajax","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/letsjump%2Fyii2-easy-ajax/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/letsjump%2Fyii2-easy-ajax/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/letsjump%2Fyii2-easy-ajax/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/letsjump","download_url":"https://codeload.github.com/letsjump/yii2-easy-ajax/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":226918542,"owners_count":17703175,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ajax","bootstrap","crud","modals","yii2"],"created_at":"2024-11-30T16:14:57.921Z","updated_at":"2024-11-30T16:14:58.035Z","avatar_url":"https://github.com/letsjump.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# yii2-easy-ajax\n\nRelax your keyboard with [Yii2 EasyAjax](https://yii.beintech.it/)\n\nEasyAjax are a bunch of Yii methods that minimize the amount of code you need to write to interact with Bootstap UI and with Javascript in general.\n\n[Notifies](#notify), [modals](#modals), [tabs](#ajax-tabs), [pjax-reloads](#pjax-reload), [form validation](#form-validation) among others can now be set up and launched with only a line of code into the controller's action response.  \n\nFor example,  `EasyAjax::modal('My modal content')` opens a modal with \"My modal content\" as _content_, while `EasyAjax::reloadPjax(['#p0'])` reloads the `pjax-container` identified by `id=\"p0\"`\n\nEasyAjax further provides:\n\n- Complete and ready-to-use **ajax CRUD**, thanks to the integrated [Gii generator](#Ajax-CRUD-with-Gii)\n- Fully configurable options both globally and action-specific\n- Customizable HTML templates\n- Extensible with your own methods\n\n## Installation\nThe preferred way to install this extension is through [composer](http://getcomposer.org/download/).\n\nEither run\n\n\n```composer require --prefer-dist letsjump/yii2-easy-ajax```\n\n\nor add\n\n\n```\"letsjump/yii2-easy-ajax\": \"~1.0.0\"```\n\nto the `require` section of your composer.json.\n\n## Configuration\n\nTo use this extension, add the following code to your web application configuration (config/web.php):\n\n```php\n'components' =\u003e [\n    'easyAjax' =\u003e [\n        'class' =\u003e 'letsjump\\easyAjax\\EasyAjaxBase',\n        'customOptions' =\u003e [\n            /* refer to plugin documentation */\n        ]\n    ],\n]\n```\n\nTo use the integrated [Gii generator](#Ajax-CRUD-with-Gii), add the following code to your application configuration:\n\n```php\nif (YII_ENV_DEV) {\n    $config['bootstrap'][] = 'gii';\n    $config['modules']['gii'] = [\n        'class' =\u003e \\yii\\gii\\Module::class,\n        // uncomment the following to add your IP if you are not connecting from localhost.\n        'allowedIPs' =\u003e ['127.0.0.1', '::1', /** your IPs */],\n        'generators' =\u003e [\n            'crud' =\u003e [ \n                'class'     =\u003e 'letsjump\\easyAjax\\gii\\crud\\Generator',\n                'templates' =\u003e [ //setting for out templates\n                    'yii2-easy-ajax' =\u003e '@vendor/letsjump/yii2-easy-ajax/gii/crud/default',\n                ]\n            ],\n        ],\n    ];\n}\n```\n\nPlease note: The integrated [Gii generator](#Ajax-CRUD-with-Gii) allows you to generate the code for AJAX as well as the standard CRUD.\n\n## Usage\n\n- [1. Requests](#1.-Requests)\n- [2. Responses](2.-Responses)\n\n### 1. Requests\n\nEasyAjax requests are simple jQuery AJAX requests that need to refer to a controller action appropriately configured:\n\nThe easiest way to perform an EasyAjax request to a controller action is adding the `data-yea=1` attribute to the Html tag in charge of the _onclick javascript event_:\n\n```html\n\u003ca data-yea=\"1\" class=\"btn btn-lg btn-success\" href=\"\u003c?= \\yii\\helpers\\Url::to(['controller/action-notify']) ?\u003e\"\u003enotify something\u003c/a\u003e\n```\n\nor\n\n```html\n\u003cbutton data-yea=\"1\" data-form-id=\"friend-form\" type=\"submit\" class=\"btn btn-primary pull-right\"\u003eSave\u003c/button\u003e\n```\n\n\u003e NOTE:\n\u003e \n\u003e To explore any other Html attributes available and to know all the details, please refer to the [guide](docs/guide/requests.md)\n\n### 2. Responses\n\nThe controller actions interacting with EasyAjax should return a _Json array_, and they only need to contain one or more EasyAjax methods in their response array. \n\nIn the following example...\n\n```php\npublic function actionSaveMyModel()\n{\n    Yii::$app-\u003eresponse-\u003eformat = \\yii\\web\\Response::FORMAT_JSON;\n\n    // your model validation and save logic...\n\n    return [\n        \\letsjump\\easyAjax\\EasyAjax::modalClose(),\n        \\letsjump\\easyAjax\\EasyAjax::reloadPjax(['#p0']),\n        \\letsjump\\easyAjax\\EasyAjax::notifySuccess('Your model has been saved')\n    ];\n}\n```\n... EasyAjax will:\n- Closes the [bootstrap modal](https://getbootstrap.com/docs/3.4/javascript/#modals) opened in the UI\n- [Reload](https://github.com/yiisoft/jquery-pjax#fnpjax) the pjax-container `#p0`\n- Shows a [Bootstrap Notify](http://bootstrap-notify.remabledesigns.com/) informing the user of the successful operation\n\nHere are the available methods in detail:\n\n#### Modals\n\nWith EasyAjax, you can fire and configure a [Bootstrap Modal](https://getbootstrap.com/docs/3.4/javascript/#modals) using the following: \u003ccode\u003eEasyAjax::modal(content, title, _form_id, size, footer, options_)\u003c/code\u003e\n\n```php\npublic function actionModal()\n{\n    Yii::$app-\u003eresponse-\u003eformat = \\yii\\web\\Response::FORMAT_JSON;\n    \n    return [\n        \\letsjump\\easyAjax\\EasyAjax::modal('This is the modal content', 'Modal title'),\n    ];\n}\n```\n\nIt is also available a method to remotely close a Modal which is actually open in the UI:\n\n```php\npublic function actionCloseModal()\n{\n    Yii::$app-\u003eresponse-\u003eformat = \\yii\\web\\Response::FORMAT_JSON;\n    \n    return [\n        \\letsjump\\easyAjax\\EasyAjax::modalClose(),\n    ];\n}\n\n```\n\n \u003e You can edit the modal layout and many other settings. Please refer to the [guide](docs/guide/modals.md) for all the available options.\n\n---\n\n#### Notify\n\n**EasyAjax Notify** allows to control the [Bootstrap Notify plugin](http://bootstrap-notify.remabledesigns.com/). The plugin assets (`bootstrap-notify.js` and `animate.js`) are bundled within EasyAjax. \n\n\u003e Tip: You can disable the asset inclusion if it is already bundled in your application\n\nTo fire a Notify, you can use \u003ccode\u003e\\letsjump\\easyAjax\\EasyAjax::notify(message, *title*, *settings*)\u003c/code\u003e.\nIn the `settings` parameter, you should specify the type of notification displayed (`Notify::TYPE_INFO` (blue), `Notify::TYPE_SUCCESS` (green), `Notify::TYPE_WARNING` (yellow) or `Notify::TYPE_DANGER` (red)).\n\nTo speed up your coding, I have also added some shortcut methods for the most common notification types: `EasyAjax::notifyInfo(message)`, `EasyAjax::notifySuccess(message)`, `EasyAjax::notifyWarning(message)`, `EasyAjax::notifyDanger(message)`.\n\nExample:\n\n```php\npublic function actionNotify()\n{\n    Yii::$app-\u003eresponse-\u003eformat = \\yii\\web\\Response::FORMAT_JSON;\n    return [\n        \\letsjump\\easyAjax\\EasyAjax::notifyInfo('This is an Info Notify!')\n    ];\n}\n```\n\n\u003e Note: Actually notify doesn't refer to the [Yii2 flash message session array](https://www.yiiframework.com/doc/api/2.0/yii-web-session#$flash-detail). Please open an issue if you think it is needed.\n\u003e\n\u003e Refer to the [guide](docs/guide/notify.md) for all the available options and template manipulation.\n\n---\n#### Pjax Reload\n\nThe EasyAjax PjaxReload (`EasyAjax::pjaxReload(['#myPjaxID0', '#myPjaxID1', ...])`) method allows to reload one or more Pjax containers.\n\n```php\npublic function actionPjaxReload()\n{\n    Yii::$app-\u003eresponse-\u003eformat = \\yii\\web\\Response::FORMAT_JSON;\n    \n    return [\n        \\letsjump\\easyAjax\\EasyAjax::reloadPjax(['#p0'])\n    ];\n}\n```\n\n\u003e Refer to the [guide](docs/guide/pjax-reload.md) for detailed informations.\n\n---\n#### Form Validation\n\nThe form validation (`EasyAjax::formValidation(['#my-form-id'=\u003eActiveForm::validate(MyModelClass)])`) method allows to display the validation results for the specified form. It will send the validation results for each form field specified by the `#form-id` attribute to [display its error messages](https://github.com/samdark/yii2-cookbook/blob/master/book/forms-activeform-js.md).\n\n```php\npublic function actionValidateForm()\n{\n    Yii::$app-\u003eresponse-\u003eformat = \\yii\\web\\Response::FORMAT_JSON;\n    $contactForm                = new ContactForm();\n    \n    return [\n        \\letsjump\\easyAjax\\EasyAjax::formValidation(['#contact-form' =\u003e \\yii\\widgets\\ActiveForm::validate($contactForm)])\n    ];\n}\n``` \n\u003e Refer to the [guide](docs/guide/form-validation.md) for detailed informations.\n\n---\n#### Ajax CRUD with Gii\n\nThe bundled Gii generator within EasyAjax allows you to instantly create the Ajax CRUD controller and views. \n\n![Gii module](docs/images/gii.jpg)\n\nThis will generate a CRUD schema which is identical to the Yii2 original one, with an added `actionModal($id=null)` into the controller code, plus its relative \u003ccode\u003e_myViewFolder_/_modal.php\u003c/code\u003e view in charge of creating or updating the data in an Ajax modal.\n\nYou can switch the CRUD behavior to Ajax modal by simply setting the 'modal' parameter of the integrated ActionColumn method : \n\n```php\n// myViewFolder/index.php \n\n\u003c?= \\yii\\grid\\GridView::widget([\n    'dataProvider' =\u003e $dataProvider,\n    'filterModel' =\u003e $searchModel,\n    'columns' =\u003e [\n        ['class' =\u003e 'yii\\grid\\SerialColumn'],\n        'id',\n        // ... your gridview fields\n        [\n            'class' =\u003e 'letsjump\\easyAjax\\helpers\\ActionColumn',\n            'modal' =\u003e true\n        ],\n    ],\n]); ?\u003e\n```\n\n\u003e BONUS: Deleting a record doesn't imply a complete page refresh, therefore the GridView pagination will not be affected.\n\u003e \n\u003e Refer to the [guide](docs/guide/gii.md) for all the available options.\n\n---\n\n#### Ajax Tabs\n\nEasyAjax Tab (`EasyAjax::tab('tab-id', 'content to inject')`) is a simple and _very basic_ way to update the content of a [Bootstrap Tab](https://getbootstrap.com/docs/3.4/javascript/#tabs) with an ajax response from a controller.\n\n**View**\n\nIn the \\yii\\bootstrap\\Tabs widget for each _tab item_, you must:\n- Include a `linkOptions` parameter with a reference to the controller action Url and a `data-yea=1` parameter which will fire the request. \n- Set the tab container ID (`'options'     =\u003e ['id' =\u003e 'yourTabID']`) for a stable reference to its content.\n\n```php\n\u003c?= \\yii\\bootstrap\\Tabs::widget([\n    'items' =\u003e [\n        [\n            'label'       =\u003e 'Rome',\n            'linkOptions' =\u003e [\n                'data-href' =\u003e \\yii\\helpers\\Url::to(['site/tab', 'id' =\u003e 'rome',]),\n                'data-yea'  =\u003e 1\n            ],\n            'options'     =\u003e ['id' =\u003e 'rome'],\n        ],\n        // ... other tabs\n    ]\n]) ?\u003e\n```\n\n**Controller**\n\nJust include the EasyAjax method `EasyAjax::tab(tab-id, content)` into the controller action response array:\n\n```php\npublic function actionTab($id)\n{\n    $date = new \\DateTimeImmutable('now');\n    \n    $content = [\n        'rome' =\u003e $date-\u003esetTimezone(new \\DateTimeZone('Europe/Rome'))-\u003eformat('l jS \\of F h:i:s A'),\n        'london' =\u003e $date-\u003esetTimezone(new \\DateTimeZone('Europe/London'))-\u003eformat('l jS \\of F h:i:s A'),\n        'new-york' =\u003e $date-\u003esetTimezone(new \\DateTimeZone('America/New_York'))-\u003eformat('l jS \\of F h:i:s A'),\n        'calcutta' =\u003e $date-\u003esetTimezone(new \\DateTimeZone('Asia/Calcutta'))-\u003eformat('l jS \\of F h:i:s A'),\n    ];\n    \n    if ( ! array_key_exists($id, $content)) {\n        throw new \\yii\\web\\BadRequestHttpException('Your request is invalid');\n    }\n    \n    Yii::$app-\u003eresponse-\u003eformat = \\yii\\web\\Response::FORMAT_JSON;\n    \n    return [\n        \\letsjump\\easyAjax\\EasyAjax::tab($id, '\u003cp\u003e' . $content[$id] . '\u003c/p\u003e')\n    ];\n}\n```\n\n\u003e Warning: tab-id must be specified without the hashtag (#).\n\u003e\n\u003e Refer to the [guide](docs/guide/tabs.md) for all the available options.\n\n---\n#### Content replace\n \nEasyAjax `ContentReplace(['#container1-id'=\u003e'New content', '#container2-id'=\u003e'New content', ...])` replaces the content of a specific Html tag with the code sent by the EasyAjax response. It uses the [`jQuery.html()` standard method](https://api.jquery.com/html/). \n \n```php\npublic function actionContentReplace()\n{\n    Yii::$app-\u003eresponse-\u003eformat = \\yii\\web\\Response::FORMAT_JSON;\n    \n    return [\n        \\letsjump\\easyAjax\\EasyAjax::contentReplace(['#time-placeholder' =\u003e date('d/m/Y H:i:s')])\n    ];\n}\n```\n\n\u003e Refer to the [guide](docs/guide/content-replace.md) for detailed informations.\n\n---\n#### Confirms\n\nYou can use the EasyAjax `confirm('message', 'url')` method to fire a [Javascript Window confirm()](https://www.w3schools.com/jsref/met_win_confirm.asp) from a controller action. By clicking on the \"OK\" button it will fire an Ajax request to the action specified in the `url` parameter.\n```php\npublic function actionConfirm()\n{\n    Yii::$app-\u003eresponse-\u003eformat = \\yii\\web\\Response::FORMAT_JSON;\n    \n    return [\n        \\letsjump\\easyAjax\\EasyAjax::confirm('This will fire a growl. Ok?', \\yii\\helpers\\Url::to(['site/notify']))\n    ];\n}\n```\n\n\u003e Refer to the [guide](docs/guide/confirm.md) for detailed informations.\n\n## Security\nSee [SECURITY.md](SECURITY.md)\n\n## Contributing\nSee [CONTRIBUTING.md](CONTRIBUTING.md)\n\n## Credits\n\n[Yiisoft](https://www.yiiframework.com/) for the best PHP framework for large-scale application (my own opinion), [Twitter Bootstrap](https://getbootstrap.com/), and the [Bootstrap Notify plugin](http://bootstrap-notify.remabledesigns.com/). The Code of Conduct is adapted from the [Contributor Covenant](http://contributor-covenant.org)\n\n## License\n\nSee [LICENSE.md](LICENSE.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fletsjump%2Fyii2-easy-ajax","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fletsjump%2Fyii2-easy-ajax","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fletsjump%2Fyii2-easy-ajax/lists"}