Generalizing code for helpers about handlebars-helpers HOT 15 CLOSED

@Arkkimaagi I removed a number of comments that were unrelated to this issue (regarding grunt-init-assemble). If you have issues with that still, let's move the conversation over to that repo: https://github.com/assemble/grunt-init-assemble/issues cc @doowb

from handlebars-helpers.

Here is another option. We could refactor this library so that:

• each helper is in a file of its own
• organized into logical groupings, or "bundles" (string helpers, math helpers, etc)
• each bundle would get its own repo on GitHub
• the helpers would use a format that is consumable by assemble's helpers option, so that all helpers are included that way, instead of requiring them as a lib by assemble.
• Since helpers rely on common utilities, the method for handling utilities will need to be addressed. @doowb what are our options?

Then helper bundles could be downloaded, git cloned, or installed using bower install xyz-helpers, enabling developers an opportunity to actually play around with, customize, add or remove the helpers on a project-by-project basis. Currently helpers in assemble are kind of a "black box" to developers, this would change that.

If we go this route, namespacing isn't nearly as much of an issue, helper "bundles" could then be included/excluded in projects at the developer's discretion, hopefully we'll get more pull requests for useful helpers.

Unless there are issues with the utilities, or something else I haven't thought of, this option gets my vote. @Arkkimaagi / @doowb can I get your feedback?

from handlebars-helpers.

@jonschlinkert I just figured out my roadblock with how to handle options passed in from assemble and still being able to split helpers out into their own libraries, so I think this task will be a lot easier now.

Also, I think for the utilities, we just need to create a common lib that they all depend on.

from handlebars-helpers.

@doowb k I think that would be good

from handlebars-helpers.

A huge advantage of splitting helpers into their own files would be to make it easier to use them client-side.

Currently, if we want to browserify the a helper, we get:

• all the other helpers in the category
• all the utils
• the custom version of handlebars

This is fine and all on the server, but in the browser where smallness matters, it's untenable.

from handlebars-helpers.

@joeybaker thank you, great points. I think we're totally on board with doing this, it's just a matter of time until it gets done. and we've gotten like a half dozen requests to do it this week, so we have that going for us.

we just need to get started and have a convention that is used consistently across the helpers and utils. any suggestions you have for these conventions are welcome. thanks!

from handlebars-helpers.

Time is always the hard part :)

If it were me, I think i'd skip having a separate repo for each 'bundle', and simply split each helper into a different file that explicitly includes just the utils (also split into their own files) that it needs. index.js could just require all of the helpers which I think means that the external api wouldn't have to change?

Something like

/helpers
  /dates
    format.js
    …
  …
/util
  formatDate.js
  …

// helpers/dates/format.js

var DateFormat = require('../../util/formatDate.js')
    , Handlebars = require('handlebars')
    , formatDate

module.exports = {
    formatDate: formatDate = function(date, format) {
      date = new Date(date);
      return Dates.format(date, format);
    }
}

module.exports.register = function(customHandlebars, options) {
    var handlebars = customHandlebars || Handlebars // allow the user to specify their own version of handlebars while registering the helper, else, fall back to the global
    handlebars.registerHelper("formatDate", formatDate);
}

from handlebars-helpers.

@joeybaker @jonschlinkert I started some awesomeness!!!

Check out https://github.com/doowb/handlebars-helpers/tree/source-refactor.

I started to refactor the source code and migrate it from coffee script to javascript so we can just get rid of that, but I also started splitting the helpers out into their own files that look like this...

function myHelper(options) {
  return function(some, inputs) {
    return "something generated from " + some + inputs;
  };
};

Also, you'll notice some YFM in a couple of the helpers that require external libraries!
There's a new templates folder in source that just has a handlebarsLayout.hbs file which is used to build each individual helper and register it properly with Handlebars. We can expand on this to include handlebars for the web, lodash mixins for node and web, etc...

I added an assemble build target to the grunt file, but I had to make some changes to assemble and assemble-handlebars to make this work without getting unresolved cyclical dependency errors. I only have this stuff checked into my repos for testing purposes, but I think we can merge those in to the main repos soon. I tried to write out useful errors messages since the changes will require people to do npm install for assemble-handlebars and handlebars-helpers if they want to use them in assemble.

I think I can finish this up tomorrow. @jonschlinkert I think we need to talk about migrating the source to it's own repos and only having the distributed files in this repo (node and web versions).

from handlebars-helpers.

@doowb I like it! I think we should change the delimiters on the YFM so that it uses code comments. also we should use some kind of logic for building paths so we don't need to hard-code paths to local dependencies

see this issue assemble/assemble#172

I can build out some regex patterns for different use cases and file types.

from handlebars-helpers.

@doowb let's keep the helpers and utils namespaced with helper-name.js and utils-name.js. It's not as terse and minimalist, but it makes them more likely to be found in searches so people who need them can find them. we can just use the path parts for the names and categories...

grunt.file.expand('helpers/*.js').forEach(function(filepath) {
  // Parse out the helper name and category name.
  var basename = path.basename(filepath, '.js');
  var parts = basename.split('-');
  // etc...

from handlebars-helpers.

@jonschlinkert So, you're saying that the source files will be in helpers/math-add.js, helpers/math-subtract.js, etc... but when built into the file that registers the Handlebars helper, they would get registered as add, subtract, etc...?

I think this can be done with a helper 😀

Also, for the YFM... I forgot if we added the custom delimiters to that or not. I'll take a look and if we did, then I can add it. This will allow it to look more like a javascript file, but remember the source files aren't complete files since references to dependencies won't be there until after it's 'compiled' into a distribution.

I'm going to work on a few unit tests for the helpers that I converted so far to make sure my generated code is correct and working the way I think it will.

from handlebars-helpers.

but remember the source files aren't complete files since references to dependencies won't be there until after it's 'compiled' into a distribution.

Yeah I was thinking about that, but I was thinking that code comments would look better in sublime text than unstyled YFM. But it's not really an improvement is it... in fact why don't I just add syntax highlighting for YFM to the javascript language definitions :-) then it will look fine.

I was also thinking we should add extension mapping for javascript files to assemble, but this is kind of an edge case.

from handlebars-helpers.

I think this can be done with a helper

lol

from handlebars-helpers.

@doowb it just occurred to me that this might be a better use case for using grunt.template.process with lodash templates instead of handlebars. Then all of the wrapping can be done with options.banner and options.footer.

from handlebars-helpers.

instead of doing this: https://github.com/doowb/handlebars-helpers/blob/source-refactor/dist/handlebars/helpers/math/ceil.js#L9-L11, why don't we just export the function, and then register all of the handlebars helpers in one file (as opposed to registering each helper in the same file as the source)?

from handlebars-helpers.