review/consider BL asset architecture

[MrDys]

CODEBASE-310: Rails3 BL assets (js, CSS, possibly images) are copied into the local application on BL generator execution. They are just put at the top level of local assets/.

Compare to Rails2 'engines' setup, which, in fact, ALSO copied the assets into local application, but did it on each app startup, and put them in a special directory.

Don't want to go back to apeing Rails2 'engines' exactly, but some concerns:

1) If the user upgrades Blacklight, they may very well want to upgrade the assets, for instance CSS if we change the CSS for default BL views. They can do this by running the generator again. But: If they edited the BL assets, they'll have to manually merge. I am concerned that it's not clear enough which assets are the BL assets, so they may edit them unawares not realizing that they may later want to upgrade them.

2) It's rather inconvenient for developers when developing BL, if you're making changes to the assets (say CSS or JS), I think you're going to have to keep running the generator after every tweak to see the changes you made in a live application!

Suggestion/proposal:

• Generate assets into a blacklight/ subdirectory to keep it clear which ones were generated by BL. (Will this work? We'll have to change all the asset references to have URLs beginning blacklight/. Will it mess up anything else?)
• Prepend each generated asset (JS or CSS) with a comment block explaining that it's a file generated by BL, and rather than edit it in place, user may wish to add on their own JS or CSS with over-rides instead, pointing to documentation on the wiki for doing that.
• Provide a generator that copies over JUST the assets (split it out). There's probably a way, then, if you want, to have this generator triggered on every startup but only when you're in 'development' environment. Provide a recipe for doing this for developers who want to do so.

[MrDys]

Original reporter: jrochkind

[MrDys]

jrochkind: yes, put those stock things back in /public

[MrDys]

jrochkind: Okay, plan above is committed. Details copied from commit message below. However I'm leaving this ticket open cause I'd like to discuss one more idea I had:

post-commit, BL is generating ALL of it's assets in ./blacklight/ subdirs. This seems appropriate for actual BL-custom logic/css. However, BL also generates jquery, jquery-ui, and yui.css into the app. Those files probably should NOT be in ./blacklight subdirs. Because you might want to share them with the rest of your app, default BL js/css needs em, but they aren't really JS specific. Generate those into public/ root maybe? That will only work without being confusing if the content of those files never changes unless the name changes too. Is that true?

https://github.com/projectblacklight/blacklight/commit/e948163ea7d08296d583b487b9c215ceb1621e8a

L assets generated into public/blacklight see CODEBASE-310

There is now a seperate generator for asset copying, "blacklight:assets".

This generator can be run programmatically in your environments/development.rb if you want, like this:

require File.join(Blacklight.root, "lib", "generators", "blacklight", "assets_generator.rb") Blacklight::AssetsGenerator.start(["--force", "--quiet"])

In order to make that work, the assets_generator.rb had to explicitly 'require' rails/generators/base, since those are implicitly required when running 'rails g', but not in the actual app. No big deal.

The asset files are no longer put directly into public/, but into blacklight-specific subdirs in each place. public/stylesheets/blacklight etc.

In order to make BL core reference this new location, pretty simple, just an edit in Blacklight::Controller to the lines that include the assets. Also some relative image paths in blacklight.css needed to be changed to still be correct.

Comments added to blacklight.css and blacklight.js discouraging users from editing these files, telling them they are BL generated.