Tangerine v3.0.0 Application Shell

[rjcorwin]

Code: https://github.com/Tangerine-Community/Tangerine/tree/v3.x.x/client-v3

Related User Stories

• Editor can log in #310
• Data collector can log in #298
• Editor can quickly edit forms on a weak connection #312

To do

• [x] Generate Application
  • Used Angular CLI. Best documentation for Angular CLI is on their Github Wiki https://github.com/angular/angular-cli/wiki
• [x] Wire application into build process
  • Upgraded node in Dockerfile
  • Added code with install and build instructions in Dockerfile.
• [x] Wire application into server
  • With this commit, it can be accessed at URL /client-v3/index.html when a Tangerine container is running.
• [x] Test framework and Continuous Integration
  • [x] Write up documentation on how to do TDD https://github.com/Tangerine-Community/Tangerine/blob/v3.x.x/docs/how-to-create-a-new-component.md
  • [x] Get Travis CI running
• [ ] Package upgrade monitoring via Greenskeeper
• [x] Implement a Material CSS library
  • Using the Angular Material library with this commit. Docs at https://material.angular.io/
• [x] Set up router
  • In this commit I implement an App Router, then add a router to the Binder Module, a new Binder Example Component, tie a route to that component, and then link to that Binder Example route from the App's header.
• [ ] i18n Support
  • i18n support started with the ngx-tranlate module, now efforts from the same developer is to get it into core angular libraries. New i18n library in Angular has a lot in common but one big difference is that the older library you could switch translations on the fly, in the new library you have end up with a different build folder for each translation.
  • old http://www.ngx-translate.com/
  • new https://angular.io/docs/ts/latest/cookbook/i18n.html
  • Angular Conf 2017 - Lost in Translation https://www.youtube.com/watch?v=dihyu1a2bPc&list=PLOETEcp3DkCoS_2cW205cfRGl-Xp5jw4K&index=30
• [ ] Set up PouchDB database services
  • Look into putting PouchDB in a service worker for performance (see research from Nolan Lawson)
• [ ] User login component (backend auth will depend on what user stories / architecture we decide on but we can create a component)
• [ ] About page
• [ ] Data upload
• [ ] Menu
• [ ] Write documentation

[rjcorwin]

We should take a deep look at Ionic. It seems to be very well supported soup to nuts framework using a lot of the same ingredients we are looking to brew together. The catch with Ionic might be is that the Angular team might be making tools that could soon dwarf Ionic's tooling. For example, Ionic's CLI vs the new officially supported Angular CLI.

[rjcorwin]

From Ionic's v2.0.0 announcement on Jan 25, 2017:

Ionic 2.0 final is hardly the end of Ionic’s development. Coming next we are working on new features to add proper desktop and electron support, something we’ve dipped our toes into in the past but will be making a bigger priority going forward. Similarly, we will be ramping up our Progressive Web App efforts to enable Ionic developers to deploy the same app with the same code across the app stores and the mobile web to take advantage of those diverse channels.

An Angular server is coming in Angular 4. This is pushing the best practice of having your frontend served on a frontend server with a separate backend service. It puts the pressure on us to write separate Dockerfile's for frontend and backend while strapping it together with a Docker Compose file. The original motivation was to improve build times.

[jwaldermo]

Links to good sites for this discussion.docx

The above document has some great links for this discussion.

[rjcorwin]

Ionic brings a lot to the table. Here's a couple notes thinking about those things and comparing them to other things.

• Ionic Components vs Material Components
  • Which one will be better maintained?
  • Which one will have a larger install base?
  • Ionic Components will style according to the platform (iOS/Android). Do we care?
  • Which one do we think is best for our users on mobile?
  • Which one do we think is best for our users on desktop?
• Ionic Pages vs Angular Router
  • An Ionic Page is a decorated Angular Component where the decorator lets you define the Ionic Router path. That's a good pattern to distinguish page components from widget components, yet it could also be convention we follow with Angular Router by prefixing page components with page-.
  • Not using Angular Router, we might miss out on some innovation like lazy loading.
• Ionic CLI vs Angular CLI
  • Can Ionic CLI and Angular CLI play well together so we can still use Angular CLI generators?
  • Will the upgrade process be any more painful with either CLI?
• Ionic Build vs Cordova + Electron + NG CLI build
  • How much time does Ionic Build save us over setting up Cordova?
• Ionic API vs Cordova API
  • Ionic API is a wrapper around Cordova API to make it more NG-ish
  • Is it hard to use ionic-native (successor of ngCordova) without ionic?
