stimulus-conductor

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 already installed.

In your project just add the stimulus-conductor package.

$ yarn add stimulus-conductor

or

$ 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

<div data-controller="items">
  <div data-controller="item"></div>
  <div data-controller="item"></div>
  <div data-controller="item"></div>
</div>

Define your parent controllers by extending stimulus-conductor

// ./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

// ./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.

// 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
• Live demo

Limitations

Plurals

Currently the library makes a very simple plural of the controller name by adding a sat 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.