Web Atoms Core Samples

# Introduction ## What is web atoms? "Web Atoms" is an advanced MVVM framework to write cross platform applications in `HTML5` and `Xamarin.Forms`. Unlike other frameworks, Web Atoms lets you divide User Interface logic in strict MVVM fashion and separates View in `HTML5` and `Xaml`. Benefit of separating User interface logic in ViewModel is you can individually unit test view model to make sure your logic is consistent across platforms. Also everything is transpiled into JavaScript, your View Model and Services remain in JavaScript and in browser it works flawlessly. In Xamarin.Forms, Web Atoms package written C# helps you easily host JavaScript modules inside an application and entire User Interface is hosed via JavaScript. ### Benefits of Web Atoms with Xamarin.Forms * Small application download size * Even Xaml views are converted to JavaScript * Reuse existing NuGet components by exposing via services * Host javascript on server with instant updates to apps * No native compilation needed unless you add/modify native services written in c# * You can use Xaml binding as well as Web Atoms's JavaScript bindings ## Requirements 1. VS Code 2. TSLint extension 3. NodeJS with NPM 4. Visual Studio for Xamarin.Forms app [optional] 5. Gitlense [optional] ## UMD Loader All web atoms modules are written (transpiled) as UMD module, suitable for testing in node as well as to load in browser with AMD Loader. ```html Web Atoms Core Samples ``` > To pack and load all modules at once, please review `Packer`. ## Web Atoms Generator Each html file under `src` folder is transpiled to a TypeScript file that can contains a class derived from AtomControl. This class is a view that can be loaded with `UMD.loadView` method and it can be nested inside any other view. Similarly, each xaml file under `src` folder is transpiled to a TypeScript file, that can be used inside Xamarin.Forms application. Please refer to generator for how to setup. ## Directory structure ``` root + dist // dynamically generated by compilation, ignored in git ... + src + model // all models here + services // all services inside this folder + tests // all unit tests + view-models // all view models must be placed here + web // all html files must be placed inside web folder + xf // all xaml files must be placed inside xf folder ``` It is important that you keep files inside `web` and `xf` folder, as module loader will replace `{platform}` variable in url to corresponding folder to load views. This will make view models completely independent of platform. ## Startup 1. Install Visual Studio Code 2. Install Node with NPM 3. Start VS Code and create a new terminal 4. Run `npm install -g web-atoms-generator @web-atoms/pack` 5. Clone repository https://github.com/web-atoms/intro and rename package name in package.json, this will configure all tasks needed to run web atoms. 6. Run VS Code tasks and run `All Build` 7. This will start a small web server, you can open the displayed link in browser and all views will be displayed to test. ## AtomControl AtomControl is a UI control which contains logic to render visual elements on the screen. AtomControl has an initialization lifecycle that is common in every platform. However, rendering lifecycle differs on every platform. For example, `Xamarin.Forms` has its own render lifecycle so AtomControl only does binding to properties. In `Web Browser`, it has special lifecycle to render contents. Most of the time developer does not need to worry about it as controls are created with best performance in mind. Following properties exist on AtomControl and they are **Logically Inherited**. ### Properties * app (readonly) * parent (readonly) * data * viewModel * localViewModel ### Why data and viewModel properties are separate? In most of UI framework, view model is usually set in `data` property, which leads to problems in multiple items control such as list box etc. That requires unnecessary climbing up hierarchy and get instance of parent's data property to bind. So having separate inherited `viewModel` property makes it easier to reference viewModel associated with whole page or fragment. ### What is localViewModel ? To make reusable components easier, `localViewModel` can be used to host all logic that is only specific to the component. For example, lets say you want to create a calendar component. Local view model will contain all the logic to create list of all dates for currently displayed month and year. It will also create list of all years. All this logic will be independent of rendering logic and it can be put inside a view model which can be unit tested separately. Benefit here is, you can write a reusable view model for platform dependent component that has common logic across different platforms. So inside component, you will only write binding expressions to `localViewModel`. ## AtomViewModel `AtomViewModel` class provides necessary services and properties to write easily extensible view models. It has `init` and `dispose` methods to initialize and dispose your view model. ```typescript export default class TaskListViewModel extends AtomViewModel { // dynamically inject TaskService @Inject public taskService: TaskService; public tasks: ITaskModel[]; public async init(): Promise { this.tasks = await this.taskService.loadTasks(); } } ``` ### Watch Since view model does not have access to user interaction updates, View usually does two way binding to a property and when it is modified by user, we have to watch for changes and update view model. It is done via `@Watch` decorator. ```typescript export default class TaskListViewModel extends AtomViewModel { @Inject public taskService: TaskService; public tasks: ITaskModel[]; public search: string = null; public range = { start: 0, size: 10 }; public async init(): Promise { this.loadTasks(null); } // whenever any of search, range.start or range.size // property is modified // automatically call this method @Watch public watchSearch(): void { this.loadTasks( this.search, this.range.start, this.range.size ); } private async loadTasks( search: string, start: number, size: number ): Promise { this.tasks = await this.taskService.loadTasks(search, start, size); } } ``` By convention, `@Watch` decorated method must be prefixed with `watch` word. Even if it is named differently, `@Watch` decorator will still watch for changes. Watch decorator automatically starts watching every expression that starts with `this.`, it ignores methods and it watches only properties. For performance, this decorator does not parse javascript code, it only looks for `this.identifier.identifier...` expression and creates map of watching every single property in entire expression. > Every property accessed inside `@Watch` decorated method must be initialized to `non undefined` value. Since binding framework ignores `undefined` ### Watch property Watch can also be defined on a readonly property. ```typescript @Watch public get fullName(): string { return `${ this.model.firstName } ${ this.model.lastName }`; } ``` HTML ```html ``` XAML ```xml ``` You can bind any view property to `fullName` and it will refresh automatically whenever any changes was detected in `model.firstName` or `model.lastName`. Again, both must not initialized to `undefined`. ### Watch Async Property Watch can also be applied on a readonly property that returns a promise, but you cannot mark get method as `async` ```typescript @Watch public get messageList(): Promise { return this.messageService.getList( this.searchText, this.archived ); } ``` Now when you bind `messageList` to `items` property of `AtomItemsControl`, it will automatically refresh whenever any property mentioned in the method changes. In order to prevent frequent loading, you must provide `cancelToken` to cancel previous REST call, however, Web Atoms waits for 100 milliseconds before starting the actual call, so if the promise is refreshed quickly, previous call would not begin. Please note, AtomViewModel has a method called `newCancelToken` which will create new token and cancel the old one. ```typescript @Watch public get messageList(): Promise { return this.messageService.getList( this.searchText, this.archived, this.newCancelToken("messageList") ); } ``` ### CachedWatch decorator for async properties The only problem with `async` property is, every time you read it, it will execute remote request, so we recommend using `@CachedWatch` decorator instead of `@Watch`. It will return cached last promise unless any of referenced parameters were modified. ```typescript @CachedWatch public get messageList(): Promise { return this.messageService.getList( this.searchText, this.archived, this.newCancelToken("messageList") ); } ``` Since you cannot write `async/await` in property getter, you can create an inline function and return its results. ```typescript @CachedWatch public get messageList(): Promise { const af = async (st, a, c) => { const r = await this.messageService.getList( st, a, c ); // do something with r... return r; }; return af(this.searchText, this.archived, this.newCancelToken("messageList")); } ``` ### Validate decorator Though `@Watch` is great way to watch any property, we cannot use it for validation because as soon as page is loaded, user will be thrown with error messages. So we have created `@Validate` decorator which only returns an error message after `this.isValid` property is called. For example, ```typescript export default class SignupViewModel extends AtomViewModel { @Inject public navigationService: NavigationService; public model = { firstName: null, lastName: null }; // both validate properties will return undefined value // unless `this.isValid` is referenced. @Validate public get errorFirstName(): string { return this.model.firstName ? "" : "First name is required"; } @Validate public get errorLastName(): string { return this.model.firstName ? "" : "Last name is required"; } public signup(): Promise { // as soon as this property is called first time // validation decorator will update and error will be displayed if (!this.isValid) { await this.navigationService.alert(`Please enter required fields`); return; } } } ``` HTML ```html

...

``` XAML ```xml ... ``` In above example, when page is loaded, error spans will not display anything. Even if `firstName` and `lastName` both are empty. As soon as user clicks `Signup` button, `this.isValid` get method will start watching for changes in all `@Validate` decorator methods and user interface will start displaying error message.