Page MenuHomePhorge

Update the documentation for "Adding New CSS and JS" to not exclude extensions
Open, Needs TriagePublic

Description

https://we.phorge.it/book/contrib/article/adding_new_css_and_js/

In my experience, this works just fine, despite the glaring disclaimer (which doesn't stop me, because I have elected to ignore it).
Extensions just need to do the following:

  • Create a directory to store CSS and JS in. Phorge uses rsrc/ within webroot/, which is misleading, because it does not have to be a web-accessible directory.
  • Create a directory where Celerity should store its map. If you already have a resources/ directory, you can create a celerity directory here.
  • Create a new class extending CelerityResourcesOnDisk and link these paths. CelerityPhabricatorResources is a good example.
    • If you do not have a need for packages, you can just create a packages.php file that returns an empty array.
  • Create some resources, following the documentation on how to do so.
  • Run bin/celerity map, which will rebuild for all Celerity resources.
  • Access the new resource by using require_celerity_resource('NAME_OF_RESOURCE', 'EXTENSION_NAME').

Event Timeline

A comment in two parts:
First and most relevant to this task: It certainly would be nice to get some of this into documentation! It took me quite awhile to figure this out when doing my own extension development.

Second, I'm also curious if it could be documented how to declare dependencies on existing phorge JX classes, for instance, from an extension? When I tried in my own extension what I found was that I had to wrap CelerityPhabricatorResources into my own resource class and then check the path being looked up to delegate to phorge resources if it wasn't a resource for my extension. It still doesn't really work very well though. It's quite brittle. If there's a better way I'd love to know!