{"id":22561763,"url":"https://github.com/everlutionsk/ajaxcom-bundle","last_synced_at":"2025-04-10T10:20:18.762Z","repository":{"id":47656137,"uuid":"102403752","full_name":"everlutionsk/ajaxcom-bundle","owner":"everlutionsk","description":"Symfony 3 bundle for AjaxCom automation","archived":false,"fork":false,"pushed_at":"2024-11-07T16:03:26.000Z","size":87,"stargazers_count":6,"open_issues_count":0,"forks_count":6,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-03-24T09:11:17.757Z","etag":null,"topics":["ajax","ajaxcom","bundle","symfony"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/everlutionsk.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-09-04T21:23:28.000Z","updated_at":"2024-11-07T16:02:35.000Z","dependencies_parsed_at":"2023-01-21T17:35:53.808Z","dependency_job_id":null,"html_url":"https://github.com/everlutionsk/ajaxcom-bundle","commit_stats":null,"previous_names":[],"tags_count":38,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/everlutionsk%2Fajaxcom-bundle","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/everlutionsk%2Fajaxcom-bundle/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/everlutionsk%2Fajaxcom-bundle/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/everlutionsk%2Fajaxcom-bundle/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/everlutionsk","download_url":"https://codeload.github.com/everlutionsk/ajaxcom-bundle/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248103903,"owners_count":21048244,"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","ajaxcom","bundle","symfony"],"created_at":"2024-12-07T22:09:39.977Z","updated_at":"2025-04-10T10:20:18.732Z","avatar_url":"https://github.com/everlutionsk.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Everlution AjaxcomBundle\n\n[![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/everlutionsk/ajaxcom-bundle/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/everlutionsk/ajaxcom-bundle/?branch=master)\n[![Build Status](https://scrutinizer-ci.com/g/everlutionsk/ajaxcom-bundle/badges/build.png?b=master)](https://scrutinizer-ci.com/g/everlutionsk/ajaxcom-bundle/build-status/master)\n\n## Installation\n\n### Step 1: Download the Bundle\n\n```console\n$ composer require everlutionsk/ajaxcom-bundle\n```\n\n### Step 2: Enable the Bundle\n\n```php\n\u003c?php\n// app/AppKernel.php\n\n// ...\nclass AppKernel extends Kernel\n{\n    public function registerBundles()\n    {\n        $bundles = array(\n            // ...\n\n            new Everlution\\AjaxcomBundle\\EverlutionAjaxcomBundle(),\n        );\n\n        // ...\n    }\n\n    // ...\n}\n```\n\n### Step 3: Include Ajaxcom library JavasSript within your TWIG layout\n\nInstall `@everlutionsk/ajaxcom-js` via `npm` and include `ajaxcom.js` to your TWIG layout:\n\n```twig\n\u003cscript type=\"text/javascript\" src=\"{{ asset('build/ajaxcom.js') }}\"\u003e\u003c/script\u003e\n```\n\nThe last thing you need to do is provide some JavaScript handler within your TWIG layout - please follow `@everlutionsk/ajaxcom-js` [documentation](https://github.com/everlutionsk/ajaxcom-js).\n\n## Configuration\n\nYou don't need to configure anything if you wish to use the flash message templates provided by the bundle.\n\n```yaml\n# all configuration is optional - following values are default\neverlution_ajaxcom:\n    flash_template: @EverlutionAjaxcom/flash_message.html.twig\n    flash_block_id: flash_message\n    persistent_class: ajaxcom-persistent\n    blocks_to_render: # default value is empty array - when you provide this value, AjaxcomBundle will automatically render these blocks within each AJAX request\n          - id: 'content'\n          - id: 'navigation'\n          - id: 'flash_message'\n            refresh: true\n```\n\nBy default AjaxcomBundle ignores blocks which are empty and if developer asks to render an empty block we filter out these instances. In case you want to re-render the block with empty content you should set `refresh` flag to true like you can see in above example.\n\nWhen you want to set refresh flag from controller you need first add the block and then refresh it:\n\n```php\n\u003c?php\n\npublic function exampleAction()\n{\n    $this-\u003eaddAjaxBlock('example');\n    $this-\u003erefreshAjaxBlock('example');\n    \n    return $this-\u003erender('some/template');\n}\n```\n\nThe bundle works best with Bootstrap 3+ CSS framework.\n\n## Usage\n\nExtend your controller from `Everlution\\AjaxcomBundle\\Controller\\Controller` or use `Everlution\\AjaxcomBundle\\Controller\\AjaxcomTrait` trait with your controller to obtain Ajaxcom functionality.\n\nBy default `ajaxcom-js` library will handle all link clicks except one with `target=\"_blank\"` and all form submissions. If you need to change selector or you want to have some control over which links are handled by `ajaxcom-js` and which aren't you can override the default selectors within `ajaxcom-js` initialization. Please see the `@everlutionsk/ajaxcom-js` [documentation](https://github.com/everlutionsk/ajaxcom-js).\n\nExample:\n\n```twig\n\u003ca href=\"https://www.google.com\"\u003eExternal link\u003c/a\u003e \u003c!-- won't be handled by Ajaxcom --\u003e\n\u003ca href=\"{{ path('remove_user') }}\"\u003eRemove user\u003c/a\u003e \u003c!-- will be handled by Ajaxcom --\u003e\n```\n\nThe following methods can be combined - eg. you can render multiple blocks and remove multiple blocks and add as many JavaScript callbacks within one request as you wish.\n\n### `public function render($view, array $parameters = array(), Response $response = null)`\n\nEverlution's Ajaxcom bundle extends standard Symfony's `render()` method so you can integrate Ajaxcom with your project without any further changes within your codebase.\n\nThe `render()` method automatically decides if it responding to the Ajax or non-Ajax call so you don't need to handle special scenarios within your application.\n\nThe Ajaxcom bundle will handle your Symfony controller's action with Ajax and non-Ajax request automatically so you don't need to write your code twice - the bundle will always call the same action.\n\nWithin your standard Symfony controller's action you will have only tiny overhead which will setup the action's behaviour for handling the Ajax requests. The overhead methods are explained in next few sections.\n\n### `renderAjaxBlock(string $id)`\n\nIn order to dynamically render only one block on page you need to fit following two conditions:\n\n1. the block which you want to render is enclosed within twig `block`\n2. the twig `block` is enclosed within DOM element with `ID` which has same name as the block\n\nBy default the TWIG does not support hyphens in block names so if you need to use hyphens within your ID's we are automatically convert hyphens to underscores for you. Hence you can use hyphens within your ID's with combination of the same name for TWIG block - you just need to replace hyphens with underscores. Example: `id='custom-block'` and `{% block custom_block %}` will be automatically matched by AjaxcomBundle.\n\n#### Example:\n\nTwig:\n\n```twig\n\u003cdiv id=\"list\"\u003e\n    {% block list %}\n        // this is the HTML which will be replaced/removed ...\n    {% endblock %}\n\u003c/div\u003e\n```\n\nPHP:\n\n```php\n$this-\u003erenderAjaxBlock(\"list\");\n```\n\nIn action of your controller simply call `renderAjaxBlock` where you need to provide the block ID (eg. TWIG block name).\n\nWhen your action is called via Ajax request the JSON response for Ajaxcom library will contain information about which block should be re-rendered with which HTML.\n\n### `removeAjaxBlock(string $selector)`\n\nIf you want to remove some DOM element dynamically for instance after deleting some row from table you can use `removeAjaxBlock()` method where you will simply provide CSS selector of the element which you want to remove.\n\n#### Example:\n\nTwig:\n\n```twig\n\u003ctable\u003e\n    \u003ctbody\u003e\n        \u003ctr id=\"row-1\"\u003e\u003ctd\u003e1.\u003c/td\u003e\u003c/tr\u003e\n        \u003ctr id=\"row-2\"\u003e\u003ctd\u003e2.\u003c/td\u003e\u003c/tr\u003e\n        \u003ctr id=\"row-3\"\u003e\u003ctd\u003e3.\u003c/td\u003e\u003c/tr\u003e\n    \u003c/tbody\u003e\n\u003c/table\u003e\n```\n\nPHP:\n\n```php\n$this-\u003eremoveBlock(\"#row-2\");\n\n// OR you can use any CSS selector\n\n$this-\u003eremoveBlock(\"tr:nth-child(2)\");\n```\n\nThe above code (both examples) will remove middle row from the table after the action is called.\n\nResult:\n\n```twig\n\u003ctable\u003e\n    \u003ctbody\u003e\n        \u003ctr id=\"row-1\"\u003e\u003ctd\u003e1.\u003c/td\u003e\u003c/tr\u003e\n        \u003c!-- the #row-2 has been removed --\u003e\n        \u003ctr id=\"row-3\"\u003e\u003ctd\u003e3.\u003c/td\u003e\u003c/tr\u003e\n    \u003c/tbody\u003e\n\u003c/table\u003e\n``` \n\n### `addCallback(string $function, array $parameters = [])`\n\nYou can add as many JavaScript callbacks as you wish. First argument of `addCallback()` is name of function which should be called after rendering the HTML, second is array of parameters which will be passed to the function as an object.\n\nExample:\n\nPHP:\n\n```php\n$this-\u003eaddCallback('Table.init', ['some' =\u003e 'data', 'other' =\u003e ['data', 'etc']]);\n```\n\n```javascript\nvar Table = function() {\n    return {\n        init: function(data){\n            var some = data.some;\n            var otherArray = data.other;\n            \n            // initialize table with provided data\n        };\n    }\n};\n```\n\n#### You don't need necessarily use this function\n\nYou don't actually need to use this function if you would write your JavaScript in a following way:\n\n```javascript\n// additional.js\nvar App = {\n    additional: function () {\n        // some additional functionality\n        console.log('executing App.additional');\n    },\n    // more functions within App namespace\n}\n\nApp.additional();\n```\n\nThe `App.additional()` will be executed every time the browser downloads `additional.js` file - no matter if the request is being handled with or without Ajaxcom. You just need to make sure that you are adding the `\u003cscript src=\"additional.js\"\u003e\u003c/script\u003e` to your DOM via Ajaxcom where it is needed.\n\nThe AjaxcomBundle will add all scripts within `javascripts` block to your page automatically (they will be inserted after the last `\u003cscript\u003e` within your code).\n\n### `replaceClass()`\n\nYou can easily replace class in any DOM object you want by invoking `replaceClass()` with two arguments - first is CSS selector of your choice and second is class which you want to replace current one with.\n\n### `doNotChangeUrl()`\n\nYou can easily avoid replacing url of the target page by invoking `doNotChangeUrl()`.\n\n### Flash messages\n\nThe flash messages are automatically handled by Ajaxcom bundle. When the request is called via Ajax the flashes which are in the session bag are rendered automatically.\n\nYou only need to include provided twig template somewhere within your twig layout:\n\n```twig\n{% include \"@EverlutionAjaxcom/flash_message.html.twig\" %}\n```  \n\nWhen you call `addFlash()` from your controller, please use `Everlution\\AjaxcomBundle\\Flash` to provide the flash message type:\n\n```php\n$this-\u003eaddFlash(Everlution\\AjaxcomBundle\\Flash::SUCCESS, 'Your request has been successfully handled by Ajaxcom bundle');\n\n// you can use following constants:\n// Everlution\\AjaxcomBundle\\Flash::SUCCESS\n// Everlution\\AjaxcomBundle\\Flash::ERROR\n// Everlution\\AjaxcomBundle\\Flash::WARNING\n// Everlution\\AjaxcomBundle\\Flash::INFO\n```\n\n### Sending forms through Ajaxcom\n\nAll forms are by default handled by `ajaxcom-js`. You can change this behaviour by overriding the default forms selector while initializing `ajaxcom-js`. Please follow `@everlutionsk/ajaxcom-js` [documentation](https://github.com/everlutionsk/ajaxcom-js).\n\n# Reusing data sources\n\nIn order to reuse data source between for instance multiple tabs you can easily create Twig functions by extending our `BaseDataSource`.\n\nSimply add to your services.yml following statement:\n\n```yaml\n    AppBundle\\DataProvider\\:\n        resource: '../../src/AppBundle/DataProvider'\n        tags: ['twig.extension']\n```\n\nYou can specify any folder within your project you want. In this example we have chosen `AppBundle\\DataProvider` namespace.\n\nEach class within this namespace which extends `Everlution\\AjaxcomBundle\\DataSource\\BaseDataSource` is scanned for public methods with suffix `Provider` via reflexion and we are creating the simple Twig functions from these methods. Let's see the example:\n\n\n```php\n// AppBundle\\DataProvider\\Example.php\n\n// simple function which returns static array\npublic function navigationProvider() {\n    return [ \n        // some data... \n    ];\n}\n\n// you can use parametrical functions and injected services as well\npublic function userProfileProvider(int $id) {\n    return $this-\u003esomeService-\u003egetData($id);\n}\n```\n\nAfter creating such class you can simply call the function within twig:\n\n```twig\n{{ dump(navigation()); }} {# will dump static array #}\n\n{% for item in userProfile(2) %}\n   {{ dump(item) }}\n{% endfor %}\n```\n\n# Best practice\n\nIf you want to use AjaxcomBundle seamlessly you should copy `@EverlutionAjaxcom\\layout_bootstrap_4.html.twig` to your project (eg. AppBundle) and modify it to your needs.\n\nThis way the AjaxcomBundle will handle tasks such as replacing JavaScripts, StyleSheets and MetaTags for you.\n\n## Use automated replacement of JS, CSS, Meta and Title\n\nWhen you are using blocks from `@EverlutionAjaxcom\\layout_bootstrap_4.html.twig` you should be all set up.\n \nWhen you decide to set up your layout manually following sections will help you to understand how the automatic replacement works.\n\n### replacing JavaScripts\n\n1. all JavaScript which should be included on every page needs to contain `class='ajaxcom-persistent'` (or anything you have set within configuration of bundle)\n2. your main layout which you are extending must contain `{% block javascripts %}{% endblock %}`\n3. when you are extending your main layout and you are rewriting `javascripts` block AjaxcomBundle will load scripts from this block automatically for you\n\n### replacing StyleSheets\n\n1. same as JavaScript, all StyleSheets which should be included on every page needs to containe `class='ajaxcom-persistent'` (or anything you have set within configuration of bundle)\n2. your main layout which you are extending must contain `{% block stylesheets %}{% endblock %}`\n3. when you are extending your main layout and you are rewriting `stylesheets` block AjaxcomBundle will load styles from this block automatically for you\n\n### replacing meta tags and title\n\n1. all meta tags which should be present on every page needs to contain `class='ajaxcom-persistent'` (or anything you have set within configuration of bundle)\n2. your main layout which you are extending must contain `{% block metatags %}{% endblock %}`\n3. when you are extending your main layout and you are rewriting `metatags` block AjaxcomBundle will load meta tags from this block automatically for you\n4. if you want to change `title` of page your layout needs to contain `\u003ctitle\u003e{% block title %}{% endblock %}\u003c/title\u003e` and you need to rewrite `title` block within template where you extending your main template\n\n# TODO\n\n- add complex usage example\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feverlutionsk%2Fajaxcom-bundle","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Feverlutionsk%2Fajaxcom-bundle","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feverlutionsk%2Fajaxcom-bundle/lists"}