Fix documentation for composer library setup

We can use composer now!
https://github.com/harvesthq/chosen/pull/2988
https://packagist.org/packages/harvesthq/chosen

Right!

Going to be bold and change the title around because I spent a lot of time tracking this down and only found this by looking through all the composer related issues to find what sort of things where going on.

Because https://github.com/harvesthq/chosen/pull/2988 made it into a release, the overrides in the current README no-longer work and the undocumented methods being discussed in this issue are required to get the library installed.

Updated summary to represent current state of issue, let me know if I got anything wrong. I'll also try to take a pass at updating the documentation this week.

I was struggling with this for a little bit and trying to piece these various patches and steps and pieces of documentation together, so here is how I got the chosen.js library installed in my web/libraries directory from a composer require.

First, install the chosen module as normal:
composer require drupal/chosen

Then run:
composer require oomphinc/composer-installers-extender

Now edit your composer.json file to include:

    "extra": {
        "installer-types": ["library"],
        "installer-paths": {
            "web/libraries/{$name}": ["harvesthq/chosen", "type:drupal-library"],
        },

Then you can run:
composer require harvesthq/chosen

And it will put chosen in the right spot for you.

If using a vendor dir for other composer required and dependent packages, won't adding type:library, as suggested in #12 above, move a bunch of other packages to the docroot/libraries (or web/libraries) directory?

@hawkeye.twolf Yep, that's the reason I identified it by name. I don't want other libraries in my web/libraries directory.

I can confirm that the procedure described in #12 worked for me.

Perhaps it's because this is an older ticket and my composer.json file already had some of the entries, but I just need to make two small adjustments:

- Added "library" to the existing extra/installer-types array
- Added "harvesthq/chosen" to the existing extra/installer-paths/docroot/libraries/{$name} array

New version of patch, sorry there's no interdiff, I couldn't actually apply the other patch to my code, and gave up on that :) They're pretty different at this point anyway.

