Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Updating version and docs to reflect changes.

  • Loading branch information...
commit 46753699f614dbb02df0d18191684a32850859f5 1 parent 66dfdcb
Alex Sexton authored
Showing with 131 additions and 25 deletions.
  1. +111 −3 README.md
  2. +8 −11 demo-build.html
  3. +10 −11 demo.html
  4. +2 −0  demo/app.build.js
114 README.md
View
@@ -2,15 +2,15 @@
## Version
-Handlebars : v1.0.3beta
+Handlebars : v1.0.beta.4
-hbs.js : v0.1.0
+hbs.js : v0.2.0
## Requirements
Should work in both the java and node build environments.
-Require.js >= 0.27.0 (I recommend 1.0.1+)
+Require.js >= 0.27.0 (I recommend 1.0.2+)
## Usage
@@ -71,6 +71,106 @@ And then the output into your body would be as follows:
YAY!
+# I18n
+
+I added a build-time/run-time helper for internationalization. The best way to see how this works is the demo.
+
+Right now, the syntax for this is the same as handlebars helper syntax, with a helper named `$` (for brevity).
+
+`{{$ "i18nkey"}}`
+
+This key should map to your locale json file.
+
+```javascript
+{
+ "i18nkey" : "This is a localized string."
+}
+
+This 'helper' works differently than actual handlebars templates. It actually modifies the AST that is generated by handlebars at build time.
+It take the 'helper' node and converts it into a simple content node with the correct localized content.
+
+The benefit of this is not having to send your entire localization object to the browser in production apps. Instead the localized strings are added directly into the compiled templates. This is faster in every case. :D
+
+The locale defaults to the `en_us.json` file, but you can set the locale in your require.config (often needs to happen in both your app.build.js and your actual app code) and the locale will change along with that property.
+
+# Helpers
+
+Just put your helpers in `template/helpers/*` and they'll automagically get pulled in as long as you write them as modules.
+
+I find that many helpers are good helpers in regular code as well, so the following is a good practice:
+
+```javascript
+define('template/helpers/roundNumber', ['Handlebars'], function ( Handlebars ) {
+ function roundNumber ( context, options ) {
+ // Simple function for example
+ return Math.round( context );
+ }
+ Handlebars.registerHelper( 'roundNumber', roundNumber );
+ return roundNumber;
+});
+```
+
+Then in your templates, you can just do:
+
+```mustache
+{{roundNumber Data.ThreeFourths}}
+```
+
+The system will make sure these modules are pulled in automatically from that directory. But if your app, you need a rounding module (perhaps in a view/datanormalization place), you could do this:
+
+```javascript
+require(['template/helpers/roundNumber'], function ( roundNumber ){
+ var threeFourths = (3/4);
+ alert( roundNumber( threeFourths ));
+});
+```
+
+It's just a module that happens to register itself.
+
+
+# Meta Data
+
+Any template that begins with a comment, with _only_ a valid json object in it will be read in as meta data for the template.
+
+I encourage you to list the name of the template and give a description, though these aren't strictly necessary.
+
+## Styles
+
+If you want to build stylesheets that are comprised of only styles needed by the templates that your app uses, I encourage you to add a `styles` property to the meta info:
+
+```
+{{!
+{
+ "name" : "template1",
+ "description" : "A nice template.",
+ "styles" : ["templatecss"]
+}
+}}
+```
+
+This will inject a link tag in dev mode to load in this style dynamically. At build time, a screen.build.css is created. At this time it is just a list of import statements. These can be inlined by many existing tools. Eventually I'd love it to just happen.
+
+De-duping happens automatically, so don't worry if multiple templates require the same styles. The styles are injected in the order that they are read in, so usually from least specific to most specific. This is usually what you want, but know that if you do weird things, it could break.
+
+# Introspection
+
+In dev mode a few properties are added to your function (an object in javascript) as a helper with debugging and as a testing plug-point.
+
+Those variables look like the following:
+
+```javascript
+require(['hbs!template/one'], function ( tmplOne ) {
+ console.log(
+ 'Variables referenced in this template: ', tmplOne.vars,
+ 'Partials/templates that this file directly depends on: ', tmplOne.deps,
+ 'Helpers that this template directly depends on: ', tmplOne.helpers,
+ 'The metadata object at the top of the file (if it exists): ', tmplOne.meta
+ );
+});
+```
+
+Note: All of these go away after a build, as they just take up space with data that is known at build time, which is the ideal time to get stuff figured out (speed-wise).
+
# Builds
As long as all of your paths match up, this should precompile all of your templates and include them in the build.
@@ -83,6 +183,10 @@ As long as all of your paths match up, this should precompile all of your templa
![After Build](http://i.imgur.com/JUOlC.jpg)
+## So many dependencies in the `hbs` plugin!
+
+I use them for coding happiness. It shouldn't bother you tooooo much, because it all get built out in production. The `hbs.js` file essentially gets written to the main.js file as a noop (a few empty definitions), and none of it's dependencies are included into the build.
+
# Demo
To run the demo, go into the root directory of this project and run the following command.
@@ -116,6 +220,10 @@ I'd encourage you to _not_ call registerPartials in your code, and just use the
In dev mode, loading the templates requires that you are on the same domain as your templates. This is standard same origin policy stuff. Once you build, though, it won't matter since there are no additional requests. Usually a few cleverly placed host overrides get you through the dev mode hurdles.
+## My helper isn't working
+
+Unfortunately my logic forces a circular dependency right now. The work-around is to add your helper to `template/helpers/all.js` much like the file that is in the demo. When a work-around is found, I'll update that and get it out. This could also be a 'watched' folder and a generated 'all.js' file. Note:: the all.js goes away in the build, so no worries on production size and unneeded helpers.
+
## Doesn't work with my version of Handlebars
This is a barely modified version of handlebars 1.0.3beta (which went out to the world with a non-updated version tag 1.0.2beta, whoops). Some of the functionality in here is new, but none of it should be specific exactly to what makes this work. Though, I did take out the code that tries to identify node.js and act differently, since we want it to be picked up by `require.js` and not the built-in node.js `require` keyword. I also turned it into a proper amd module, which makes it "require-able". There's nothing too crazy, though, so I'd suggest just using it to save yourself time. Or don't.
19 demo-build.html
View
@@ -10,20 +10,17 @@
<!-- use a common require.js and app injection method. -->
-<script src="demo-build/require.js" data-main="demo-build/main.js"></script>
-
-<script>
-// I change the path as to not duplicate the hbs.js and handlebars plugin.
-// Normally, just drop it in the same place as require.js and it'll work fine.
-// Essentially just ignore this.
-require({
- paths : {
+<script>require = {
+ locale : "en_ca",
+ // I change the path as to not duplicate the hbs.js and handlebars plugin.
+ // Normally, just drop it in the same place as require.js and it'll work fine.
+ // Essentially just ignore this.
+ paths : {
'hbs' : '../hbs',
'Handlebars' : '../Handlebars'
}
-});
-</script>
-
+};</script>
+<script src="demo-build/require.js" data-main="demo-build/main.js"></script>
21 demo.html
View
@@ -7,19 +7,18 @@
<body>
<div id="demo-app-container"></div>
-<!-- use a common require.js and app injection method. -->
-<script src="demo/require.js" data-main="demo/main.js"></script>
-
-<script>
-// I change the path as to not duplicate the hbs.js and handlebars plugin.
-// Normally, just drop it in the same place as require.js and it'll work fine.
-// Essentially just ignore this.
-require({
- paths : {
+<!-- If you set the require variable to an object, it automatically is the config :D -->
+<script>require = {
+ locale : "en_ca",
+ // I change the path as to not duplicate the hbs.js and handlebars plugin.
+ // Normally, just drop it in the same place as require.js and it'll work fine.
+ // Essentially just ignore this.
+ paths : {
'hbs' : '../hbs',
'Handlebars' : '../Handlebars'
}
-});
-</script>
+};</script>
+<!-- use a common require.js and app injection method. -->
+<script src="demo/require.js" data-main="demo/main.js"></script>
</body>
</html>
2  demo/app.build.js
View
@@ -18,6 +18,8 @@
"Handlebars" : "../Handlebars"
},
+ locale: "en_ca",
+
modules: [
//Optimize the application files. Exclude jQuery since it is
//included already in require-jquery.js
Please sign in to comment.
Something went wrong with that request. Please try again.