• Releasing to app store... Does Ionic help? Their paid services?

[rjcorwin]

I been thinking about what the Unique Selling Proposition (USP) of Ionic is. Last year I think it went as follows...

1. Angular doesn't have a standard way of compiling the application and so everyone uses starter projects. Ionic is the most extensive Angular starter project for mobile, it even builds to Android/iOS apps by configuring Cordova for you.
2. Ionic Components are the most feature complete set of Angular Components for Mobile. Especially if your requirement is that the components are themed to look native according to the target platform you build for.

Today I have have reservations about those USPs.

On the first USP, Angular now has supported Angular CLI which provides the best practices for starting an Angular Application, building it, mind blowing generators, test harness, and amazing upgrade path tools. Going with Ionic means we don't get to use Angular CLI (for now, maybe in the future). Ionic has their own opinions about how an app should be structured, for example they don't use the Angular Router. The one thing that Ionic CLI has over Angular CLI is that Ionic CLI can build to APK out of the box. Building to APK after a Angular CLI build requires setting up Cordova yourself.

On the second USP, Ionic Components are cool, but Angular Material is equally if not even more cool than Ionic Components (https://material.angularjs.org/). There seems to be a real solid commitment to Angular Material, some great best practices (like using wrapper elements over native tags), and it works great on both Desktop format, Tablet, and mobile. While Ionic Components are now also targeting the Desktop format, I'm not sure they are going to as good of a job of making a UI library that work well on both Mobile and Desktop as the Google has done with Material.

[rjcorwin]

A note on installing Material, angular-cli has its own doc page for installing Material. The thing I think that page does differently than the standard Material docs is that it imports all of the Material components with one require. That's probably just going to result in a dist size that is much larger than necessary.

• https://github.com/angular/angular-cli/wiki/stories-include-angular-material
• https://material.angular.io/guide/getting-started

[rjcorwin]

Angular Material has been added to our client-v3 codebase with this commit https://github.com/Tangerine-Community/Tangerine/commit/d0d2a1a30c4f87ad71521e1eb40fe831d55afb88

[rjcorwin]

Researching databases and auth...

• Creating a Multiple User App with Ionic 2, PouchDB & CouchDB
  • The Todo Provider (aka Service) on init creates a PouchDB database, turns on continuous sync. Has a logout method that destroys the database. Interesting how it is used just a temporary cache.
  • The LoginPage Component actually does HTTP requests to log in the user. I'm this results in a session managed in a cookie. this.http.post('http://localhost:3000/auth/login'...
  • The session management on the server side is NOT COUCHDB in this example. It is a Node.js library called superlogin and it uses CouchDB as a database purely for storage where it manages its own way of doing Sessions.
• To do: What are best practices for passing configuration like Server URL to Service Providers? This configuration probably comes from Application Environments during the build process. See https://github.com/angular/angular-cli/wiki/stories-application-environments
• To do: Create a CouchDB Service for Angular which can be used as a database provider or can just be used for authentication.
• To do: Create a PouchDB Service for Angular example which is really simple.

[rjcorwin]

Modular Router is now in client-v3.

[rjcorwin]

Updated this ticket's summary with the following and some more things to do.

Code: https://github.com/Tangerine-Community/Tangerine/tree/v3.x.x/client-v3

• [x] Generate Application
• [x] Wire application into build process
• [x] Wire application into server
• [x] Implement a Material CSS library
• [x] Set up router

[rjcorwin]

For reference, the [i18n] plans for v4 and beyond issue. Olivier mentions "looking at possible solutions, using an external file is one of them." Which would I think make it easier for us to serve the use case of needing to update translations quickly without having to wait for another release of Tangerine.

[evansdianga]

• How do we do Lazy Loading of Dynamic Translation tables

• Caching: Reducing Load Times by caching the translation files. Could this help when using JIT?

• Embedding in cordova? When we use AOT, will we Create a separate app for each language? Or include all languages? Leads to bloating of app. Github issue.

• Separate app for each language leads to UX issues- no dynamic language change, requires complete site reload.

• JIT loads translations at bootstrap which is not the same as switching at runtime. Switching languages will mean re-bootstrapping the the app. We can save the user's progress in local storage perhaps so as not to lose changes made by the user. Actually, we could do progressive saving of the user's state as the user makes changes across the app and not only to deal with i18n.

• The UI language ideally should'nt be a compiler issue. The text should be able to be loaded at runtime through a module library that can be loaded and used like any other. This will be changed in the future though there is no concrete timeline

• Breaking change planned around autogeneration of IDs- the method will change and the IDs will ot match anymore. There will be a cli migration tool to help update translation files.

• For large apps, having a single translation file for each language could affect load times. Probably a good idea to break translation file into smaller files

• ng2-translate will be deprecated once i18n in implementation reaches feature parity. It is a minimal way to translate app. The angular i18n is the one suited for enterprise

• Translation for messages embedded in code? e.g throw new Error('Message that should be translated') One approach is this. This only works for JIT.

• ngx-translate has poor performance when compared to using Angular's i18n as i18n doesn't use bindings. As the number of translations multiply, the more the perfomance gain

• You need to pay attention on the location of your i18n directive, it should be placed directly on the element that contains the text, not on any other siblings. example

• Library support may be included in v5. Release date is 2017‑09‑18. Link

• using user agent is tricky e.g. in canada or in situations where the user understands a different language

• An example implementation of the translation in production app is here

• Demo for showing the use of one app per language.

• Other Links

  • https://github.com/angular/angular/issues/16477
  • https://github.com/angular/angular/issues/11405
  • Design doc
  • https://github.com/IdeaBlade/angular.io/blob/b3e44c88dd8cd6b37da64e56d275e058314922fd/public/docs/ts/latest/guide/i18n.jade#L67
  • https://github.com/StephenFluin/i18n-sample
  • http://rolandoldengarm.com/index.php/2017/02/01/how-we-have-made-our-angular-2-website-multi-language/
  • https://github.com/actimeo/simmage-ui

[rjcorwin]

My current directions for starting Test Driven Development on a Component by Component basis.

1. Generate module
2. Generate component
3. Modify spec file to import Component's module and not declare the component.
4. Modify the component's tests from using it function to using fit function.
5. Run ng test.
6. Click DEBUG.
7. Open developer tools.
8. Start development of that component.

Also see https://aio-staging.firebaseapp.com/guide/testing#import-the-feature-module for examples of things like fixture.debugElement.query(By.css('input')).nativeElement.

[rjcorwin]

Here's an example of a more advanced Component Spec where we feed it data and then check to make sure that the DOM of the component is as expected https://github.com/Tangerine-Community/Tangerine/blob/v3.x.x--tangerine-forms/client-v3/src/app/tangerine-forms/tangerine-page/tangerine-page.component.spec.ts

[rjcorwin]

@evansdianga The test spec for Tangerine Page Component now simulates adding input to a form, submitting it, and then makes sure that corresponding @Output matches what we would expect. There is a click function used that is taken directly from the docs and requires passing in the "nativeElement" I think. We're getting closer to the level of testing complexity we want but still have things to learn from https://aio-staging.firebaseapp.com/guide/testing.

[evansdianga]

@rjsteinert Angular documentation currently points towards using SystemJS as a module loader. This is especially true for the documentation on i18n. Our configuration uses Webpack. Digging through the various configuration options, docs for Webpack is missing not only for the i18n but for most parts of Angular. Check this open issue for details. https://github.com/angular/angular.io/issues/3163 Another option with Webpack is to use this method. https://medium.com/@feloy/deploying-an-i18n-angular-app-with-angular-cli-fc788f17e358 Integrating this configuration into our app may solve the issue. Any thoughts?

[rjcorwin]

@evansdianga That blog post looks helpful. To supplement that post, the angular-cli wiki might have more up to date information. Keeping an eye on this search result might help https://github.com/angular/angular-cli/search?q=i18n&type=Wikis&utf8=%E2%9C%93

The pages relevant to use I think are these.

• https://github.com/angular/angular-cli/wiki/stories-internationalization
• https://github.com/angular/angular-cli/wiki/build
• https://github.com/angular/angular-cli/wiki/serve
• https://github.com/angular/angular-cli/wiki/xi18n

[rjcorwin]

I added documentation on how to do TDD with Angular Units Tests when creating Components https://github.com/Tangerine-Community/Tangerine/blob/v3.x.x/docs/how-to-create-a-new-component.md.

I also got Travis CI working correctly thanks to @chrisekelley https://travis-ci.org/Tangerine-Community/Tangerine/builds/240416270

I also started setting up Greenskeeper.io so it will send us pull requests when we have a package that needs updating. I integrated it with the Tangerine repository but I can't seem to find a way to show that the package.json it needs to care about lives at client-v3/package.json.