{"id":444,"date":"2016-11-28T22:01:08","date_gmt":"2016-11-28T22:01:08","guid":{"rendered":"http:\/\/www.corrspt.com\/blog\/?p=444"},"modified":"2016-11-28T22:01:08","modified_gmt":"2016-11-28T22:01:08","slug":"ember-conventions-over-conventions","status":"publish","type":"post","link":"http:\/\/www.corrspt.com\/blog\/2016\/11\/28\/ember-conventions-over-conventions\/","title":{"rendered":"Ember – Conventions over Conventions"},"content":{"rendered":"

Today I want to talk about conventions and share something I’ve been doing as I’m working in my app that uses EmberJS<\/a>\u00a0for the front-end.<\/p>\n

Warning: This post\u00a0does assume a certain degree of familiarity with\u00a0ember\/ember-cli and I assume that you have all things installed necessary to run\/build an ember app. There’s a full repository on github with the complete project<\/a>, which I’ll reference from here.<\/p>\n

We’re going to create a very simple app with\u00a0components that have i18n<\/a>, real-time validation, use DDAU (data down, actions up) and some baked-in conventions to make things more “robust”. It will look something like this:<\/p>\n

\"Components<\/a>

Components with validation and i18n<\/p><\/div>\n

The first thing is to create a new project using ember-cli (at the time of writing\u00a0EmberJS is on version 2.9.1) on the terminal:<\/p>\n

ember new\u00a0blog-post-ember-conventions-steps<\/span><\/p><\/blockquote>\n

Then, since we’re going to use i18n, I recommend the excellent ember-i18n addon<\/a>\u00a0and to make things look good we’ll use ember-bootstrap<\/a> and to make validations we’ll use ember-model-validator<\/a>. Also, I like to use ember-truth-helpers<\/a>, so I’m going to install them for later. To install just do the following on the terminal (see this commit for the results<\/a>):<\/p>\n

\n

ember install ember-i18n<\/span><\/p>\n

ember install ember-model-validator<\/span><\/p>\n

ember install ember-bootstrap<\/p>\n

ember install ember-truth-helpers<\/p>\n<\/blockquote>\n

To finish installing ember-i18n, we’ll need two locales (so that we can switch between them), so we just type this in terminal (to create the english and portuguese locales, see this commit<\/a>):<\/p>\n

\n

ember generate locale en<\/p>\n

ember generate locale pt<\/p>\n<\/blockquote>\n

With the required addons out of the way it’s time to generate a new route so that we can work on something (see this commit<\/a>).<\/p>\n

\n

ember g route application<\/p>\n

ember g controller application<\/p>\n<\/blockquote>\n

And we’re going to need a model for this whole thing to work, so I’m going to create a person model:<\/p>\n

\n

ember g model person<\/p>\n<\/blockquote>\n

We’re going to include a simple name<\/strong> and age<\/strong> attribute, so we get the following definition<\/a>:<\/p>\n

import DS from 'ember-data';\r\n\r\nconst {\r\n Model,\r\n attr\r\n} = DS;\r\n\r\nexport default Model.extend({\r\n name: attr('string'),\r\n age: attr('number')\r\n});<\/pre>\n
Component with DDAU<\/h1>\n
For starters we’re going to create a component to handle text\/numeric values which adheres to Data Down Actions Up. In terminal type:<\/p>\n
ember g component attribute-text<\/p><\/blockquote>\n
In our component template we’re going to use a standard bootstrap form definition (I’m omitting a way to bind the value on purpose):<\/p>\n
<div class=\"form-group\">\r\n <label title=\"{{placeholder}}\" \r\n   class='control-label'\r\n   for='{{attribute}}'>\r\n   {{label}}\r\n <\/label>\r\n <input\r\n   value={{get model attribute}}\r\n   class='form-control'\r\n   placeholder={{placeholder}}\r\n   type='text'\r\n   id={{attribute}}\r\n >\r\n<\/div><\/pre>\n
To make things dynamic, the value of the input uses the get helper<\/a>\u00a0which allows me to get a dynamic property, in this case from the model (in the {{get model attribute}}<\/strong> line).<\/p>\n
If I now make my route return a new person instance (so that we have a model to work with)<\/p>\n
routes\/application.js\r\nimport Ember from 'ember';\r\n\r\nexport default Ember.Route.extend({\r\n model() {\r\n   return this.store.createRecord('person');\r\n }\r\n});<\/pre>\n
And I update\u00a0my main application template to display two components like this:<\/p>\n
<div class=\"container\">\r\n <h2 id=\"title\">Conventions, Conventions<\/h2>\r\n\r\n <div class=\"row\">\r\n <div class=\"col-sm-6\">\r\n {{attribute-text\r\n   model=model\r\n   attribute='name'\r\n   label='Name'\r\n   placeholder='Insert your name'\r\n }}\r\n <\/div>\r\n <div class=\"col-sm-6\">\r\n {{attribute-text\r\n   model=model\r\n   attribute='age'\r\n   label='Age'\r\n   placeholder='Insert your age'\r\n }}\r\n <\/div>\r\n <\/div>\r\n\r\n {{outlet}}\r\n<\/div>\r\n\r\n\r\n<\/pre>\n
We’ll get a result like the following (see this commit<\/a> with the result of all changes):<\/p>\n
\"initial-display\"<\/a>
Initial Display<\/p><\/div>\n
Now,\u00a0it’s a start, but I\u00a0said we wanted to used DDAU on our component, so we’re going to make just that, we’ll add an oninput<\/em> handler.<\/p>\n
value={{get model attribute}}\r\noninput={{action this.attrs.onUpdateValue value=\"target.value\"}}\r\nclass='form-control'<\/pre>\n
We’re calling this action ‘onUpdateValue’, so we need to update the\u00a0application template (and controller) to have these actions.<\/p>\n
templates\/application.hbs\r\n...\r\nplaceholder='Insert your name'\r\nonUpdateValue=(action 'setName')\r\n....\r\nplaceholder='Insert your age'\r\nonUpdateValue=(action 'setAge')<\/pre>\n
And in the controller, things look like this:<\/p>\n
import Ember from 'ember';\r\n\r\nconst {\r\n Controller,\r\n get\r\n} = Ember;\r\n\r\nexport default Controller.extend({\r\n\r\n actions: {\r\n   setName(name) {\r\n     let model = get(this, 'model');\r\n     model.set('name', name);\r\n   },\r\n\r\n   setAge(age) {\r\n     let model = get(this, 'model');\r\n     model.set('age', age);\r\n   }\r\n }\r\n});<\/pre>\n
Ok, so now we have a DDAU compatible component, which is nice (see this commit<\/a>).<\/p>\n
Now let’s make\u00a0things more interesting!<\/p>\n
Conventions on i18n<\/h1>\n
Ideally if I need to show the same field of a given model, I would like to have the labels\/placeholders all centralized in a localization file, so I’m going to do the following and\u00a0put the following\u00a0in my locales\/en\/translations.js (and the equivalent in \/pt\/translations.js) and not have to type\u00a0them in the template\u00a0every time.<\/p>\n
export default {\r\n 'model': {\r\n   'person': {\r\n     'name': {\r\n     'label': 'Name',\r\n     'help': 'This name will be used throughout the application to display your name',\r\n     'placeholder': 'Person\\'s complete name'\r\n    },\r\n  'age': {\r\n    'label': 'Age',\r\n    'help': 'This field is used to validate access to some parts of the app, must be 18 or older',\r\n    'placeholder': 'The age (in years)'\r\n    }\r\n  }\r\n }\r\n};<\/pre>\n
Now, to make this work I would have to the following transformation (and use the “t” helper from ember-i18n<\/a>).\u00a0Check this commit for the changes<\/a>.<\/p>\n
templates\/application.hbs\r\n...\r\n{{attribute-text\r\n   model=model\r\n   attribute='name'\r\n   label=(t 'model.person.name.label')\r\n   placeholder=(t 'model.person.name.placeholder')\r\n   onUpdateValue=(action 'setName')\r\n}}<\/pre>\n
I mean, it’s kind of verbose, having to pass all that model.modelName.attribute.xxx <\/strong>over and over again, so I’m going to leverage conventions<\/strong> here. I know that my strings\u00a0are in a translations file with the structure\u00a0being:<\/p>\n
model: {\r\n  attribute: {\r\n    label: 'The Label',\r\n    placeholder: 'The Placeholder',\r\n    help: 'The Help text'\r\n  }\r\n}<\/pre>\n
Let’s update our component to have some additional properties:<\/p>\n
import Ember from 'ember';\r\n\r\nconst {\r\n Component,\r\n inject: { service },\r\n computed,\r\n} = Ember;\r\n\r\nexport default Component.extend({\r\n i18n: service(),\r\n\r\n attribute: '',\r\n\r\n getTranslation(property) {\r\n   return this.get('i18n').t(`model.${this.get('modelName')}.${this.get('attribute')}.${property}`);\r\n },\r\n\r\n modelName: computed.alias('model.constructor.modelName'),\r\n\r\n helpText: computed('i18n.locale', function() {\r\n   return this.getTranslation('help').toString();\r\n }),\r\n\r\n label: computed('i18n.locale', function() {\r\n   return this.getTranslation('label').toString();\r\n }),\r\n\r\n hasHelp: computed('helpText', function() {\r\n   return this.get('helpText').length > 0;\r\n }),\r\n\r\n placeholder: computed('i18n.locale', function() {\r\n   return this.getTranslation('placeholder').toString();\r\n })\r\n\r\n});<\/pre>\n
We are going to leverage the fact that each DS.Model instance knows the model name (through constuctor.modelName<\/strong>) and create a helper method getTranslation<\/strong>\u00a0which uses the model name and attribute name\u00a0to get the translation using that structure we defined in the translations file (model.modelName.attribute).<\/p>\n
Since we also pass the attribute name from the\u00a0application template, we have everything we need. Just need to update the application template and remove the label and placeholder parameters:<\/p>\n
{{attribute-text\r\n  model=model\r\n  attribute='name'\r\n  onUpdateValue=(action 'setName')\r\n}}<\/pre>\n
Also, we can now include the help text that is present in the translations file, in the component template file, like this (relevant\u00a0commit<\/a>):<\/p>\n
{{#if hasHelp}}\r\n  <span class=\"help-block\">{{helpText}}<\/span>\r\n{{\/if}}<\/pre>\n
In order to switch between locales we can add two buttons and an action to\u00a0our controller<\/p>\n
templates\/application.hbs\r\n<button class='btn btn-default' disabled={{eq i18n.locale 'en'}} onClick={{action 'setLocale' 'en'}}>English<\/button>\r\n<button class='btn btn-default' disabled={{eq i18n.locale 'pt'}} onClick={{action 'setLocale' 'pt'}}>Portugu\u00eas<\/button><\/pre>\n
And an action in the controller<\/p>\n
controllers\/application.js\r\n\r\nconst {\r\n  Controller,\r\n  get,\r\n  inject: { service }\r\n} = Ember;\r\n\r\nexport default Controller.extend({\r\n  i18n: service(),\r\n\r\n  actions: {\r\n    ...\r\n    setLocale(value) {\r\n      this.set('i18n.locale', value);\r\n    }\r\n  }\r\n}<\/pre>\n
And with this (see this commit<\/a>), we finish the first part regarding conventions. We basically leverage a predefined structure (convention) in the translations file and the fact that each instance of a model knows the name of the model to retrieve\u00a0all the values associated with a given attribute.<\/p>\n
Part 2 – Preventing bugs\/typos on attribute names using conventions<\/h1>\n
One of the things\u00a0that I find a real problem is doing things like we did before while setting the value on the model:<\/p>\n
setName(name) {\r\n let model = get(this, 'model');\r\n model.set('name', name);\r\n},<\/pre>\n
Doing a set <\/strong>operation and passing a string like\u00a0‘name’ <\/strong>means that if we make a small typo on that ‘name’, we never find out about it until we go hunting a bug because some operation\u00a0that depends on this value\u00a0is having a weird behavior. This is\u00a0a mistake I’ve done plenty of times, and the way I found to deal with my typos is the following:<\/p>\n
I create a file in the utils folder of my app called person-utils.js<\/em> in which I place the following content:<\/p>\n
utils\/person-utils.js\r\nexport default {\r\n PERSON: {\r\n  NAME: 'name',\r\n  AGE: 'age'\r\n }\r\n};<\/pre>\n
This is basically a list of all attributes of the model\u00a0Person, but as a JSON object that I can reference.<\/p>\n
In my controller I now import this file and create a new method:<\/p>\n
controllers\/application.js\r\ni18n: service(),\r\n...\r\nsetField(field, value) {\r\n Ember.assert(`Must pass a valid attribute - ${field}`, !isEmpty(field));\r\n let model = get(this, 'model');\r\n model.set(field, value);\r\n},<\/pre>\n
This method will be used to set the value of a field and assert that the field name is valid (as in, not empty), for this to work now we have to change our controller to look like this:<\/p>\n
controllers\/application.js\r\nimport Ember from 'ember';\r\nimport PersonUtil from '..\/utils\/person';\r\n\r\nconst {\r\n Controller,\r\n get,\r\n inject: { service },\r\n assert,\r\n isEmpty\r\n} = Ember;\r\n\r\nconst {\r\n PERSON\r\n} = PersonUtil;\r\n\r\nexport default Controller.extend({\r\n\r\n setField(field, value) {\r\n   assert(`Must pass a valid attribute - ${field}`, !isEmpty(field));\r\n   let model = get(this, 'model');\r\n   model.set(field, value);\r\n },\r\n\r\n actions: {\r\n   setName(name) {\r\n    this.setField(PERSON.NAME, name);\r\n   },\r\n\r\n   setAge(age) {\r\n    this.setField(PERSON.AGE, name);\r\n   }\r\n }\r\n});<\/pre>\n
By importing the person-utils<\/strong> file with the constant PERSON<\/strong> which contains keys for each attribute, and using the calls to setField with a key from that object, If I make a mistake and do:<\/p>\n
this.setField(PERSON.NEME); \/\/ This will fail because NEME does not exist<\/pre>\n
When I try\u00a0to write on\u00a0the name field, I’ll get a nice error message in the console, and even a stacktrace telling me where the problem is, like the following example:<\/p>\n
\"Wrong<\/a>
Wrong parameter<\/p><\/div>\n
The list of changes can be seen in this commit<\/a>.\u00a0This has prevented me a lot of bugs \ud83d\ude42<\/p>\n
Real-time\u00a0validation<\/h1>\n
The last step in this tutorial is having\u00a0validation as you type. In order to do that we must define a set of validations as per ember-model-validator<\/a>‘s documentation, so we change our model to have the following (age must be an integer over 18 and name a string over 4 characters long):<\/p>\n
models\/person.js\r\nimport Validator from '..\/mixins\/model-validator';\r\n\r\nconst {\r\n Model,\r\n attr\r\n} = DS;\r\n\r\nexport default Model.extend(Validator, {\r\n name: attr('string'),\r\n age: attr('number'),\r\n validations: {\r\n  name: {\r\n    presence: true,\r\n    length: {\r\n    minimum: 4\r\n   }\r\n  },\r\n  age: {\r\n   presence: true,\r\n    numericality: {\r\n     allowBlank: true,\r\n     onlyInteger: true,\r\n     greaterThanOrEqualTo: 18\r\n   }\r\n  }\r\n }<\/pre>\n
Now, we need to update our component to display errors, which per bootstrap’s documentation is adding an “has-error” class to the outer div and a span with class “help-block” to display the messages.<\/p>\n
<div class=\"form-group {{if (gt (get model (concat 'errors.' attribute '.length')) 0) 'has-error'}}\">\r\n   <label title=\"{{placeholder}}\" class='control-label' for='{{attribute}}'>\r\n   {{label}}\r\n   <\/label>\r\n   <input\r\n    value={{get model attribute}}\r\n    oninput={{action this.attrs.onUpdateValue value=\"target.value\"}}\r\n    class='form-control'\r\n    placeholder={{placeholder}}\r\n    type='text'\r\n    id={{attribute}}\r\n  >\r\n {{#each (get model (concat 'errors.' attribute)) as |error|}}\r\n   <span class=\"help-block\">{{error.message}}<\/span>\r\n {{\/each}}\r\n {{#if hasHelp}}\r\n   <span class=\"help-block\">{{helpText}}<\/span>\r\n {{\/if}}\r\n<\/div><\/pre>\n
We use the “gt” helper for ember-truth-helpers<\/a> for check if the model has errors on the attribute that is linked to this component and if so, we add the “has-error” class.<\/p>\n
With this now we are capable of showing errors, but we’re missing something that triggers the validation process. Since I want to have “real-time” validation, I’m going to use the actions\u00a0in the controller that update the model, to also validate the field which I’m typing on.<\/p>\n
controllers\/application.js\r\nvalidateField(field) {\r\n this.get('model').validate({ only: [field] });\r\n},\r\n\r\nsetField(field, value) {\r\n assert(`Must pass a valid attribute - ${field}`, !isEmpty(field));\r\n let model = get(this, 'model');\r\n model.set(field, value);\r\n this.validateField(field);\r\n},<\/pre>\n
These changes can be seen in the relevant commit<\/a>.<\/p>\n
EmberJS is a really great framework which leverages a lot of conventions (especially when coupled with the excellent ember-cli tools), by adding a few more\u00a0of our own conventions on top of this project I think we get even more value.<\/p>\n
Feel free to comment and suggest better approaches.<\/p>\n
Happy coding!<\/p>\n","protected":false},"excerpt":{"rendered":"
Today I want to talk about conventions and share something I’ve been doing as I’m working in my app that uses EmberJS\u00a0for the front-end. Warning: This post\u00a0does assume a certain degree of familiarity with\u00a0ember\/ember-cli and I assume that you have … Continue reading →<\/span><\/a><\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[48,12],"tags":[57,49],"class_list":["post-444","post","type-post","status-publish","format-standard","hentry","category-emberjs","category-web-development","tag-ember","tag-emberjs"],"_links":{"self":[{"href":"http:\/\/www.corrspt.com\/blog\/wp-json\/wp\/v2\/posts\/444","targetHints":{"allow":["GET"]}}],"collection":[{"href":"http:\/\/www.corrspt.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"http:\/\/www.corrspt.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"http:\/\/www.corrspt.com\/blog\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"http:\/\/www.corrspt.com\/blog\/wp-json\/wp\/v2\/comments?post=444"}],"version-history":[{"count":6,"href":"http:\/\/www.corrspt.com\/blog\/wp-json\/wp\/v2\/posts\/444\/revisions"}],"predecessor-version":[{"id":453,"href":"http:\/\/www.corrspt.com\/blog\/wp-json\/wp\/v2\/posts\/444\/revisions\/453"}],"wp:attachment":[{"href":"http:\/\/www.corrspt.com\/blog\/wp-json\/wp\/v2\/media?parent=444"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"http:\/\/www.corrspt.com\/blog\/wp-json\/wp\/v2\/categories?post=444"},{"taxonomy":"post_tag","embeddable":true,"href":"http:\/\/www.corrspt.com\/blog\/wp-json\/wp\/v2\/tags?post=444"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}