Gulp asset pipeline documentation

[rtpHarry]

This needs documenting as it's going to be in 1.9.2

Notes can be taken from OrchardCMS/Orchard#5450

@DanielStolt you said you would do this documentation. Have you got anything in motion for it? I'm not giving you a hard time, I just don't want to start writing stuff if its already half done :)

[DaRosenberg]

@rtpHarry Indeed I did say so - it's on my Trello board, but I haven't started on it unfortunately. I'd be happy to assist though - if you create an initial draft in a branch, I can review and add to it?

[rtpHarry]

ok

[rtpHarry]

I have started work on this today :) just thought I would let you know that I hadn't forgotten about it.

I've been working on a big PR, #221 but that's launched now so I can get this one done next.

[DaRosenberg]

@rtpHarry Sounds good - let me know if you want anything reviewed!

[rtpHarry]

@DanielStolt I've been working on this in #256 and I have a couple of sticking points.

Customising the asset pipeline

I'm not sure exactly where I saw it but I was under the impression the advice was to duplicate the gulpfile.js and make amendments to that so that it didn't get overwritten by orchard updates.

When I tried this Task Runner Explorer ignored my dup and carried on loading the gulpfile.js. Deleting gulpfile.js didn't make it recognise it either. Have you done this? Is there a working technique?

Bower

Do you have a strategy for using bower with all this?

npm install

I have a feeling you told me about some hidden technique to run npm install, like highlighting something and pressing enter? Do you know what I'm talking about?

[rtpHarry]

I set up a theme to use bower by adding a .bowerrc file in the module root which points the install dir to /Assets/bower_components/, then used bower to install some packages and less to include them as normal assets.

This works for the theme but CMS wide I don't know what the best solution is. In my case I'm including bootstrap so I can get at the bootstrap variables like the screen size when building responsive ui and to override styles.

If I, or a 3rd party module then wanted to do anything with Bootstrap we are going to get issues either of the files being included twice or different versions being wired in.

I'm not sure if the correct solution to this would be editing the gulpfile.js to integrate something like wiredep and doing the bower commands in the src root folder.

[DaRosenberg]

Hi @rtpHarry, sorry for the late reply, I've had a back surgery so I've been a little out of it for the last few weeks.

I don't know of any recommendations for customizing, and I don't know a clear best way to do it. Haven't tried the scenario you mentioned. In my projects I've been lucky enough to have the solution file in a different folder, so I've been able to keep a separate gulp file there.

I have not given any thought to fitting Bower into it all.

Yes, for some reason opening the package.json file in VS and just hitting Save triggers an npm install - that might be the trick you're thinking about.

Regarding including Bootstrap variables and mixins in a module/theme, this can totally be done by referencing the files in Orchard.Resources using relative paths in the @imports statements, I've used that technique very successfully.

[rtpHarry]

Sorry to hear that, hope you're on the road to recovery. Thanks for getting back to me I'll fold your feedback into the document.

[rtpHarry]

I've finished the article (woohoo). I will give it one last check for typos and unfinished sentences and then the merge it into the docs.

[rtpHarry]

Assets pipeline is now documented: http://docs.orchardproject.net/en/latest/Documentation/Assets-pipeline/

[DaRosenberg]

Nice job @rtpHarry!

There's no mention of the "watch" property though, which you can use in your asset manifest group to configure additional files to be watched for changes - this should probably be added as it's pretty crucial when using LESS includes.

It might also be worth mentioning some specifics of how the watch task works, including what happens when asset files are modified, when the manifest itself is modified. And also mention the limitations (e.g. it won't detect an asset file being added even if it matches an already existing glob pattern in the asset manifest, etc).

Also might be worth pointing out that source maps are added for non-minified outputs only.

[rtpHarry]

Thanks for the feedback, I'll re-open the issue until I've had a chance to make some tweaks

[rtpHarry]

There's no mention of the "watch" property though, which you can use in your asset manifest group to configure additional files to be watched for changes - this should probably be added as it's pretty crucial when using LESS includes.

I didn't know about this, to be honest I bolted Sass on straight away as that's what I use. Is it in there now or upcoming in dev? With Sass I just added the whole set of them including the master sass file which included all the other partials. It worked for watching all changes and I didn't end up with duplicate rules in the output css.

[rtpHarry]

OrchardCMS/Orchard#6871 (comment)

[agriffard]

@DanielStolt Can you please update the 'Gulp asset pipeline documentation'?

[DaRosenberg]

@agriffard Yep I'm on it. I've started a PR, I'll let you know when it is ready to be reviewed and merged.

[DaRosenberg]

#320