Search code examples
javascriptjquerygoogle-closure-compilergoogle-closure-librarygoogle-closure-stylesheet

How do I use Google Closure Stylesheet renaming with an external Javascript Library such as jQuery?

I'm looking into Google's stylesheet renaming feature and I'm not sure how to rewrite my jquery selectors. I didn't find the doc very clear on that.

If I have some code that looks like this:

<div class="MyClass"></div>
<div id="MyID"></div>

$('.MyClass').someFunc();
$('#MyID').someFunc();

How must the HTML and javascript be written so that CSS renaming will work?

Thanks for your suggestions.

Solution

  • For Closure-stylesheets to work in combination with an external library like jQuery, you will need to use the Closure-library as well to add support for goog.getCssName. However, because Closure-Library is written to make maximum use of the dead code elimination of Closure-compiler, only a very small amount of the library code will be included in the final output (about 1KB in this example).

    Step 1 - Setup your project

    You'll need the following tools:

    Step 2 - Setup Your Source Files

    Stylesheet Source (sample.gss)

    @def BG_COLOR              rgb(235, 239, 249);

@def DIALOG_BORDER_COLOR   rgb(107, 144, 218);
@def DIALOG_BG_COLOR       BG_COLOR;

.MyClass {
  background-color: BG_COLOR;
  height:100px;
}

#MyId {
  background-color: DIALOG_BG_COLOR;
  border: 1px solid DIALOG_BORDER_COLOR;
  height:100px;
}

    Closure Template Source (sample.soy)

    {namespace ClosureSample}

/**
 * SampleHtml
 */
{template .SampleHtml autoescape="false"}
    <div class="{css MyClass}"></div>
{/template}

    Javascript Source (sample.js)

    goog.require('ClosureSample');
document.write(ClosureSample.SampleHtml());

$(function() {
    $('.' + goog.getCssName('MyClass')).css('background-color', 'pink');
});

    HTML Source (development.htm)

    <!DOCTYPE html>
<html>
<head>
  <title>Closure stylesheets with External Library</title>
  <link rel="Stylesheet" media="all" href="sample.css" />
  <script type="text/javascript" src="sample_renaming_map.js"></script>
  <script type="text/javascript" src="http://closure-library.googlecode.com/svn/trunk/closure/goog/base.js"></script>
  <script type="text/javascript">
    goog.require('goog.soy');
    goog.require('goog.string.StringBuffer');
  </script>
  <script type="text/javascript" src="soyutils_usegoog.js"></script>
  <script type="text/javascript" src="sample-templates.js"></script>
  <script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.7.2/jquery.min.js"></script>
</head>
<body>
  <script type="text/javascript" src="sample.js"></script>
  <div id="MyId"></div>
</body>
</html>

    Step 3 - Compile your Stylesheet and Templates

    Using the tools downloaded from the templates and stylesheet projects, you'll need to compile the sample.gss and sample.soy files. Here's the commands used for this sample:

    java -jar closure-stylesheets.jar \
    --pretty-print \
    --output-file sample.css \
    --output-renaming-map-format CLOSURE_UNCOMPILED \
    --rename CLOSURE \
    --output-renaming-map sample_renaming_map.js \
    sample.gss

java -jar SoyToJsSrcCompiler.jar \
    --shouldProvideRequireSoyNamespaces \
    --shouldGenerateJsdoc \
    --outputPathFormat {INPUT_FILE_NAME_NO_EXT}.js \
    --cssHandlingScheme goog \
    sample.soy

    With these files, you can test the renaming during development. See the example.

    Step 4 - Compile the Project for Production

    First recompile your stylesheets to produce a renaming map using the "CLOSURE_COMPILED" option:

    java -jar closure-stylesheets.jar \
    --output-file sample.css \
    --output-renaming-map-format CLOSURE_COMPILED \
    --rename CLOSURE \
    --output-renaming-map sample_renaming_map.js \
    sample.gss

    Then you will need to calculate the Closure-library dependency files and compile all of the source javascript files into a single source.

    Note: since jQuery is not compatible with ADVANCED_OPTIMIZATIONS of Closure-compiler, it will not be included as input. Instead, reference the appropriate jQuery extern file found in the Closure-compiler contrib/externs folder.

    The calcdeps.py script in the Closure-library project can be used to also call the Closure-compiler on the input files it determines.

    python calcdeps.py \
    -i sample.js \
    -p PATH_TO_CLOSURE_LIBRARY_FOLDER \
    -p sample-templates.js \
    -o compiled \
    -c compiler.jar \
    -f --js=sample_renaming_map.js
    -f --compilation_level=ADVANCED_OPTIMIZATIONS \
    -f --warning_level=VERBOSE \
    -f --externs=jquery-1.7-externs.js \
    -f --js_output_file=sample_compiled.js

    See the final result: compiled version.

    Final Notes

    As you can see, using Google Closure Stylesheets requires not only pieces of the entire Closure-tools suite, but is quite involved.

    • Outputing the HTML required use of Google Closure-templates. In this contrived example I used a document.write call to output the HTML with the properly renamed class, however there are more elegant and maintainable techniques for production code.
    • Closure-stylesheets does not rename ID selectors, therefore the code for an ID is not affected.
    • For ease of viewing, the compiled example references the jQuery library off of the Google CDN. However, it would be equally valid to concatenate the jQuery library and the compiled source into a single source JS file.