Noodles Practicing Medicine
    Wondering what’s next for npm?Check out our public roadmap! »

    jmcnet

    1.7.5 • Public • Published

    JMCNet Logo JMCNet library !

    JMCNet provides a JavaScript implementation of the JMCNet Java library (cf. JMCNet Java Library for more information). It provides utility libraries for :

    • jmcnet-date - date manipulation : adding days, weeks and month to date,
    • jmcnet-config - properties file management : automatic reload of .properties file on change, resources bundle for i18n features,
    • jmcnet-email - email management : add attachment, deals with image attachment, automatically create attachment from html text,
    • jmcnet-emailTemplate - templated email features : cooperate with email features above to send beautiful html templated emails,
    • jmcnet-exception - exception feature : the base exception used with all modules above,
    • jmcnet-resourceBundle - Localized resource bundle : dealing with localized resources bundle for i18n,
    • jmcnet-i18n - Internalization (i18n) format functions helper : format String, date, currency and float values considering a locale

    Prerequisites

    • Node.js - Download and Install Node.js. You can also follow this gist for a quick and easy way to install Node.js and npm

    Tools Prerequisites

    • NPM - Node.js package manage; should be installed when you install node.js.

    Optional Built with Gulp

    • Gulp - Download and Install Gulp.
    $ npm install -g mocha
    $ gulp testu
    

    Additional Packages

    • none yet.

    Dependencies

    All JMCNet libs have Lodash and Log4js-node dependencies.

    Quick Install

    The quickest way to get started with JMCNet Library is to fork the Github repo.

    $ [sudo] git fork git@github/jmcollin78/jmcnet.git
    $ cd jmcnet
    $ npm install
    $ npm install -g mocha
    

    We recommend using Grunt to start the test :

    $ gulp testu
    

    If grunt aborts because of JSHINT errors, these can be overridden with the force flag:

    $ gulp -f testu
    

    Alternatively, when not using grunt you can run:

    $ npm test
    

    Troubleshooting

    During install some of you may encounter some issues.

    Most issues can be solved by one of the following tips, but if are unable to find a solution feel free to contact us via the repository issue tracker or the links provided below.

    Update NPM, Bower or Grunt

    Sometimes you may find there is a weird error during install like npm's Error: ENOENT. Usually updating those tools to the latest version solves the issue.

    • Updating NPM:
    $ npm update -g npm
    
    • Updating Mocha:
    $ npm update -g mocha
    

    Cleaning NPM

    NPM has a caching system for holding packages that you already installed. We found that often cleaning the cache solves some troubles this system creates.

    • NPM Clean Cache:
    $ npm cache clean
    

    Getting Started with JMCNet library

    Include JMCNet lib in the require sections :

    var jmcnet = require('jmcnet');
    

    JMCNet Library contains those modules :

    Exception (jmcnet-exception)

    A base module containing BaseException, FunctionalException and TechnicalException

    throw new jmcnet.exception.TechnicalException('The error message', [arg1, arg2]);
    ...
    throw new jmcnet.exception.FunctionalException('The functional error message', [arg1, arg2]);
    

    Date manipulation (jmcnet-date)

    A module containing date helpers functions like :

    • jmcnet.date.getDateHourMinuteNow() : gives the current date limited to minutes informations (skip seconds and millisec),
    • jmcnet.date.getDateToday() : gives the current date limited to date informations (skip hours, muinutes, seconds and millisec),
    • jmcnet.date.addDays(date, nbDays) : gives back a date which is date in argument with days augmented by nbDays,
    • jmcnet.date.addWeeks(date, nbWeeks) : gives back a date which is date in argument with weeks augmented by nbWeeks,
    • jmcnet.date.addMonth(date, nbMonths) : gives back a date which is date in argument with month augmented by nbMonths,
    • jmcnet.date.addMonth(date, nbYears) : gives back a date which is date in argument with year augmented by nbYears,

    .properties files manipulations (jmcnet-config)

    A module for dealing with configuration files in the .properties style (like in Java) with automatic reload of the properties on file changes.

    • jmcnet.config.loadConfig(path, options) : loads a set of configuration files. Path is the base directory of all configuration files. Options are the following :
       // the base file containing a reference to all subfile
       masterFileName: 'master-config.properties',
       // when the master file or a subfile is changed, reloads all
       reloadOnChange: true,
       // period in second between two checks
       checkReloadTimeSec: 10                      
    
    • jmcnet.config.get(key) : get the value of a key
    • jmcnet.config.getKeys() : get all the properties keys
    • jmcnet.config.addListener(callback) : adds a listener to the configuration reloads. The callbacks are called upon a config reload
    • jmcnet.config.getFirst(key, defaultValue) : get the first properties value declared with the key
    • jmcnet.config.getLast(key, defaultValue) : get the last properties value declared with the key

    Resource bundle for i18n .properties files (jmcnet-resourceBundle)

    A module for dealing with resource bundle files in the .properties style. A resource bundle is a set of files having the same base name, a .properties file extension. Each file contains key/value set with different translations for a same key.

    Examples of resource bundle files:

    test1_en.properties:

    w1=Hello this is an English sentence
    w2=${w1} and I will terminate it.
    

    test1_fr.properties:

    w1=Bonjour ceci est une phrase en Français
    w2=${w1} et je la termine.
    templatedString=The templated String with val1=<%= val1 %> and val2=<%= val2 %>.
    

    test1_fr_FR.properties:

    w1=Bonjour ceci est une phrase en Français de France
    w2=${w1} et je la termine.
    
    • jmcnet.resourceBundle.ResourceBundle(path, baseName, options) : creates a resource bundle (ie. the set of files for each translation). Path is the base directory of all .properties files. BaseName is the base name used for all files. See options below.
    var rsc = new jmcnet.resourceBundle.ResourceBundle('./path/to/resources/', 'test1');        
    
    • jmcnet.resourceBundle.getLocaleFile(bundleBaseName, locale) : gets the previously loaded properties file for bundle with base name 'bundleBaseName' and for locale 'locale'. If no file is provided for locale 'locale' the most approching locale is returned. That is file returned for base name 'test1' and locale 'en_En' could be (in order) 'test1_en_En.properties' or test1_en.properties' if the first one is not found,
    • jmcnet.resourceBundle.getLocaleString(file, key, context) : get a string from a locale file 'file'. The string is assumed to be a template string (in the form of ejs). Values from template string are replaced with 'context'. See example below,
    • jmcnetResourceBundle.getBundle(bundleBaseName) : retrieve the bundle named bundleBaseName
    • ResourceBundle.load([callback]) : load all resource bundle files. If callback is provided, load is done asynchronously and callback is a function that takes an error in argument.
    • ResourceBundle.getFiles() : get all the properties files loaded. jmcnet.resourceBundle.getFiles().fr gives the property file for locale 'fr',
    • ResourceBundle.setOptions(options) : set the reload options of the resource bundle. Available options are :
       // when one of the locale file is changed, reloads it
       reloadOnChange: true,
       // period in second between two checks
       checkReloadTimeSec: 10                      
    

    Code example using the tests files above :

    new jmcnetResourceBundle.ResourceBundle('./test/resources/', 'test1', {
       reloadOnChange: false // don't check for file change
    }); 
    // creates a new ResourceBundle will check for file change every minutes
    new jmcnetResourceBundle.ResourceBundle('./test/resources/', 'test2');
    ...
    // gets the French for France properties file with base name test1
    var w2 = jmcnetResourceBundle.getLocaleFile('test1', 'fr_FR').get('w2');
    expect(w2).to.equal('Bonjour ceci est une phrase en Français de France et je la termine.');
    ...
    var w2 = jmcnetResourceBundle.getLocaleFile('test1', 'en_US').get('w2');
    expect(w2).to.equal(Hello this is an English sentence and I will terminate it.');
    ...
    var rsc = new jmcnetResourceBundle.ResourceBundle('./test/resources/', 'test2');
    var localeFile = rsc.getLocaleFile('en_EN');
    war w2 = localeFile.get('a.key', 'a default value');
    ...
    rsc.setOptions({
        reloadOnChange: true,
        checkReloadTimeSec: 60 // check every minute if file has change and reloads the file
    });
    ...
    
    // Templating
    var localFile = jmcnetResourceBundle.getLocaleFile('test1', 'fr');
    var replacedValue = jmcnetResourceBundle.getLocaleString(
        localFile,
        'templatedString',
        { val1 : 'val1', val2 : 12});
    expect(replacedValue).to.equal('The templated String with val1=val1 and val2=12.');
               
    

    Email features (jmcnet-email)

    A module to manage email and image attachments. You can use like this :

    • Create email
    var Email = jmcnet.email.Email;
    var email = new Email('from@test.com', 'to@test.com', 'My subject string', 'My text string', '<html>My html string</html>');
    
    • Create a fake transport (useful for testing)
    var fkTp = jmcnet.email.setFakeTransport();
    email.sendEmail(function () {
        expect(fkTp.sentEmails).to.have.length(1);
        var sentEmail = fkTp.sentEmails[0];
        // reseting the sent mails
        fkTp.resetSentEmails();
        expect(fkTp.sentEmails).to.have.length(0);
        done();
    });
    
    • or create a real smtp transport
    var smtpServer = 'smtp.xxx.xxx';
    var port = 465;
    var login = 'xxxx';
    var pwd = 'xxxx';
    var from = 'xxxx';
    var to = 'xxxx';
    jmcnet.email.setSmtpTransport(smtpServer, port, login, pwd, 60000); // 60 sec timeout
    var email = new Email(from, to, 'Test email fron JmcNetEmail lib', 'My text string', '<html>My html string</html>');
    email.sendEmail(function (err, info) {
        log.trace('Send real Email on a real smtp server return. Err="%s", info="%s"', err, util.inspect(info));
        if (err) { // manage error
        }
        ...
    });
    
    • Adding attachment
    email.addAttachment('image.png', 'http://url/to/images.png');
    
    • Replace all image in html with an attachment and corresponding cid:
    email = new Email('from@test.com', 'to@test.com',
           'My subject string',
           'My text string',
           '<html>An image: <img src="./images/test.png"></img></html>');
    email.createImageAttachmentFromHtml('/path/to/images/');
    // This last command parse the html, replace all <img src=> with the corresponding cid: instruction
    

    Email templating features (jmcnet-emailTemplate)

    This module provides very easy features to send beautiful html email based on template.

    • Creates a template from Strings
    var EmailTemplate = jmcnet.emailTemplate.EmailTemplate;
    var template = new EmailTemplate(
           'templateName',
           'The subject of the mail with <%= user.lastname %>',
           '<html>The email templated body <%= user.firstname %></html>');
    
    
    • Loads a template from a file
    var template = jmcnet.emailTemplate.loadEmailTemplateFromFile(
           'templateName',
           'subject <%= title %>',
           '/path/to/template/file.html');
    
    • Retrieve a previously loaded template
    jmcnet.emailTemplate.getLstTemplates(); // list all templates
    var template = jmcnet.emailTemplate.getEmailTemplate('templateName');
    
    • Reset all loaded templates
    jmcnet.emailTemplate.resetEmailTemplates();
    
    • Sends a templated email
    email = new Email(from, to);
    jmcnet.email.setSmtpTransport(smtpServer, port, login, pwd, 60000);
    template = jmcnet.emailTemplate.loadEmailTemplateFromFile('realTemplate ', '[\u2601 Testu] Création d\'un compte', 'test/emailTemplates/realTemplate.html');
    var context={
               mail_commons_header : 'Vous recevez cet e-mail ...',
               headerH1 : 'Création d\'un compte',
               account : {
                   email : 'test@testu.com',
                   pseudo : 'The test man'
               },
               password : 'hyXPyDKx',
               urlAccountApp : 'http://clouderial.com/account-web'
    };
    var lang='fr';
    jmcnetEmail.setBaseImgDir('./test/emailTemplates/images');
    // Does a 2 pass rendering
    template.sendEmail2Pass(email, context, lang, function (err, info) {
               expect(err).to.not.exist;
    });
    

    or

    // Does a single pass rendering
    template.sendEmail(email, context, lang, function (err, info) {
               expect(err).to.not.exist;
    });
    
    • Format date String
    tpl = new jmcnetEmailTemplate.EmailTemplate('template1', 'The date is <%= date.toLocaleDateString(lang) %>', '...');
    subject = tpl.renderSubject({
               date: d,
               body: 'This is the body of the mail'
    }, 'fr');
    expect(subject).to.equal('The date is 31/08/2014');
    

    or

    subject = tpl.renderSubject({
               date: d,
               body: 'This is the body of the mail',
               lang : 'fr'
    });
    expect(subject).to.equal('The date is 31/08/2014');
    

    Internationalization (i18n) features (jmcnet-i18n)

    This module provides very easy features to internationalize your template.

    • Set locale
    var i18n = jmcnet.jmcnetI18n;
    i18n.setLocale('fr');
    expect(i18n.getLocale()).to.equal('fr');
    
    
    • Set currency symbol
    var i18n = jmcnet.jmcnetI18n;
    i18n.setCurrencySymbol('€');
    expect(i18n.getCurrencySymbol()).to.equal('€');
    
    
    • Extract locale from an Http request
    var i18n = jmcnet.jmcnetI18n;
    i18n.getLocaleFromRequest(req); // req.headers.accept-language = 'fr ...'
    expect(i18n.getLocale()).to.equal('fr');
    
    
    • Format a currency value in cents
    var i18n = jmcnet.jmcnetI18n;
    i18n.setLocale('fr').setCurrency('€');
    expect(jmcnetI18n.formatCurrency(123456, false, false)).to.equal('1.234,56&nbsp;€');
    expect(jmcnetI18n.formatCurrency(123456, false, true)).to.equal('1234,56&nbsp;€');
    expect(jmcnetI18n.formatCurrency(123456, true, false)).to.equal('1.234,56');
    expect(jmcnetI18n.formatCurrency(123456, true, true)).to.equal('1234,56');
    expect(jmcnetI18n.formatCurrency(123400, true, false)).to.equal('1.234,00');
    expect(jmcnetI18n.formatCurrency(123400, true, true)).to.equal('1234,00');
    expect(jmcnetI18n.formatCurrency(1234, false)).to.equal('12,34&nbsp;€');
    expect(jmcnetI18n.formatCurrency(1200, true)).to.equal('12,00');
    
    
    • Format a float value in cents
    var i18n = jmcnet.jmcnetI18n;
    i18n.setLocale('fr');
    expect(jmcnetI18n.formatFloatCent(123456, false)).to.equal('1.234,56');
    expect(jmcnetI18n.formatFloatCent(123456, true)).to.equal('1.234,56');
    expect(jmcnetI18n.formatFloatCent(123400, false)).to.equal('1.234');
    expect(jmcnetI18n.formatFloatCent(123400, true)).to.equal('1.234,00');
    expect(jmcnetI18n.formatFloatCent(1234, false)).to.equal('12,34');
    
    
    • Format a percent value in cents
    var i18n = jmcnet.jmcnetI18n;
    i18n.setLocale('fr');
    expect(jmcnetI18n.formatPercent(1234, false)).to.equal('12,34 %');
    expect(jmcnetI18n.formatPercent(1234, true)).to.equal('12,34 %');
    expect(jmcnetI18n.formatPercent(1200, false)).to.equal('12 %');
    expect(jmcnetI18n.formatPercent(1200, true)).to.equal('12,00 %');
    
    
    • Format a date
    var i18n = jmcnet.jmcnetI18n;
    var d = new Date(Date.parse('2015-04-11'));
    expect(jmcnetI18n.formatDate(d)).to.equal('11/04/2015');
    
    

    Release notes

    • 1.2.9 : add jmcnetResourceBundle.getLocaleString to get a template String replaced with context
    • 1.2.8 : fix some log verbosity
    • 1.3.0 : update dependencies version and migrate to EJS V2
    • 1.3.1 - 1.3.3 : add HtmlTemplate class as base class for EmailTemplate
    • 1.4.0 - 1.4.2 : add i18n format functions
    • 1.4.3 : add jmcnetConfig.getFirst and jmcnetConfig.getLast in case of multivalued properties
    • 1.4.4 : update dependencies
    • 1.4.5 - 1.4.6 : update java-properties from @mattdsteele and nodemailer in 1.8.0
    • 1.4.7 - 1.4.8 : update java-properties and update dependencies
    • 1.4.9 : add flat format for currency numbers in i18n
    • 1.5.0 : add getLastMonday to get the last monday of a date
    • 1.6.0 : add internationalization for date.format()

    More Information

    License

    This module is distributed under the MIT License.

    Install

    npm i jmcnet

    DownloadsWeekly Downloads

    7

    Version

    1.7.5

    License

    MIT

    Unpacked Size

    681 kB

    Total Files

    43

    Last publish

    Collaborators

    • avatar