Add CSS and JavaScript Files to Phabricator Extensions

By  on  

Every open source framework has its own methods of extending functionality; some make extending incredibly easy and others...not so much.  Most of the time it comes down to how well the framework is documented.  Phabricator did an awesome job of making necessary classes extendable but it's fair to say it would be great if the framework had a bit better documentation (PRs welcome, I bet!).

In creating my own extension, I needed to add JavaScript and CSS files to the page.  Unfortunately the Adding New CSS and JS documentation states "This document is intended for Phabricator developers and contributors. This process will not work correctly for third-party code, plugins, or extensions."  I found that to not be true.  The following is how I added JavaScript and CSS assets for my extension.

Place Asset Files in Your Extension Directory

Each extension I create is placed in its own directory with all dependencies within that directory:

  • extensions
    • my-extension
      • my-extension.php
      • my-extension.css
      • my-extension.js

You could further place CSS and JS files into their own directories if you'd like.  Each CSS and JS file should have a @provides comment by which you'll refer to it when it's time to require it:

/**
 * @provides my-extension-js
 */

I choose to add -js and -css to the reference name for ease in maintenance.

Use require_celerity_resource to Require the File

In the function which represents the view you'd like the assets injected into, you'll use require_celerity_resource with the @provides asset name:

protected function renderLoginForm(AphrontRequest $request, $mode) {
 // Add CSS and JS resources to the page
  require_celerity_resource('bmo-auth-css');
  require_celerity_resource('bmo-auth-js');

  // ....
}

During Build, Move Asset Locations

Phabricator expects all JavaScript and CSS files to be in its /webroot/rsrc/js/ and /webroot/rsrc/css/ directories so you'll need to move your extension assets during the build process.  I added the following to my Dockerfile to do just that:

# Move static resources to phabricator, add files to celerity map array
COPY auth/my-extension.css /app/phabricator/webroot/rsrc/css/my-extension.css
COPY auth/my-extension.js /app/phabricator/webroot/rsrc/js/my-extension.js

With your JavaScript and CSS files in this location, the require_celerity_resource function can find your assets by name.

Updated the Celerity Map

To bust cache and index your files, you'll need to run the following command:

phabricator/ $ ./bin/celerity map

That's the simple but not excellently documented process for adding your own CSS and JavaScript assets to Phabricator!

Recent Features

  • By
    fetch API

    One of the worst kept secrets about AJAX on the web is that the underlying API for it, XMLHttpRequest, wasn't really made for what we've been using it for.  We've done well to create elegant APIs around XHR but we know we can do better.  Our effort to...

  • By
    Introducing MooTools Templated

    One major problem with creating UI components with the MooTools JavaScript framework is that there isn't a great way of allowing customization of template and ease of node creation. As of today, there are two ways of creating: new Element Madness The first way to create UI-driven...

Incredible Demos

  • By
    NSFW Blocker Using MooTools and CSS

    One of my guilty pleasures is scoping out the latest celebrity gossip from PerezHilton.com, DListed.com, and JoBlo.com. Unfortunately, these sites occasionally post NSFW pictures which makes checking these sites on lunch a huge gamble -- a trip to HR's office could be just a click away. Since...

  • By
    Element Position Swapping Using MooTools 1.2

    We all know that MooTools 1.2 can do some pretty awesome animations. What if we want to quickly make two element swap positions without a lot of fuss? Now you can by implementing a MooTools swap() method. MooTools 1.2 Implementation MooTools 1.2 Usage To call the swap...

Discussion

    Wrap your code in <pre class="{language}"></pre> tags, link to a GitHub gist, JSFiddle fiddle, or CodePen pen to embed!