├── readme.rst
├── rename.json
├── root
    ├── Gruntfile.js
    ├── _gitignore
    ├── auth.json
    ├── license.txt
    ├── package.json
    ├── project.json
    ├── src
    │   ├── component
    │   │   ├── _template.html
    │   │   ├── component.js
    │   │   └── component.less
    │   └── index.html
    └── tasks
    │   ├── build.js
    │   ├── bundle.js
    │   ├── connect.js
    │   ├── lib
    │       ├── browserify-less.js
    │       └── browserify-template.js
    │   ├── publish.js
    │   └── watch.js
└── template.js


/readme.rst:
--------------------------------------------------------------------------------
 1 | Seattle Times Component Template
 2 | ================================
 3 | 
 4 | (or, The Poor Journalist's Polymer)
 5 | -----------------------------------
 6 | 
 7 | This project is a scaffolding for `grunt-init <http://gruntjs.com/project-scaffolding>`__ intended to smooth the process of creating reusable web components. It provides a basic setup process for bundling custom element definitions, along with their templates and styles, into a single .js file for easy use.
 8 | 
 9 | Since these components are meant to be used with IE9 and up with a very small footprint, they do not use all the features of the Web Components "spec," and they do not use Polymer's platform shim. Instead, the following libraries/techniques are used:
10 | 
11 | * A LESS plugin for RequireJS packages styles with the component, and automatically adds them on first load, instead of HTML imports
12 | * `doT.js templates <http://olado.github.io/doT/>`__ are pre-compiled and packaged through a second AMD plugin, instead of using ``<template>``
13 | * The minimal `registerElement() <https://github.com/WebReflection/document-register-element>`__ shim is included for custom elements
14 | * Shadow root is not supported by default, although you're welcome to make use of it
15 | 
16 | By default, the template sets up your package to be published to Bower, in addition to deployment as a bundle file. This way, you can include these components in other projects without incurring a loading penalty from pulling in the bundles separately.
17 | 
18 | For more details as to how the scaffolding is installed and run, see our `news app template <https://github.com/seattletimes/newsapp-template>`__, on which this is based.
19 | 
20 | Project layout
21 | --------------
22 | 
23 | By default, a project can contain one or more components. Each one should be contained in its own folder, along with its styles and templates. So, for example, if we were making a component called ``responsive-frame``, we would probably have the following layout:
24 | 
25 | * /src/responsive-frame/responsive-frame.js - Main module for the custom element
26 | * /src/responsive-frame/_template.html - doT template for the element
27 | * /src/responsive-frame/responsive-frame.less - LESS file for the element
28 | 
29 | The scaffolding will also set up an ``index.html`` file with your tag pre-inserted for testing. In the build directory, each component folder will generate two JavaScript files--one for development, which includes a source map, and one marked ``.min.js``, which is for production and omits the source map (eventually it'll be minified as well). 


--------------------------------------------------------------------------------
/rename.json:
--------------------------------------------------------------------------------
1 | {
2 |   "_gitignore": ".gitignore"
3 | }


--------------------------------------------------------------------------------
/root/Gruntfile.js:
--------------------------------------------------------------------------------
1 | module.exports = function(grunt) {
2 | 
3 |   //load tasks
4 |   grunt.loadTasks("./tasks");
5 | 
6 |   grunt.registerTask("default", ["bundle", "build", "connect", "watch"]);
7 |   
8 | };
9 | 


--------------------------------------------------------------------------------
/root/_gitignore:
--------------------------------------------------------------------------------
1 | node_modules/
2 | build/
3 | temp/
4 | src/lib/
5 | auth.json


--------------------------------------------------------------------------------
/root/auth.json:
--------------------------------------------------------------------------------
1 | {
2 |   "s3": {
3 |     "accessKeyId": "{%= s3_key %}",
4 |     "secretAccessKey": "{%= s3_secret %}",
5 |     "region": "{%= s3_region %}"
6 |   }
7 | }


--------------------------------------------------------------------------------
/root/license.txt:
--------------------------------------------------------------------------------
 1 | This program is free software: you can redistribute it and/or modify 
 2 | it under the terms of the GNU General Public License as published by
 3 | the Free Software Foundation, either version 3 of the License, or
 4 | (at your option) any later version.
 5 | 
 6 | This program is distributed in the hope that it will be useful,
 7 | but WITHOUT ANY WARRANTY; without even the implied warranty of
 8 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 9 | GNU General Public License for more details.
10 | 
11 | You should have received a copy of the GNU General Public License
12 | along with this program.  If not, see <http://www.gnu.org/licenses/>.


--------------------------------------------------------------------------------
/root/package.json:
--------------------------------------------------------------------------------
 1 | {
 2 |   "name": "component-{%= tag_name %}",
 3 |   "description": "{%= component_description %}",
 4 |   "version": "0.0.1",
 5 |   "author": "{%= author_name %}",
 6 |   "repository": {
 7 |     "type": "git",
 8 |     "url": "https://github.com/{%= github_repo %}.git"
 9 |   },
10 |   "main": "src/{%= tag_name %}/{%= tag_name %}",
11 |   "dependencies": {
12 |     "async": "^1.2.1",
13 |     "aws-sdk": "^2.1.33",
14 |     "babelify": "^6.1.2",
15 |     "browserify": "^10.2.4",
16 |     "chalk": "^1.0.0",
17 |     "document-register-element": "^0.4.3",
18 |     "dot": "^1.0.2",
19 |     "exorcist": "^0.4.0",
20 |     "grunt": "^0.4.5",
21 |     "grunt-contrib-connect": "^0.10.1",
22 |     "grunt-contrib-watch": "^0.6.1",
23 |     "less": "^2.0.0",
24 |     "mime": "^1.2.11",
25 |     "resolve": "^1.1.7",
26 |     "shelljs": "^0.5.1",
27 |     "through2": "^2.0.0"
28 |   },
29 |   "browserify": {
30 |     "transform": [
31 |       "./tasks/lib/browserify-template",
32 |       "./tasks/lib/browserify-less"
33 |     ]
34 |   }
35 | }
36 | 


--------------------------------------------------------------------------------
/root/project.json:
--------------------------------------------------------------------------------
 1 | {
 2 |   "s3": {
 3 |     "stage": {
 4 |       "bucket": "",
 5 |       "path": ""
 6 |     },
 7 |     "live": {
 8 |       "bucket": "",
 9 |       "path": ""
10 |     }
11 |   }
12 | }
13 | 


--------------------------------------------------------------------------------
/root/src/component/_template.html:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/seattletimes/component-template/80256912d83abcfe5ed36b2c868962114d13f015/root/src/component/_template.html


--------------------------------------------------------------------------------
/root/src/component/component.js:
--------------------------------------------------------------------------------
 1 | //shim
 2 | require("document-register-element");
 3 | 
 4 | //element setup
 5 | var template = require("./_template.html");
 6 | require("./{%= tag_name %}.less");
 7 | 
 8 | var proto = Object.create(HTMLElement.prototype);
 9 | 
10 | proto.createdCallback = function() {};
11 | proto.attachedCallback = function() {};
12 | proto.detachedCallback = function() {};
13 | proto.attributeChangedCallback = function() {};
14 | 
15 | try {
16 |   document.registerElement("{%= tag_name %}", { prototype: proto });
17 | } catch (e) {
18 |   console.error("<{%= tag_name %}> has already been registered.")
19 | }


--------------------------------------------------------------------------------
/root/src/component/component.less:
--------------------------------------------------------------------------------
1 | {%= tag_name %} {
2 |   * {
3 |     -webkit-box-sizing: border-box;
4 |     -moz-box-sizing: border-box;
5 |     -ms-box-sizing: border-box;
6 |     box-sizing: border-box;
7 |   }
8 | 
9 | }


--------------------------------------------------------------------------------
/root/src/index.html:
--------------------------------------------------------------------------------
1 | <!doctype html>
2 | <html>
3 |   <body>
4 |     <h1>Test page for {%= tag_name %}</h1>
5 |     <{%= tag_name %}></{%= tag_name %}>
6 |     <script src="{%= tag_name %}.js"></script>
7 |   </body>
8 | </html>


--------------------------------------------------------------------------------
/root/tasks/build.js:
--------------------------------------------------------------------------------
 1 | /*
 2 | 
 3 | Build HTML files using any data loaded onto the shared state.
 4 | 
 5 | */
 6 | 
 7 | var path = require("path");
 8 | 
 9 | module.exports = function(grunt) {
10 | 
11 |   grunt.template.include = function(where, data) {
12 |     var file = grunt.file.read(path.resolve("src/", where));
13 |     return grunt.template.process(file, {data: data || grunt.data});
14 |   };
15 | 
16 |   grunt.registerTask("build", "Processes index.html using shared data (if available)", function() {
17 |     var files = grunt.file.expandMapping(["**/*.html", "!**/_*.html", "!lib/**/*.html"], "build", { cwd: "src" });
18 |     var data = Object.create(grunt.data || {});
19 |     data.t = grunt.template;
20 |     files.forEach(function(file) {
21 |       var src = file.src.shift();
22 |       var input = grunt.file.read(src);
23 |       var output = grunt.template.process(input, { data: data });
24 |       grunt.file.write(file.dest, output);
25 |     });
26 |   });
27 | 
28 | };


--------------------------------------------------------------------------------
/root/tasks/bundle.js:
--------------------------------------------------------------------------------
 1 | /*
 2 | 
 3 | Builds a source package for all components located in this package
 4 | 
 5 | */
 6 | 
 7 | var async = require("async");
 8 | var browserify = require("browserify");
 9 | var babel = require("babelify");
10 | var exorcist = require("exorcist");
11 | var fs = require("fs");
12 | var path = require("path");
13 | 
14 | module.exports = function(grunt) {
15 | 
16 |   grunt.registerTask("bundle", "Compile build/app.js using Browserify", function() {
17 |     var done = this.async();
18 | 
19 |     //set name, out for each seed file
20 |     var components = grunt.file.expand({filter: "isDirectory", cwd: "src" }, ["*", "!lib"]);
21 |     var files = components.map(function(d) { return path.join(d, d) });
22 |     files.filter(function(f) { grunt.file.exists(f) });
23 | 
24 |     grunt.file.mkdir("build");
25 | 
26 |     async.each(files, function(file, c) {
27 |       var output = "build/" + path.basename(file) + ".js";
28 | 
29 |       var outStream = fs.createWriteStream(output);
30 | 
31 |       var b = browserify({ debug: true });
32 |       b.transform(babel);
33 | 
34 |       b.add("./src/" + file);
35 |       b.bundle().pipe(exorcist(output + ".map")).pipe(outStream).on("finish", function() {
36 |         c();
37 |       });
38 | 
39 |     }, function(err) {
40 |       if (err) console.log(err);
41 |       done();
42 |     });
43 | 
44 |   });
45 | 
46 | };
47 | 


--------------------------------------------------------------------------------
/root/tasks/connect.js:
--------------------------------------------------------------------------------
 1 | /*
 2 | 
 3 | Sets up a connect server to work from the /build folder. May also set up a
 4 | livereload server at some point.
 5 | 
 6 | */
 7 | 
 8 | module.exports = function(grunt) {
 9 | 
10 |   grunt.loadNpmTasks("grunt-contrib-connect");
11 | 
12 |   grunt.config.merge({
13 |     connect: {
14 |       dev: {
15 |         options: {
16 |           livereload: true,
17 |           base: "./build",
18 |           hostname: "localhost"
19 |         }
20 |       }
21 |     }
22 |   })
23 | 
24 | };
25 | 


--------------------------------------------------------------------------------
/root/tasks/lib/browserify-less.js:
--------------------------------------------------------------------------------
 1 | var less = require("less");
 2 | var path = require("path");
 3 | var through = require("through2");
 4 | var resolve = require("resolve").sync;
 5 | 
 6 | // we need to plug into the LESS import statement for node modules
 7 | // Sadly, the less-plugin-npm-import module doesn't handle this well
 8 | // It assumes that we have all our dependencies at the top level
 9 | var npmImporter = {
10 |   install: function(less, pluginManager) {
11 | 
12 |     var FileManager = function() {};
13 |     FileManager.prototype = new less.FileManager();
14 |     FileManager.prototype.supports = function(file, dir) {
15 |       return file.indexOf("npm://") == 0;
16 |     };
17 |     FileManager.prototype.supportsSync = FileManager.prototype.supports;
18 |     FileManager.prototype.resolve = function(file) {
19 |       file = file.replace("npm://", "");
20 |       var resolved = resolve(file, {
21 |         extensions: [".less", ".css"],
22 |         packageFilter: function(package) { 
23 |           if (package.style) package.main = package.style;
24 |           return info;
25 |         }
26 |       });
27 |       return resolved;
28 |     };
29 |     FileManager.prototype.loadFile = function(url, dir, options, env) {
30 |       var filename = this.resolve(url);
31 |       return less.FileManager.prototype.loadFile.call(this, filename, "", options, env);
32 |     };
33 |     FileManager.prototype.loadFileSync = function(url, dir, options, env) {
34 |       var filename = this.resolve(url);
35 |       return less.FileManager.prototype.loadFileSync.call(this, filename, "", options, env);
36 |     };
37 | 
38 |     pluginManager.addFileManager(new FileManager());
39 |   },
40 |   minVersion: [2, 1, 1]
41 | };
42 | 
43 | var _ = function(tmp) {
44 |   return tmp.toString().replace(/^.*\/\*\n*\s*|\*\/\}$/gm, "");
45 | };
46 | 
47 | var lessTemplate = function() {/*
48 | var style = document.createElement("style");
49 | style.setAttribute("less", "{{file}}");
50 | style.innerHTML = {{content}};
51 | document.head.insertBefore(style, document.head.firstElementChild);
52 | */};
53 | 
54 | module.exports = function(file) {
55 | 
56 |   if (path.extname(file).match(/\.(css|less)/)) {
57 |     var buffer = "";
58 |     return through(function(chunk, enc, done) {
59 |       buffer += chunk.toString();
60 |       done();
61 |     }, function(done) {
62 |       var self = this;
63 |       var options = {
64 |         paths: [ path.dirname(file) ],
65 |         plugins: [ npmImporter ]
66 |       };
67 | 
68 |       less.render(buffer, options, function(err, result) {
69 |         if (err) {
70 |           console.error(err);
71 |           return done();
72 |         }
73 |         var output = _(lessTemplate).replace("{{file}}", path.basename(file)).replace("{{content}}", JSON.stringify(result.css));
74 |         self.push(output);
75 |         self.push(null);
76 |         buffer = "";
77 |         done();
78 |       });
79 |     });
80 |   }
81 | 
82 |   return through();
83 | 
84 | };


--------------------------------------------------------------------------------
/root/tasks/lib/browserify-template.js:
--------------------------------------------------------------------------------
 1 | var dot = require("dot");
 2 | var path = require("path");
 3 | var through = require("through2");
 4 | 
 5 | var extensions = [".html", ".txt"];
 6 | 
 7 | dot.templateSettings.varname = "data";
 8 | dot.templateSettings.selfcontained = true;
 9 | dot.templateSettings.evaluate = /<%([\s\S]+?)%>/g;
10 | dot.templateSettings.interpolate = /<%=([\s\S]+?)%>/g;
11 | 
12 | module.exports = function(file) {
13 | 
14 |   if (extensions.indexOf(path.extname(file)) > -1) {
15 |     var buffer = [];
16 |     return through(function(chunk, enc, done) {
17 |       buffer.push(chunk.toString());
18 |       done();
19 |     }, function(done) {
20 |       var text = buffer.join("");
21 |       buffer = [];
22 | 
23 |       var template = dot.compile(text);
24 | 
25 |       this.push("module.exports = " + template.toString());
26 |       this.push(null);
27 |       done();
28 |     });
29 |   }
30 | 
31 |   return through();
32 | 
33 | };


--------------------------------------------------------------------------------
/root/tasks/publish.js:
--------------------------------------------------------------------------------
  1 | var async = require("async");
  2 | var fs = require("fs");
  3 | var path = require("path");
  4 | var chalk = require("chalk");
  5 | var gzip = require("zlib").gzip;
  6 | var mime = require("mime");
  7 | var join = function() {
  8 |   return path.join.apply(path, arguments).replace(/\\/g, "/");
  9 | }
 10 | 
 11 | var aws = require("aws-sdk");
 12 | 
 13 | var formatSize = function(input) {
 14 |   if (input > 1024 * 1024) {
 15 |     return Math.round(input * 10 / (1024 * 1024)) / 10 + "MB";
 16 |   }
 17 |   if (input > 1024) {
 18 |     return Math.round(input / 1024) + "KB";
 19 |   }
 20 |   return input + "B";
 21 | }
 22 | 
 23 | var gzippable = ["js", "html", "json", "map", "css", "txt"];
 24 | 
 25 | module.exports = function(grunt) {
 26 | 
 27 |   var creds = require("../auth.json");
 28 |   var config = require("../project.json");
 29 | 
 30 |   grunt.config.merge({
 31 |     publish: config.s3
 32 |   });
 33 | 
 34 |   var findBuiltFiles = function() {
 35 |     var pattern = ["**/*"];
 36 |     var embargo = config.embargo;
 37 |     if (embargo) {
 38 |       if (!(embargo instanceof Array)) embargo = [embargo];
 39 |       embargo.forEach(function(item) {
 40 |         pattern.push("!" + item);
 41 |         console.log(chalk.bgRed.white("File embargoed: %s"), item);
 42 |       });
 43 |     }
 44 |     var files = grunt.file.expand({ cwd: "build", filter: "isFile" }, pattern);
 45 |     var list = files.map(function(file) {
 46 |       var buffer = fs.readFileSync(path.join("build", file));
 47 |       return {
 48 |         path: file,
 49 |         buffer: buffer
 50 |       }
 51 |     });
 52 |     return list;
 53 |   }
 54 | 
 55 |   grunt.registerTask("publish", "Pushes the build folder to S3", function(deploy) {
 56 | 
 57 |     deploy = deploy || "stage";
 58 | 
 59 |     if (deploy == "simulated") {
 60 |       var uploads = findBuiltFiles();
 61 |       uploads.forEach(function(upload) {
 62 |         var extension = upload.path.split(".").pop();
 63 |         if (gzippable.indexOf(extension) > -1) {
 64 |           console.log("Uploading gzipped %s", upload.path);
 65 |         } else {
 66 |           console.log("Uploading %s", upload.path);
 67 |         }
 68 |       });
 69 |       return;
 70 |     }
 71 | 
 72 |     var c = this.async();
 73 | 
 74 |     var bucketConfig = config.s3[deploy];
 75 |     aws.config.update(creds.s3);
 76 | 
 77 |     var s3 = new aws.S3();
 78 |     s3.createBucket({
 79 |       Bucket: bucketConfig.bucket
 80 |     }, function(err) {
 81 |       if (err && err.code != "BucketAlreadyOwnedByYou") {
 82 |         return console.log(err);
 83 |       }
 84 |       var uploads = findBuiltFiles();
 85 |       async.each(uploads, function(upload, c) {
 86 |         var obj = {
 87 |           Bucket: bucketConfig.bucket,
 88 |           Key: join(bucketConfig.path, upload.path.replace(/^\\?build/, "")),
 89 |           Body: upload.buffer,
 90 |           ACL: "public-read",
 91 |           ContentType: mime.lookup(upload.path),
 92 |           CacheControl: "public,max-age=3000"
 93 |         };
 94 |         //if this matches GZip support, compress them before uploading to S3
 95 |         var extension = upload.path.split(".").pop();
 96 |         if (gzippable.indexOf(extension) > -1) {
 97 |           var before = upload.buffer.length;
 98 |           return gzip(upload.buffer, function(err, zipped) {
 99 |             if (!err) {
100 |               obj.Body = zipped;
101 |               var after = zipped.length;
102 |               obj.ContentEncoding = "gzip";
103 |               console.log("Uploading gzipped %s - %s %s %s (%s)",
104 |                 upload.path,
105 | 
106 |                 chalk.cyan(formatSize(before)),
107 |                 chalk.yellow("=>"),
108 |                 chalk.cyan(formatSize(after)),
109 |                 chalk.bold.green(Math.round(after / before * 100) + "%")
110 |               );
111 |               s3.putObject(obj, c);
112 |             }
113 |           });
114 |         }
115 |         console.info("Uploading", obj.Key);
116 |         s3.putObject(obj, c);
117 |       }, function(err) {
118 |         if (err) return console.log(err);
119 |         console.log("All files uploaded successfully");
120 |       })
121 |     });
122 |   });
123 | 
124 | }


--------------------------------------------------------------------------------
/root/tasks/watch.js:
--------------------------------------------------------------------------------
 1 | /*
 2 | 
 3 | Standard configuration from grunt-contrib-watch:
 4 | - Compile LESS when source files change
 5 | - Compile page template when index.html changes
 6 | - Compile JSON data when CSVs change
 7 | - (optional) Run optimizer on AMD modules when JS files change
 8 | 
 9 | */
10 | 
11 | module.exports = function(grunt) {
12 | 
13 |   grunt.loadNpmTasks("grunt-contrib-watch");
14 | 
15 |   grunt.config.merge({
16 |     watch: {
17 |       options: {
18 |         livereload: true,
19 |         spawn: false
20 |       },
21 |       templates: {
22 |         files: ["src/**/*.html"], //test files for local development
23 |         tasks: ["build"]
24 |       },
25 |       js: {
26 |         files: ["src/**/*"], //everything, due to templating, GLSL, LESS, etc.
27 |         tasks: ["bundle"]
28 |       }
29 |     }
30 |   });
31 | 
32 | };
33 | 


--------------------------------------------------------------------------------
/template.js:
--------------------------------------------------------------------------------
 1 | var exec = require("child_process").exec;
 2 | var path = require("path");
 3 | 
 4 | exports.description = "A standard starting-point for news app development at the Seattle Times.";
 5 | exports.template = function(grunt, init, done) {
 6 |   //prelims
 7 |   var here = path.basename(process.cwd());
 8 | 
 9 |   //process
10 |   init.process(init.defaults, [
11 |     init.prompt("author_name"),
12 |     init.prompt("tag_name", here),
13 |     init.prompt("component_description"),
14 |     init.prompt("github_repo", "seattletimes/component-" + here)
15 |   ], function(err, props) {
16 |     //add environment variables, dynamic properties
17 |     props.s3_key = process.env.AWS_ACCESS_KEY_ID || "";
18 |     props.s3_secret = process.env.AWS_SECRET_ACCESS_KEY || "";
19 |     props.s3_region = process.env.AWS_DEFAULT_REGION || "us-west-1";
20 | 
21 |     var root = init.filesToCopy(props);
22 |     //rename "component" to tag name during move
23 |     for (var key in root) {
24 |       if (key.indexOf("component") > -1) {
25 |         var src = root[key];
26 |         delete root[key];
27 |         var dest = key.replace(/component/g, props.tag_name);
28 |         root[dest] = src;
29 |       }
30 |     }
31 |     init.copyAndProcess(root, props);
32 | 
33 |     //install node modules
34 |     console.log("Installing Node modules...");
35 |     exec("npm install --cache-min 999999", done);
36 |   });
37 | };


--------------------------------------------------------------------------------