Document custom assets #2475
Document custom assets #2475
Conversation
![hound[bot]](https://avatars.githubusercontent.com/in/3598?s=60&v=4){kind=small}
pablobm
force-pushed
the
document-custom-assets
branch
7 times, most recently
from
8440e60
to
829da14
Compare
pablobm
added
the
documentation
pablobm
force-pushed
the
document-custom-assets
branch
from
a391be8
to
8da33e4
Compare
pablobm
force-pushed
the
document-custom-assets
branch
from
8da33e4
to
b28c28f
Compare
| @@ -0,0 +1 @@ | |||
| //= require_tree ./admin | |||
There was a problem hiding this comment.
Hound's got a point. Should this be
/*
*= require_tree ./admin
*/There was a problem hiding this comment.
Good point. To be honest, as long as it works and Hound shuts up, I'm in 👍
| ## Adding custom CSS and JS | ||
|
|
||
| You can add custom CSS and JS to Administrate. Put the files in the | ||
| appropriate folders (typically under `assets`) and point Administrate to them | ||
| using the following API, preferably in an initializer. For example, if your | ||
| files are called `admin.css` and `admin.js`: | ||
|
|
||
| ``` | ||
| /// config/initializers/administrate.rb | ||
| Administrate::Engine.add_stylesheet("admin") | ||
| Administrate::Engine.add_javascript("admin") | ||
| ``` | ||
|
|
||
| Then make sure to list them in your manifest file (Rails will helpfully remind | ||
| you of this step if you miss it): | ||
|
|
||
| ``` | ||
| /// app/assets/config/manifest.js | ||
| //= link admin.css | ||
| //= link admin.js | ||
| ``` |
There was a problem hiding this comment.
Looks good, thank you!
@pablobm @nickcharlton I wonder what we should to do with the following generators:
lib/generators/administrate/assets/assets_generator.rblib/generators/administrate/assets/javascripts_generator.rblib/generators/administrate/assets/stylesheets_generator.rb
They are another way of customizing assets. As far as I understand, by running those generators, Administrate's non-compiled assets are copied to the users' app. So users can edit a non-compiled asset and compile it themselves if their app is set up for that. And then their assets will take precedence over the ones from the Administrate gem.
I lean toward removing those generators and making users customize assets by appending to Administrate's CSS/JS, just like the example in this PR, instead of completely replacing them with their own.
There was a problem hiding this comment.
I agree. I think that this way of customising assets is more likely to cause issues than to solve them. Adding additional, separate assets to add new behaviour (or override CSS) feels like a better solution to me. Then if anyone wants to fully override Administrate's own assets, they can copy them over manually and do that.
There was a problem hiding this comment.
Yeah, that makes sense to me 👍
| @@ -0,0 +1 @@ | |||
| //= require_tree ./admin | |||
There was a problem hiding this comment.
Hound's got a point. Should this be
/*
*= require_tree ./admin
*/
There was a problem hiding this comment.
I think it'd be good to remove those generators, but in another PR (I'll get around to it eventually, but if someone else wanted to, go ahead!). And then we can merge this once #2397 goes in.
We are not documenting how to add custom assets to complement or override Administrate's own. In fact I recently came across a client project where this was done the wrong way, causing breakage.
So here's some documentation on it, as well as adds examples to the example app. The examples (particularly the CSS one) are a bit artificial, but I couldn't think of anything else. Suggestions welcome.