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.
pablobm
force-pushed
the
document-custom-assets
branch
from
22a20f5
to
d0cbf27
Compare
|
And related PR to remove old asset generators at #2674, as discussed above. |
We weren't documenting any custom assets, which is a common thing for people to want to do. This does that and also provides an example change in the `example_app`. Example of custom CSS Example of custom JS Document the feature Avoid scss to avoid sassc error If using scss here, you'll get `cannot load such file -- sassc`. Perhaps not if your app is configured to digest scss, but this one isn't.
nickcharlton
force-pushed
the
document-custom-assets
branch
from
d0cbf27
to
b55fed3
Compare
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.