[enhancement] Support for .dust and .properties files under public/components

[tsullivan]

If we want to use Bower components in a Kraken app that contain CSS, JS and Dust files, Bower would not typically install the front-end package files be under public/templates. However, it is not currently possible to render templates that are not within public/templates, and relative path references don't work using the Dust renderer.

Example:

• Dust partial file was installed with bower and exists in public/components/component-name/templates/partial.dust
• File that needs includes the component template exists in public/templates/layout/master.dust

Dust partial includes in Kraken are always relative to public/templates, but including the partial this way does not work:

{>"../components/component-name/templates/partial" /}

The Dust renderer ignores the leading ../ part of the partial's path and gives the error:

Error:ENOENT, open '/Users/tsullivan/webapps/app-name/public/templates/components/component-name/templates/partial.dust

[lmarkus]

I'm unable to reproduce this.

I've placed three dust templates along the tree, and they rendered fine:

/public/templates/small.dust /public/smaller.dust /smallest.dust

from /public/templates/index.dust

{>"layouts/master" /}

{<body}
    <h1>{@pre type="content" key="greeting"/}</h1>
    {>"small" /}
    {>"../smaller" /}
    {>"../../smallest" /}
{/body}

Hello, test!
small!smaller!smallest!

Am I missing anything?

Feel free to reopen as needed.

[tsullivan]

Thanks Lenny, I confirmed that a simpler example does work. I must have had some other code issue before. :relieved:

I'd like my the small Dust template contains a content property:

public/components/small/templates/small.dust:

<h1>{@pre type="content" key="small.greeting"/}</h1>

I will explore what happens when I try this to figure out where to store my small.properties file for the template in this location.

[alexsantos]

@lmarkus , is it possible to compile these templates that are outside /public/templates using grunt build? Or is it necessary to add these paths to Gruntfile.js?

[lmarkus]

In development mode, kraken will compile them on the fly. In production, you'll need to modify the Gruntfile. Out of the box it looks for templates under the templates folder. However, I think that's besides the point. I was just showing a convoluted example here to test the relative path issue.

[alexsantos]

@lmarkus :+1:

[pvenkatakrishnan]

@tsullivan Are you ok with using relative paths though, i thought you wanted something that worked seamlessly with bower components ? One other solution we were just discussing was pointing 'views' config to public folder, and including partials in your dust relative to the public folder. This will let you pick any component checked out.

{>"templates/address.dust"}
{>"components/foo/templates/address.dust"}
{>"lib/bar/address.dust"}

etc. And this will also at some level take care of the grunt task i think. There may be some minor bugs with scanning only .dust files in public folder. But maybe not. Trying it out will be a good idea. The config you want to play with is 'express:views'

[tsullivan]

@pvenkatakrishnan I'd prefer to use relative paths for partials outside of public/templates, that only has impact to those cases. Pointing views config to public seems would impact how every partial is included, not just component partials, and that's not ideal. The choice to use components with Dust partials shouldn't affect how you use all partials in your project.

[tsullivan]

Changed the issue headline to be more generic for the need of having Dust files and Properties files organized under public/components, which is the location that PayPal's bower components will be installed into for PayPal apps.

The PayPal bower components will provide a few different kinds of files:

• README.md
• templates - Dust partials
• locales - Translations needed for the Dust partials
• js
• css

As an example, as a PayPal UI Engineer, if I want to use a component named "credit-card-entry" then I would do bower install credit-card-entry. This places files into:

• public/components/credit-card-entry/bower.json - version and dependency info
• public/components/credit-card-entry/README.md - docs
• public/components/credit-card-entry/templates - Dust partials
• public/components/credit-card-entry/locales - content
• public/components/credit-card-entry/js - JavaScript
• public/components/credit-card-entry/css - LESS

Where does Kraken come into this?

• The Makara configuration only enables a string for the contentPath and templatePath. It needs to have awareness of templates and content under public/components, so these options should be either a string or an array, and the string should support globs.
• By default, the Kraken Gruntfile makara and dustjs tasks only enable templates under public/templates/**/*.dust and content under locales/**/*.properties. There needs to be documentation to lead users to understand what Grunt task options to update to use components.

This enhancement would introduce a MAJOR benefit for PayPal UI Engineers not "reinventing the wheel" for front-end experiences.

[grawk]

I'm just wading into this, but would it be possible to resolve this issue with symbolic links using relative paths under the existing contentPath and templatePath directories?

[jeffharrell]

Requiring symlinks is a no-no for a long term solution :smile:

What about creating something like a {@component} dust helper so that dust can load from other roots?

Additionally, as @tsullivan / @pvenkatakrishnan mentioned, we'll need to adjust a few settings to ensure that content and builds work.

[jeffharrell]

Tagging for 1.0 milestone.

[grawk]

@jeffharrell Can you elaborate on why symlinking is a no-no? We could dynamically create sym links at some point in the application lifecycle based on config and environment.

Nevermind, I already found a pretty big flaw with that solution.

[grawk]

OK. With some guidance from @jeffharrell I looked at some grunt/bower tasks which copy component files around using various configuration approaches. The one that is closest to fitting the need here is grunt-bower-task.

For this solution I had to propose a minor change: https://github.com/yatskevich/grunt-bower-task/pull/114

I used my fork of the task, and created a sample kraken-js 1.0 app: https://github.com/grawk/bowerz

Please check it out, comment there or here.

[grawk]

Because I'm still not convinced that copying is the way to go, I worked up another branch of bowerz which uses symlinks (via my fork of the grunt-contrib-symlink repo). Please see the README for instructions on usage: https://github.com/grawk/bowerz/blob/symlink/README.md

[mayyan]

I like the idea @jeffharrell mentioned regarding {@component} dust helper. Will it recognize the component is a npm component? Will Kraken 1.0 contain this enhancement?

[grawk]

Attempting to achieve multiple dust roots (as per @jeffharrell 's suggestion) while appealing from an end-user perspective, is complex from an implementation perspective. Express wants a single template root. Trying to add an additional root for this use case is a lot more complex than just symlinking or copying files to the current template root. Perhaps someone from the community can attempt to follow up on the {@component} concept. In the meantime, I've provided two feasible workarounds via either grunt-contrib-symlink (recommended due to the better support of this task module) or grunt-bower-task. You can see the bowerz example kraken app for an explanation of both: https://github.com/grawk/bowerz (symlink branch for symlink example, master branch for file copy example)