{"id":18782393,"url":"https://github.com/atk4/mastercrud","last_synced_at":"2025-04-13T12:08:33.664Z","repository":{"id":54493362,"uuid":"120906930","full_name":"atk4/mastercrud","owner":"atk4","description":"Manipulates ATK CRUD through the force of references","archived":false,"fork":false,"pushed_at":"2023-12-19T14:26:23.000Z","size":1224,"stargazers_count":9,"open_issues_count":4,"forks_count":7,"subscribers_count":8,"default_branch":"develop","last_synced_at":"2025-04-13T12:08:26.779Z","etag":null,"topics":["agile","atk4","mastercrud","php"],"latest_commit_sha":null,"homepage":"https://atk4.org","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/atk4.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-02-09T13:08:33.000Z","updated_at":"2023-10-16T09:30:54.000Z","dependencies_parsed_at":"2022-08-13T17:40:41.415Z","dependency_job_id":null,"html_url":"https://github.com/atk4/mastercrud","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/atk4%2Fmastercrud","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/atk4%2Fmastercrud/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/atk4%2Fmastercrud/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/atk4%2Fmastercrud/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/atk4","download_url":"https://codeload.github.com/atk4/mastercrud/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248710431,"owners_count":21149190,"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":["agile","atk4","mastercrud","php"],"created_at":"2024-11-07T20:35:51.505Z","updated_at":"2025-04-13T12:08:33.637Z","avatar_url":"https://github.com/atk4.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"[ATK UI](https://github.com/atk4/ui) is a UI library for building UI interfaces that has a built-in [CRUD](http://ui.agiletoolkit.org/demos/crud.php) component. It can be used to create complex admin systems, but it requires you to populate multiple pages and inter-link them together yourself.\n\n![mastercrud](docs/images/mastercrud.png)\n\n**MasterCrud** is an add-on for ATK UI and ATK Data, which will orchestrate navigation between multiple CRUD pages by respecting relations and conditions. You can use **MasterCrud** to:\n\n-   Manage list of clients, and their individual invoices and payments.\n-   Manage user groups and users within them\n-   Manage multi-level catalogue and products in them\n\nThe syntax of **MasterCrud** is incredibly simple and short. It automatically takes care of many details like:\n\n-   record and track `id` of various records you have clicked on (BreadCrumb)\n-   display multi-Tab pages with model details and optional relations\n-   support `hasOne` and `hasMany` relations\n-   allow flexible linking to a higher tree level (user - invoice - allocated_payment -\u003e payment (drops invoice_id))\n\n**MasterCrud** can also be extended to contain your own views, you can interact with the menu and even place **MasterCrud** inside a more complex layouts.\n\n### Example Use Case (see demos/clients.php for full demo):\n\nAssuming you have Clients with Invoices and Payments and you also want to add \"Line\"s for each Invoice, you may want to add this interface for the admin, where user can use drill-downs to navigate through data:\n\n![step1](docs/images/step1.png)\n\nClicking on `Client 2` would bring you to a different page. Extra tabs Invoices and Payments offer you further way in:\n\n![step2](docs/images/step2.png)\n\nclicking on specific invoice, you can edit it's lines:\n\n![step3](docs/images/step3.png)\n\nOn this screen however we turned off deletion of lines (because it is a demo). However clicking Edit brings up a Modal where you can easily update record data:\n\n![step4](docs/images/step4.png)\n\nAll this UI can be created in just a few lines of code!\n\nMasterCrud operates like a regular CRUD, and you can easily substitute it in:\n\n```php\n$crud = \\Atk4\\MasterCrud\\MasterCrud::addTo($app);\n$crud-\u003esetModel('Client');\n```\n\nYou'll noticed that you can now click on the client name to get full details about this client. Next, we want to be able to see and manage Client invoices:\n\n```php\n$crud = \\Atk4\\MasterCrud\\MasterCrud::addTo($app);\n$crud-\u003esetModel('Client', ['Invoices' =\u003e []]);\n```\n\nThis will add 2nd tab to the \"Client Details\" screen listing invoices of said client. If you invoice is further broken down into \"Lines\", you can go one level deeper:\n\n```php\n$crud = \\Atk4\\MasterCrud\\MasterCrud::addTo($app);\n$crud-\u003esetModel('Client', ['Invoices' =\u003e ['Lines' =\u003e []]]);\n```\n\nIf `Client hasMany('Payments')` then you can also add that relation:\n\n```php\n$crud = \\Atk4\\MasterCrud\\MasterCrud::addTo($app);\n$crud-\u003esetModel('Client', ['Invoices' =\u003e ['Lines' =\u003e []], 'Payments' =\u003e []]);\n```\n\nWith some cleanup, this syntax is readable and nice:\n\n```php\n$crud = \\Atk4\\MasterCrud\\MasterCrud::addTo($app);\n$crud-\u003esetModel('Client', [\n    'Invoices' =\u003e [\n        'Lines' =\u003e [],\n    ],\n    'Payments' =\u003e [],\n]);\n```\n\n## Support for actions\n\nMasterCrud is awesome for quickly creating admin systems. But basic C,R,U,D operations are not enough. Sometimes you want to invoke custom actions for individual element. MasterCrud now supports that too:\n\n```php\n$app-\u003elayout-\u003eadd(new \\Atk4\\MasterCrud\\MasterCrud())\n    -\u003esetModel(new \\Saasty\\Model\\App($app-\u003edb),\n    [\n        'columnActions' =\u003e [\n            'repair' =\u003e ['icon' =\u003e 'wrench'],\n        ],\n        'Models' =\u003e [\n            'columnActions' =\u003e [\n                'migrate' =\u003e ['icon' =\u003e 'database'],\n            ],\n            'Fields' =\u003e [\n                'ValidationRules' =\u003e [],\n\n            ],\n            'Relations' =\u003e [\n                'ImportedFields' =\u003e [],\n            ],\n        ],\n```\n\n ![actions](docs/images/actions.png)\n\nThere are various invocation methods allowing you to specify icon, label, custom callbacks etc.\n\nThis also adds \"MethodInvocator\" - a view which asks you for arguments and then executes them.\n\nThis next example will use form to ask for an email, which will then be passed as argument to sendEmail($email)\n\n```php\n[\n    'columnActions' =\u003e [\n         'sendEmail' =\u003e ['icon' =\u003e 'wrench', 'email' =\u003e 'string'],\n   ]\n]\n```\n\n### Installation\n\nInstall through composer:\n\n``` bash\n composer require atk4/mastercrud\n```\n\nAlso see introduction for [ATK UI](https://github.com/atk4/ui) on how to render HTML.\n\n## Roadmap\n\n- [x] Allow to specify custom CRUD seed. You can ever replace it with your own compatible view.\n- [x] Add custom actions and function invocation\n- [ ] Create decent \"View\" mode (relies on ATK UI Card)\n- [ ] Traverse hasOne references (see below)\n\n-------------------------\n\n\u003e NOT IMPLEMENTED BELOW\n\nSuppose that `Invoice hasMany(Allocation)`and `Payment hasMany(Allocation)` while allocation can have one Payment and one Invoice.\n\n```php\n$crud = \\Atk4\\MasterCrud\\MasterCrud::addTo($app);\n$crud-\u003esetModel('Client', [\n    'Invoices' =\u003e [\n        'Lines' =\u003e [],\n        'Allocations' =\u003e [],\n    ],\n    'Payments' =\u003e [\n        'Allocations' =\u003e [],\n    ],\n]);\n```\n\nThat's cool, but if you go through the route of `Invoice -\u003e allocation -\u003e` you should be able to click on the \"payment\":\n\n```php\n$crud = \\Atk4\\MasterCrud\\MasterCrud::addTo($app);\n$crud-\u003esetModel('Client', [\n    'Invoices' =\u003e [\n        'Lines' =\u003e [],\n        'Allocations' =\u003e [\n            'payment_id' =\u003e ['path' =\u003e 'Payments', 'payment_id' =\u003e 'payment_id'],\n        ],\n    ],\n    'Payments' =\u003e [\n        'Allocations' =\u003e [\n            'invoice_id' =\u003e ['path' =\u003e 'Invoices', 'invoice_id' =\u003e 'invoice_id'],\n        ],\n    ],\n]);\n```\n\nNow you will be able to jump from `Invoice-\u003eallocation` to `Payment` and other way around.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fatk4%2Fmastercrud","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fatk4%2Fmastercrud","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fatk4%2Fmastercrud/lists"}