README
gulp-component-assembler
Always reference the documents on the git repo since they are updated more often then the NPM package website. I update NPM when there is a code change. I might change documentation without a code change and, at that time, I would not update the version number or NPM release.
gulp-component-assembler
is a gulp plug-in that assembles JavaScript components. The source for the components are a combination of JavaScript files, HTML Templates and Localization strings.
gulp-component-assembler
uses the file assembly.json
to define the list of files to assemble into the component output file. The filename of the component will be the name of the folder that contains the assembly.json
file. The extension of the component file .js
.
Examples: For a folder named
widget
the component output file will bewidget.js
. For a folder namedMyControl
the component output file will beMyControl.js
. The case of the component filename matches the case of the folder name.
Output file location
Prior to version 2.0.0 the component output file would be placed in a folder of the same name as the output file itself.
As of version 2.0.0 the additional folder name is removed and component output file is placed one folder higher than it had been in previous versions.
Example For the path
.../testing/widget/assembly.json
the old, version 1.x, component output file would have been_outputPath_/widget/widget.js
and the new, version 2.0, component output file will be_outputPath_/widget.js
With version 2.x you can continue to use the old output path by including the useOldDest
option in the assemble()
command. See the useOldDest
option below.
The assembled contents of the component file are wrapped inside an Immediately-Invoked Function Expression (IIFE). This helps prevent anything within the component from having a negative effect, like name collisions, with any other script files loaded on the page.
Install
npm install gulp-component-assembler --save-dev
or
npm install -g gulp-component-assembler
Pull Requests and Issues
Please submit pull requests and issues. I want to make this into a tool that is useful to everyone. I will do my best to review and take care of PRs and issues quickly. If you have suggestions, I would love to hear them.
PRs for Third-Party Plug-ins
gulp-component-assembler
supports plug-ins to be run at various times during the assembly process. Plug-ins allow special manipulation of the component output file. If you create a plug-in, please either create a PR on the plug-in page or email me your info. I will add it to the list of third-party plug-ins in the PLUGINLIST.md file
gulp-component-assembler
Usage of The primary usage of the gulp-component-assembler
is to assemble the component output files. This is done when gulp calls the assemble()
function. This function uses the information in the assembly.json
file to assemble the component output file. The source files does not need to be called assembly.json
, but it must be a JSON
file and it must conform to the correct structure of the assembly.json
file. For simplicity, throughout all documentation, I will call this file assembly.json
You can also call the function loadPlugin()
to load plug-ins into the assembly process. Plug-ins, how to use them and how to write them are defined in the plug-ins README.md file
assemble()
function
Example of the Here is an example of how to use the assemble()
function:
var gulp = require('gulp');
var compasm = require('gulp-component-assembler');
gulp.task('assemble', function() {
return gulp.src('./assembly.json')
.pipe(compasm.assemble())
.pipe(gulp.dest('./dist'))
});
Watching assembly files
gulp-component-assembler
provides it's own watch function that should be used in place of gulp.watch
. Pass the function the same parameters you would to gulp.watch
. The watch function only works in Gulp 4.
gulp.task('watch', function() {
compasm.watch('./assembly.json', gulp.series('assemble'));
});
assemble()
function
Options for The assemble()
function takes an optional object which contains any combination of the options defined below. These options allow the user to customize the assembly process and the output file for the component. The options are defined in the object passed to the assemble()
function. Like this:
compasm.assemble({
"defaultLocale": "en",
"exposeLang": true
})
List of Options
Here is the list of options and their description and usage:
Key | Example | Use |
---|---|---|
allowMultiRootTemplates | allowMultiRootTemplates:true/false |
New in 3.0.0 - If set to true then templates can have multiple root nodes. |
defaultLocale | defaultLocale:"en" |
Set the locale that your project will use as the default locale. If you do not provide the defaultLocale option then the default locale is set to "en" . defaultLocale is also the locale that is used if the user attempts to request a non-supported locale. |
exposeLang | exposeLang:true/false |
If set to true then the language strings are also placed into a global object for access outside of the IIFE. The language strings will be added to [globalObj].[assemblyName].lang where assemblyName is the name of the assembly that is being created.See globalObj . |
externalLibName | externalLibName:"filename" |
Name for the external lib file. The default is assembly-lib.js and assembly-lib-min.js .See useExternalLib . |
globalObj | globalObj:"objectToUse" |
This is an optional string that defines the global object that is used to expose the language string into the global scope. The default value is "window.components" .If you are building servers-side components to run in node.js, then you would set this to "global.components" or something similar. But be aware that this could become a problem if you are working with a server cluster.Currently this is only used if you set the option exposeLang to true . |
iifeParams | iifeParams:paramsObject |
This is an optional object that contains the list of parameters used by the IIFE and the list of parameters passed into the IIFE. The default values are "window, document". See Option: iifeParams below. |
localeVar | localeVar:"window.locale" |
The default value for this options is window.locale . If your application uses some other variable to set the locale then you can supply it here like window.myObj.locale . If the defined variable name is undefined or does not exist then the locale is set to the value of the option defaultLocale .See defaultLocale above. |
minTemplateWS | minTemplateWS:true/false |
This controls how white space is processed in the templates. If set to true then each set of white space is reduced to a single space to reduce the overall size of the templates while maintaining separation of tags. If set to false then all white space is preserved with the exception the white space at the beginning and end of the template which is trimmed and removed. |
supportTransKeys | supportTransKeys:true/false |
If set to true this creates a set to translation test values.See Option: supportTransKeys below. |
tagMissingStrings | tagMissingStrings:true/false |
If set to true then any string that was in the locale file for the default locale that is not found in one of the other locale files is marked so the user can see the lack of translation easily. If set to false then the missing translations are set to the key for that string. |
useExternalLib | useExternalLib:true/false |
If set to true then a single file assambly-lib.js is created with the common code used for each assembly. If it is set to false then each assembly contains copies of the common code needed for the assembly to work. If you choose to use the external libraries then you must include that file before including your own. |
useOldDest | useOldDest:true/false |
New in 2.0.0 - If set to true then the output directory structure is used. The output files are placed in the same folder as the assembly.json file. (Same as before ver. 2.0.0) If set to false then the output files are stored one level higher than the pre 2.0.0 locations, the parent folder of where the assembly.json file. |
useStrict | useStrict:true/false |
If set to true then "use strict"; is added just inside the IIFE.See Option: useStrict below. |
Option names are case sensitive. defaultLocale
is correct but DefaultLocale
is not.
Example using options
Below is an example of assembling a component with the following options set:
- Set the default language to French
- Remove extra white space from templates
- Use the external version of the helper library code
- And, by using
gulp-uglify
, the code will be saved in both a non-minified and minified version file.
var gulp = require('gulp');
var uglify = require('gulp-uglify');
var rename = require('gulp-rename');
var compasm = require('gulp-component-assembler');
gulp.task('assemble', function() {
return gulp.src('./assembly.json')
.pipe(compasm.assemble({
"defaultLocale": 'fr',
"minTemplateWS": true,
"useExternalLib": true
})
.pipe(gulp.dest('./dist'))
.pipe(uglify())
.pipe(rename(function (path) {path.basename += "-min";}))
.pipe(gulp.dest('./dist'))
});
#### Option: `iifeParams`
The option iifeParams
is used to provide the values that are accessible within the IIFE function and the values that are passed into the IIFE.
The last parameter in the IIFE function is always undefined
which is automatically added to the function.
To set these values you create an object that has both a use
and a pass
property like this:
"iifeParams": {
"use": "window, document,