WORK IN PROGRESS! Specifically, downloading the JS library to web/libraries instead of vendor: I tried several combinations of extra/installer-* values, couldn't get it to work, hoping someone here has a solution. I'll include a list of my best recollection of what I tried so far (not that you shouldn't also try these ideas, but, just to share) -- list is at the bottom of this comment.

Also: Asset Packagist -- implicitly suggested in patch in #3, might work perfectly for this issue, I just couldn't figure out how to use it for this situation (my impression is that it's no longer needed b/c the Chosen library is on packagist, but idk if that's accurate).

Related d.o documentation: Downloading third-party libraries using Composer
(...And Chosen is right there ^^ in the Asset Packagist examples!! ...but obviously, that's for if you're getting Chosen from npm, which we no longer have to do, "yay" haha.)

One more related doc: Including 3rd party libraries (Getting Involved guide)

(1)

        "installer-paths": {
            "web/core": ["type:drupal-core"],
            "web/libraries/chosen": ["harvesthq/chosen"],
            "web/libraries/{$name}": ["type:drupal-library"],

Attempt #1: really seemed like it should work, based on this composer/installers documentation! (Note: I couldn't let it be web/libraries/{$name} because then there would be two identical installer-paths.)

(2)
Same as attempt #1 but I manually created a "chosen" directory in web/libraries before running composer require harvesthq/chosen

(3)

        "installer-paths": {
            "web/core": ["type:drupal-core"],
            "web/libraries/{$name}": ["type:drupal-library", "harvesthq/chosen"],

(4)

        "installer-types": ["library"],
        "installer-paths": {
            "web/core": ["type:drupal-core"],
            "web/libraries/{$name}": ["type:drupal-library", "harvesthq/chosen"],

Attempt #4: Obviously concerned about having "library" in here as an installer type, but I wanted to try it anyway.

Just for kicks, I installed oomphinc/composer-installers-extender and tried again with "installer-types": ["library"] and put "type:library" into the same installer path as drupal-library -- as predicted, 111 packages were re-installed into the web/libraries directory 😆

(also as warned here: https://github.com/composer/installers#should-we-allow-dynamic-package-t... )

...in my defense, I promise I waited a **while** before posting my comment, imagining myself SO POSITIVE that I had thought of everything I needed to say... and yet, here I am again...

Looks like you can't specify a custom installer path unless composer/installers is required by the package you're adding to your project -- if I'm understanding this documentation correctly:
https://getcomposer.org/doc/faqs/how-do-i-install-a-package-to-a-custom-...

Idk where that leaves us. I mean, is it even an option to change how the Chosen module looks for the library, so it looks in vendor? Never mind, duh, of course not -- that wouldn't work for sites not using composer.

The instructions in #11 worked a treat with the oomphinc/composer-installers-extender installed for me.
Any reason not to do it that way?

#22 By adding harvesthq/chosen as a required package in chosen's composer.json (as added in patch #18), you won't have to manually add the library to your composer file.

I am not sure where we are since the last comment was 3 months back, but I will try to address concerns in some of the previous comments.

#12: We can't use type: library as that is the default for composer.json if not specified. Further, this is actually used by PHP libraries. See https://github.com/symfony/http-kernel/blob/master/composer.json for example. This means we should really use the name. If we can submit a PR to the chosen library to change it to something like 'npm-asset', then we don't have to worry about this (once it gets merged and tagged).

#19, #20: I think what the documentation says is that the installer-paths of only the root composer.json is used, not in the library's composer.json file. To workaround this, documentation in chosen module should just direct people to add the entry to installer-paths in their composer.json file.

I'll review the patch in #18 and see if I can help.

First, a reroll.

Updating the library to the latest (1.8.7) as the current README refers to that version. I also updated the README file to be hopefully clearer and also addressing my comment in #24.

I realised that this documentation was not enough and we actually need the composer-installers-extended package for this to work. I am updating the README with those instructions.

I also submitted an issue on Github to change the package type: https://github.com/harvesthq/chosen/pull/3066. I'll appreciate if you can comment there to explain the reasoning.

Followed instructions in #27. Chosen library is successful placed in the /libraries folder and js is detected by Drupal.

Thanks!

Committed.

Thank you thank you everybody for making this happen!! I just did my first Chosen update since well, since all this, and I had to modify my composer things, the instructions worked beautifully. And, three cheers for @hussainweb for getting the package type changed (and overall composer support improvements) in the library itself!

------
Only thing, I think, is that a change notice or at least a note on the release page would be cool to add, so folks who did it the "old way" know what to do in their projects. @nagy.balint would that be ok, or do you think it's not appropriate for the situation?

Here are a couple ideas for language to add to the release page, if you think it's a good idea:

Option 1: "MVP", if you will...

Instructions for composer users:

• See project README for full instructions.
• Note: If you included the Chosen library in your project via composer prior to this release, you'll need to redo your Composer/Chosen setup before you update the Drupal module to 8.x-2.9! Review the commit diff for the updated instructions to see the changes you'll need to make (old way vs. new way).

Option 2: Full details -- I tested these instructions a couple times, but ideally someone else would test, too -- so, only reason I wouldn't push for these more complete instructions is if it'll take time to iron out specific language, and I think it's better to get *something* on there than delay adding a note -- *imo*:

Instructions for composer users:

• See project README for full instructions.
• Note: If you included the Chosen library in your project via composer prior to this release, you'll need to redo your Composer/Chosen setup -- before you update the Drupal module to 8.x-2.9!
  • Remove the chosen *library* from your project:
  • composer remove harvesthq/chosen
  • Remove the harvesthq/chosen *repository/package* from the top of your composer.json file (edit composer.json, find "repositories" and remove the harvesthq/chosen "package" record from the repositories list).
  • Now, you're in a clean enough place to re-add the library to your project using the updated instructions in the README. (You may need to use the --update-with-dependencies flag when you run composer require drupal/chosen.)
  • See also: instructions change details in the commit diff.

Thanks!

I added a similar text to the release.

We can fortunately edit the release as many times as we want, so we can do further changes if required.

https://www.drupal.org/project/chosen/releases/8.x-2.9

Woo hoo, thanks @nagy.balint!

This is the only module so far that I've struggled so much with to get the library working. I don't fully understand why this has to be so complicated. One some of my servers chosen installs correctly, on others it does not and I've read the README I've watched the video and I've tried MANY of the suggestions on this thread. It's frustrating, especially when the whole point of composer is to make things simpler.

Until this is resolved I'm simiply going with the solution in #9, in https://www.drupal.org/project/chosen/issues/3102250 adding it as a package. It gets installed in the right place and I'm not going through extra hoops trying to install helper packages and work through frustrating errors.

I really hope this gets resolved soon.