https://github.com/adrienpoly/stimulus-conductor
👩👧👦 👨👧👦 : A simple Stimulus Controller to manage Parent/Children controllers with simple conventions
https://github.com/adrienpoly/stimulus-conductor
stimulus stimulus-controller stimulusjs
Last synced: about 1 month ago
JSON representation
👩👧👦 👨👧👦 : A simple Stimulus Controller to manage Parent/Children controllers with simple conventions
- Host: GitHub
- URL: https://github.com/adrienpoly/stimulus-conductor
- Owner: adrienpoly
- License: mit
- Created: 2019-03-11T17:27:12.000Z (about 6 years ago)
- Default Branch: master
- Last Pushed: 2024-03-25T14:50:29.000Z (about 1 year ago)
- Last Synced: 2025-04-06T18:38:01.864Z (about 2 months ago)
- Topics: stimulus, stimulus-controller, stimulusjs
- Language: JavaScript
- Homepage: https://www.npmjs.com/package/stimulus-conductor
- Size: 2.95 MB
- Stars: 89
- Watchers: 7
- Forks: 2
- Open Issues: 21
-
Metadata Files:
- Readme: readme.md
- License: LICENSE
Awesome Lists containing this project
README
Stimulus-Conductor
👩👧👦 👨👧👦 : A simple Stimulus Controller to manage Parent/Children controllers with simple conventions
- **Conventions**: Parent/children Stimulus controllers defined by simple conventions
- **Has many** : an `items` controller has many `item` controllers
- **Belongs to** : `item` controllers belong to an `items` controller
## Getting started
This assumes that you have [Stimulus](https://stimulusjs.org/handbook/installing) already installed.
In your project just add the `stimulus-conductor` package.
```bash
yarn add stimulus-conductor
```
or
```bash
npm i stimulus-conductor
```
### Conventions
There is a single convention to remember to use this package:
> **Parent conductor is the plural of the children items name**
>
> - `todo` controllers are conducted by a `todos` controller
> - `item` controllers are conducted by an `items` controller
> - `chart` controllers are conducted by a `charts` controller
### Define your html
```html
```
### Define your parent controllers by extending `stimulus-conductor`
```js
// ./controllers/items_controller.js
import Conductor from 'stimulus-conductor'
// create a parent controller by extending stimulus-conductor controller
export default class extends Conductor {
connect() {
// if you overwrite connect you must call super!!!!
super.connect()
}
disconnect() {
// if you overwrite disconnect you must call super!!!!
super.disconnect()
}
update() {
// this.itemControllers is an array of item stimulus controllers
// this.itemControllers.length -> 3
}
}
```
> By **convention** the parent controller has a new class method `this.itemControllers` that return an array of all children controllers
### Define your children controllers by extending `stimulus-conductor`
```js
// ./controllers/item_controller.js
import Conductor from 'stimulus-conductor'
// create a kid controller by extending stimulus-conductor controller
export default class extends Conductor {
connect() {
// if you overwrite connect you must call super!!!!
super.connect()
// you can access to the parent controller like this
// this.itemsController is the stimulus controller for the parent controller
}
}
```
> By **convention** all children controllers have a new class method `this.itemsController` that return the parent controller
### Inflections & custom naming
Sometime plurals are not just as simple as adding a `s` at the end. You can overide the musician and conductor name by setting the static `musicianId` and `conductorId` values.
```js
// your conductor todo_controller.js
export default class extends Controller {
static musicianId = 'todo-item'
// ...
}
// your musicians todo-item_controller.js
export default class extends Controller {
static conductorId = 'todo'
// ...
}
```
## Example
An very basic todo list example is available on Glitch :
- [Todo list code ](https://glitch.com/edit/#!/stimulus-conductor)
- [Live demo ](https://stimulus-conductor.glitch.me/)
## Limitations
#### Plurals
Currently the library makes a very simple plural of the controller name by adding a `s`at the end of the word:
- `todo` is conducted by `todos`
- `item` is conducted by `items`
more complex plurals (child/children) are not yet supported
#### Nesting
Currently it only works with nested parent/children elements
## Contributing
Bug reports and pull requests are welcome.
**To contribute:**
Fork the project.
Install dependencies
`$ yarn install`
Start the test watcher
`$ yarn test:watch`
Running one-off test runs can be done with:
`$ yarn test`
You can test locally also the results with the playground project (`yarn start`)
**Then :**
👍 Write some tests
💪 Add your feature
🚀 Send a PR
## License
This package is available as open source under the terms of the MIT License.