DEV Community: Web Atoms

Introducing new JavaScript Engine YantraJS for DotNet

Akash Kava — Wed, 27 Oct 2021 08:46:31 +0000

We are happy to announce a brand new Open Source JavaScript engine completely written in C# for .NET.

Managed JavaScript Runtime

YantraJS is a JavaScript runtime written in .NET Standard. Yantra has two components, Expression Compiler and JavaScript engine.

It is written in .NET standard, so it runs everywhere except iOS which enforces JIT restrictions. However, with help of an interpreter you can still use it on iOS.

Why did we build it?

We wanted a JavaScript engine with complete support of ES6, including generators and async/await. And we want to officially support as a commercial product. YantraJS is open source.

License

Apache 2.0 License

For more details, please visit YantraJS Website

Features

Compiles JavaScript to .Net Assembly
Strict Mode Only JavaScript*
Arrow functions
Classes
Enhanced object literals
Template strings and tagged templates
Destructuring
let const
Map, Set, WeakMap, WeakSet
Symbols
Subclassable built-ins
Binary and Octal literals
Module support
Null coalesce
Optional property chain identifier?.[], identifier?.(, identifier?.identifier
Rest, Default and Spread Parameters
Generators, iterators, for..of
Async/Await
Optional parameters
Many ES5 + ES6 features
CommonJS Module Support
Easily marshal CLR Object to JavaScript and other way around
CSX Module support

* Most JavaScript today is available in strict mode, we do not feel any need to support non strict mode as modules are strict by default.

Roadmap

Support for V8 Debugger Protocol
Increase ECMAScript conformance
Faster IL Serialization
Faster Debugging
Support for module pollyfills (ability to redirect default node modules, to support dual platform)

ECMAScript Conformance

Currently we are seeing more than 70% conformance to ECMAScript, reaching 100% is little out of scope as it is very huge and Yantra is only one year old. We are focusing on supporting most used JavaScript patterns instead of targeting 100% compliance due to limited development bandwidth.

Expression Compiler

YantraJS is built on custom Expression Compiler, which allows us to create expressions similar to that of Linq Expressions. Expression Compiler has several methods to generate IL, you can compile expression to MethodBuilder. Since there is no support for Linq to compile expressions to MethodBuilder, Yantra Expression Compiler was written from ground up to support saving IL to various ways.

Engine Types

JSContext - plain JavaScript context
JSModuleContext - context with modules and clr support
YantraJSContext - context with modules, clr and CSX Module support

How to use?

Simple Execution

var context = new JSContext();

// create global function
context["add"] = new JSFunction((in Arguments a) => {
    return new JSNumber(
         (a[0]?.IntValue ?? 0) + (a[1]?.IntValue ?? 0)
    );
});

var result = context.FastEval("add(4,5)", "script.js");

Wrap CLR Object

Custom CLR types can be wrapped in ClrProxy which will allow you to call any methods directly from JavaScript.

context["createUri"] = context.CreateFunction((in Arguments a) => {
    var uri = new Uri(a[0]?.ToString() 
          ?? throw context.NewReferenceError(
                   "At least one parameter expected");
    return new ClrProxy(uri);
}, "add");
var result = context.FastEval(
      "var uri = createUri('https://yantrajs.com'); uri.host");
Console.WriteLine(result);

For more information on how to use various types, please visit YantraJS Examples

Alternative to Razor View in ASP.NET Core

We have created our website using JavaScript as view instead of Razor view, though it started as a simple application, but we realized that by using JavaScript as view, we can easily plugin Server Side Rendering and improve page delivery speed. However, using traditional JSDom is not yet supported due to very heavy dependency on various built in node modules. But you can easily create a wrapper with mocks to render content of your React/Angular components on server easily with YantraJS. Check out source code for our website at Github Repository for YantraJS Website

Originally Posted at Introducing YantraJS - Web Atoms Blog

Web Atoms for Xamarin Forms vs React Native

Akash Kava — Thu, 18 Feb 2021 04:56:11 +0000

Xamarin Forms

Xamarin Forms provides platform independent UI framework, however the code is natively compiled, it gives you speed but deployment is lengthy process. Xamarin Forms makes it easier to create and deploy custom UI components using Custom Renderers.

React Native

React Native on other hand provides quick updates but to achieve native performance, and for custom UI components, you need to write code in different platforms in different languages.

Web Atoms

With Web Atoms, we decided to bring all features of React Native in Xamarin Forms to get the best of both.

Native Component

We are always in need to create native components when framework components don't provide exact features we need. In case of React Native, we are left to create new components in Java/Kotlin for Android and in Swift for iOS. In Xamarin Forms, we can create custom components by combining existing platform neutral controls or write custom renderers in different platform but all in C#.

In Web Atoms, you can create custom controls using JavaScript and in C#, (Writing in C# will require you to redeploy application in AppStore).

JSX + JavaScript Support

Xamarin Forms does not have any support for JSX + JavaScript, React Native and Web Atoms, both provides support for JSX.

Support for NuGet Packages

In Xamarin Forms you can reuse all existing NuGet Packages. There is no support for NuGet packages in React Native as it is not built on .NET framework.

In Web Atoms, you can reuse all existing NuGet Packages.

Support for NPM Packages

Since there is no support for JavaScript, using NPM package is not possible. In React Native, you can use most of NPM Packages.

In Web Atoms, you can use most of NPM Packages as well.

Live Reload in Production

Application deployment is becoming lengthy day by day, the queue to publish new update is increasing and also subject to approval.

Live Reload allows user to refresh the app version without having to download the app from the respective store.

In Xamarin Forms, it is not possible to provide live reload as entire code is natively compiled and shipped via store.

In React Native and Web Atoms for Xamarin Forms, you can provide live reload in production.

Binding and MVVM Pattern

Xamarin Forms has excellent One, Two way binding and MVVM Pattern support.

React Native is purely functional and there are no inbuilt binding/MVVM concepts.

In Web Atoms, we have created Binding and MVVM support to reduce learning time, you can easily translate Xaml + C# to JSX + JavaScript with exact similar concepts.

Dependency Injection

Xamarin Forms has simple dependency injection and Prism provides advanced dependency injection.

React Native does not have dependency injection, but there are other frameworks in NPM in which you can achieve same.

Web Atoms provides Prism kind of Dependency Injection in JavaScript with decorators.

Reuse Existing C# Code

If you have your backend and most of your front end application already has C# code, reusing them in Xamarin Forms is very easy.

Using existing C# code in React Native is not easy, either you will have to rewrite it in JavaScript or provide server side rest proxy.

Using existing C# code in Web Atoms is as easy as using in Xamarin Forms. In fact, you can use Web Atoms in existing app without having to rewrite most of its parts.

Side by Side versioning

Since Xamarin Forms apps are compiled natively, you cannot allow users to switch the version, this is very useful in beta test, early adopter tests. For admin and investigation purpose.

In React Native, apps are mostly in JavaScript, it is possible to load JavaScript from server and it is possible to switch to different version for various investigation/debugging purpose.

In Web Atoms for Xamarin Forms, apps are mostly in JavaScript and they can be loaded from server, it is possible to use different versions.

Feature	Xamarin Forms	React Native	Web Atoms for Xamarin Forms
Native Component Implementation Languages	C#	JavaScript, Swift, Java	JavaScript, C#
JSX + JavaScript Support	No	Yes	Yes
Support for NuGet Packages	Yes	No	Yes
Support for NPM Packages	No	Yes	Yes
Live Reload in Production	No	Yes	Yes
Binding and MVVM Pattern	Yes	No	Yes
Dependency Injection	Requires Prism	Requires other packages	Inbuilt
Reuse Existing C# Code, if you already have various application logic already available in C#	Yes	No	Yes
Side by side versioning (Use different versions of Application without uninstall/reinstall)	No	Possible	Yes
Exception Line Numbers in Production	No	Available	Available

Live & Hot Reload/Code Push Xamarin.Forms Apps with Web Atoms

Akash Kava — Thu, 10 Sep 2020 09:52:00 +0000

History & Motivation

We have been using Xamarin.Forms for a couple of years, but business augmentation demanded more frequent app updates. We were assessing React native as an alternative, but the learning curve was very steep and our developers are considerably more familiar with MVVM approach up against the MVC method. Thus three years back, we ran a pilot by writing Xamarin Forms in JavaScript, it was relatively easy to fabricate and prototype swiftly. We now have three apps that are partly c# and partly JavaScript, as all-new screens are shipped through JSX

Native Limitations

Native code is fast, but for most business application needs, this performance vs the time need to build/deploy and maintain release cycle is extremely costly.
No side by side versioning, once the bug is found, fix is not available instantly.

Xamarin.Forms Limitations

Xamarin has an advantage of writing app in one language c# along with Powerful set of NuGet Libraries. 2 BUT, yes the big But is, the c# code is translated into native, so it requires same time to build and deploy the app.
Unfortunately, Android builds are still relatively slow.
Developing and debugging is painfully slow.

Deployment Limitations

iOS App approvals take longer, bugs do go out on production as we never have million dollar app budgets to fix all the bugs before rolling out.
There is no quick way to fix bug, a new upgrade reaches all your customers after couple of days. Most of the time, users don't have auto update enabled, they don't download new version, they are not connected to high speed internet and above all, all the major heavy updates in queue will delay your update.

React Native Limitations

React native was great alternative to bypass all slowness, but for C# developers, it has many roadblocks.
C# developers are more familiar with MVVM pattern, lack of MVVM pattern on React increases learning time.
Rewriting C# components and services on React will defy the purpose of making life easier.
Native integration in C++/Swift/Java is again problem for developers who have years of experience in C#.

Hot/Live reloading with Web Atoms

Language/Platform

You can use JavaScript + C#, JavaScript for your business pages/UI and C# only for high speed computation and other native integrations.
NuGet has probably million packages that you can easily use in Xamarin Forms. And all that can be used in JavaScript.
Web Atoms is designed by keeping MVVM in mind, so writing JSX with MVVM is extremely easy. For C# developers it only feels different in syntax, rest of things remain as it is.

Reuse

Since you can reuse all of your existing Xamarin.Forms code, time to shift to Web Atoms is really negligible.
You don't have to rewrite everything.
You can simply add nearly 20 to 30 lines of code to start using JSX instead of Xaml in Xamarin.Forms project.
You can reuse all your existing C# components in JavaScript.
You can create reusable components in JavaScript and use them in your existing components of C#.

Side by side versioning

Since web atoms javascript packages are deployed simply as nuget packages, you can easily create some strategy to upgrade/downgrade versions on your web server.
You can easily distribute private beta and offer different version to different customers to debug or quickly patch few bugs.

Advantages of Web Atoms over React Native and Native Script

Both, React native and Native script offers JavaScript , but native integration and high performing code needs to be written in Swift/Java/C++. With Web Atoms, you can easily write platform independent in C# and use it in Web Atoms.
You can continue to use your existing code/libraries written in C# easily without any hassle.
Debugging Xamarin apps is easy compared to native platforms.
Debugging JavaScript in Android is done via Chrome debugger and in iOS with Safari development tools.
JSX syntax in Web Atoms is exactly same as Xaml, you can perform all kinds of Bindings in JSX in exactly same fashion as in Xaml.

How does it work?

Your existing Xamarin Forms app is loaded natively in exactly same manner.
As soon as the app is launched, a new JavaScript bridge (V8 in Android and JavaScriptCore in iOS) is created.
Web Atoms module loader loads your scripts and provides integration between c# and your code.
Once the bridge is loaded, you can refresh the bridge inside the app via some code, or some trigger, without reloading entire app, the bridge loads new version of application JavaScript. This happens usually within 1-2 seconds.

Once built, only JavaScript is reloaded

You don't need to publish your app on app store unless you make any changes in the C# code.
You don't even need to close/restart the app to see new changes.
You can publish javascripts on the Wifi and you can also debug your app over wifi.
JavaScript reloading is little slow compared to native code, but for prototyping, for business applications, the time delay in JavaScript code is negligible.

Introducing Xamarin.Forms Fiddle

Akash Kava — Wed, 08 Jul 2020 15:29:06 +0000

Xamarin.Forms app in JavaScript

With Web Atoms, you can create Xamarin.Forms apps in JavaScript. You can write JSX instead of Xaml and that gives you powerful multibinding and allows you to push code on production.

Side by side versioning
Divide large app in multiple javascript npm packages
No need to create multiple apps and integrate all of them
Debug JavaScript in Chrome using V8 Inspector protocol for Android
Debug JavaScript in Safari debugger for iOS

Download the App

Trying and playing with Xamarin.Forms in JavaScript is one step process, download the app.

Open Demo

Shapes

https://www.webatoms.in/play/demo/shapes/1
https://www.webatoms.in/play/demo/rating/4

Explore new feature "Shapes" of Xamarin.Forms 4.7.

Master Detail

https://www.webatoms.in/play/demo/master-detail

Application with drawer and multiple pages, using navigation service to open pages, retrieve result and load unpacked pages.

List View

https://www.webatoms.in/play/demo/list

Explore list view with Cell bindings. Using two way binding to update the selection.

Form

https://www.webatoms.in/play/demo/form/3

Explore validation sample with simple form.

Tabbed Page

https://www.webatoms.in/play/demo/tabbed-page/3

Explore tabbed pages.

Scan QR Code

Console Logging

You can see console of your device and you can log errors/warnings in the console in your code.

ViewModel Decorators in Web Atoms for Xamarin.Forms

Akash Kava — Sun, 14 Jun 2020 09:03:07 +0000

Rich View Model

Web Atoms provides feature rich View Model to write common logic with simple configuration.

Watch Decorator

Watching property is super easy with Web Atoms. You can simply create a readonly accessor and mark it is @Watch.

export default class EditorViewModel extends AtomViewModel {

    public model: CustomerModel = {
        firstName: "",
        lastName: ""
    };

    @Watch
    public get fullName() {
        const firstName = this.model.firstName;
        const lastName = this.model.lastName;
        return firstName + " " + lastName;
    }
}

Usage

    this.render(<WA.AtomForm>
        <WA.AtomField>
            <XF.Entry text={Bind.twoWays(() =>
                this.viewModel.model.firstName)}>
        </WA.AtomField>
        <WA.AtomField>
            <XF.Entry text={Bind.twoWays(() =>
                this.viewModel.model.lastName)}>
        </WA.AtomField>
        <WA.AtomField>
            <XF.Label text={Bind.oneWay(() => this.viewModel.fullName)}>
        </WA.AtomField>
    </WA.AtomForm>);

Validate Decorator

Validate is special type of watch, which gets activate only if validation was requested.

export default class SignupViewModel extends AtomViewModel {
    public model: CustomerModel = {
        firstName: "",
        lastName: "",
        emailAddress: ""
    };

    @Validate
    public get errorFirstName() {
        if (!this.model.firstName) {
            return "First name is required";
        }
        return "";
    }

    @Validate
    public get errorEmailAddress() {
        const email = this.model.emailAddress;
        if (!email) {
            return "Email is required"; 
        }
        if (!emailRegEx.test(email)) {
            return "Invalid email";
        }
        return "";
    }

    @Action({ validate: true })
    public async actionSignup() {
        // only when this was invoked
        // in UI, validation occurs
    }
}

export default class Signup extends AtomXFContentPage {

    public viewModel: SignupViewModel;

    public create() {

        this.viewModel = this.resolve(SignupViewModel);

        this.render(<WA.AtomForm>
            <WA.AtomField>
                <XF.Entry text={Bind.twoWays(() =>
                    this.viewModel.model.firstName)}>
            </WA.AtomField>
            <WA.AtomField>
                <XF.Entry text={Bind.twoWays(() =>
                    this.viewModel.model.emailAddress)}>
            </WA.AtomField>
            <WA.AtomField>
                <XF.Button
                    command={Bind.event(() => this.viewModel.actionSignup())}
                    text="Signup">
            </WA.AtomField>
        </WA.AtomForm>);
    }
}

Load Decorator

Load decorator makes loading of async data very easy. Let's assume that we want to load countries and then selected state. It reports exceptions and cancels previous
operation.

export default class SignupViewModel extends AtomViewModel {

    /** This gets called on initialization */
    @Load({ init: true })
    public async loadCountries() {
        this.countries = 
            await this.restService.getCountries();
        this.selectedCountry = this.countries
            .find((x) => x.value === "IN").value;
    }

    /** This gets called when `this.selectedCountry` changes */
    @Load({ watch: true /* watch */ })
    public async loadStates(ct: CancelToken) {
        const country = this.selectedCountry;
        // pass cancel token
        // to automatically cancel previous
        // incomplete request
        this.states = 
            await this.restService.getStates(country, ct);
    }

}

Debouncing


export default class SignupViewModel extends AtomViewModel {

    @Load({
        /** watch for changes */
        watch: true,
        /** wait as user might still be typing */
        watchDelayInMS: 500
    })
    public async loadCities(ct: CancelToken) {
        const search = this.search;

        /** cancellation of previous request is tracked here */
        this.cities = await
            this.restService.searchCities(search, ct);
    }

}

Action

@Action decorator can be applied on a method which will automatically display an alert if there was any error. And it will invoke validation before executing the method. Display an success alert after completion if configured. You can also configure confirm to request confirmation (e.g. for delete operations).

export default class SignupViewModel extends AtomViewModel {

    /** This decorator will handle validation, display error
     * and will display an alert for success
     */
    @Action({
        validate: true,
        success: "Signup successful",
        confirm: false,
    })
    public async signup() {
        ....
    }

}

    <XF.Button
        command={Bind.event((e) =>
            this.viewModel.signup())}
        text="Signup"
        />

Embed V8 JavaScript Engine in Xamarin.Android

Akash Kava — Sat, 25 Apr 2020 06:46:49 +0000

Isn't there any existing JavaScript engine for Xamarin.Android?

Well, there is LiquidCore project, which has Java bindings for V8, you can use it to embed V8 in Xamarin.Android by natively embedding Android Native Project (AAR) files of LiquidCore project.

Also there are other implementations such as DuckTape, JavaScriptCore etc.

The problem with all of them is, your C# code actually calls (Marshals all parameters) Java code which in turn calls (Marshals all parameters) again to V8.

   // Marshall all parameters 
   CLR Code -> Java Code -> V8 Native

   // Marshal result
   CLR Code <- Java Code <- V8 Native

This in turn slows your execution if your code frequently access C# code.

So I decided to remove "Java" bridge to call V8.

V8 is Embedded as a Native Library

Since V8 is embedded as native library, calls from C# does not go through Java bride.

   CLR Code -> V8 Native
   CLR Code <- V8 Native

V8 Inspector Protocol Support

Currently LiquidCore does not support Inspector protocol, that means you cannot debug your JavaScript. And other libraries such as DuckTape etc does not have any support for debugging at all.

Xamarin.Android.V8 (Name is subjected to change in future)

web-atoms / xamarin-v8

V8 Bindings for Xamarin for Android

Xamarin V8 Bindings

V8 Bindings for Xamarin for Android

Though V8 is very heavy, you can try YantraJS, very light weight JavaScript engine written in C#.

NuGet

<PackageReference Include="Xamarin.Android.V8" Version="1.4.79" />

Inspector Protocol Port

Visual Studio > Tools > Android > Android Adb Command Prompt

adb forward tcp:9222 tcp:9222

If you want to change the default 9222 port, you can specify in the parameters.

Create Context

using Xamarin.Android.V8;

using(var context = new JSContext( /*Enable Debugging*/ true)) {

  // you can connect to dev tools by visiting url
  // devtools://devtools/bundled/inspector.html?experiments=true&v8only=true&ws=127.0.0.1:9222/backend
  
  

}

Create New Global Function

context["printf"] = context.CreateFunction(0, (c, a) => {
  // first parameter is context isself
  // second parameter is an array as IJSValue
  System.

…

View on GitHub

NuGet Package

NuGet Package is available with ID Xamarin.Android.V8

Inspector Protocol Port

To open Inspector protocol port from your device, you have to click Visual Studio > Tools > Android > Android Adb Command Prompt. Then type,

    adb forward tcp:9222 tcp:9222

Create Context

using(var context = new JSContext( /*Enable Debugging*/ true)) {

  // you can connect to dev tools by visiting url
  // devtools://devtools/bundled/inspector.html?experiments=true&v8only=true&ws=127.0.0.1:9222/backend

    context.Evaluate("console.log('I am ready')", "vm");

}

Now you have full debugging support in the given link

devtools://devtools/bundled/inspector.html?experiments=true&v8only=true&ws=127.0.0.1:9222/backend

Create New Global Function

Context itself is a global object. So you can store/retrive values on it.

context["printf"] = context.CreateFunction(0, (c, a) => {
  // first parameter is context isself
  // second parameter is an array as IJSValue
  System.Diagnostics.Debug.WriteLine(a[0].ToString());
  return c.Undefined;
});

context.Evaluate("  printf('This is from JS Coe'); ", "vm");

// this works as well
context.Evaluate("  global.printf('This is from JS Coe'); ", "vm");

Evaluate Script with Location

// script location is useful for debugging
context.Evaluate(scriptText, scriptLocation);

Navigate Objects

Each JavaScript object is exposed to CLR as IJSValue, you can access properties and methods on this object directly.

   // Object.create() JavaScript Equivalent in c#
   var obj = context["Object"].InvokeMethod("create");


   var obj = context.CreateObject();
   obj["name"] = context.CreateString("Akash");

   // Object.keys(obj) JavaScript Equivalent in c#
   var keys = context["Object"].InvokeMethod("keys", obj);

   for(var i = 0; i < keys.Length; i++) {
       var key = keys[i].ToString();
       var value = obj[key].ToString();

       //... you have key and value here
   }

Serialize C# Object

When you use method context.Convert method to automatically create native JS values from native types, it will only wrap C# custom object, you cannot call any method or access property from JavaScript on wrapped object. This is done to improve performance. So when you pass C# objects in and out, engine will not create methods and properties on them.

In order to access methods and properties of C# object, you have to serialize them.

  // you can access all properties, no methods
   var jsDictObject = context.Serialize( customClrObject , SerializationMode.Copy);

   // you can access all properties and invoke method as well
   var jsClrObject = context.Serialize( customClrObject , SerializationMode.Reference);

Serialization Modes

Copy

This method will create a deep copy of CLR Object as dictionary which you can easily access inside JavaScript code. This method will fail if there are self referencing objects in the object graph. This limitation may be removed in future, but right now it will throw an exception.

This method is also very slow as deep copy operation will take more time.

Deserialization will also be slow as it will completely construct new object with all properties.

Reference

Keeps reference along with serialization, every property is serialized as getter/setter, upon deserialization, same object will be returned.

This method is useful for self referencing objects, but this may cause memory leak if you keep reference in JavaScript and JavaScript garbage collector fails to dispose object.

Deserialization is faster as it simply returns referenced object.

WeakReference

Same as Reference but it only keeps weak reference, you will get object disposed if you try to access object in JavaScript and it is disposed in CLR. CLR is very aggressive while disposing objects, so this may not work if you do not keep reference in CLR. This is also recommended method as it will avoid memory leaks.

Wrap

This is default serialization method for any object. Object will simply be wrapped and no methods/properties are exposed.

Thread Safety

This library is not thread safe and it is recommended that you use JSContext on the same thread as you created on. Most likely it is better to call in UI Thread.

This is done to avoid unnecessary locking when you don't need them. You can achieve locking in the CLR when you need them.

License

MIT License

Big Thanks to

A huge thanks to following github repo to help making this project a reality.

Different types of bindings in Web Atoms for Xamarin.Forms

Akash Kava — Sat, 04 Apr 2020 05:57:38 +0000

Types of Bindings

Web Atoms offers two types of data bindings. JavaScript Data Binding and CLR Dta Binding. CLR Data Binding refers to existing Binding mechanisms offered in Xamarin/WPF in Xaml.

JavaScript Data Binding

Web Atoms framework provides Binding of JavaScript objects within JavaScript engine. This form of binding allows more features over CLR Data Binding. Data Binding in JavaScript allows you to rewrite custom expressions in JavaScript and you don't have to recompile your native app.

Pros of JavaScript Data Binding

It can contain custom TypeScript expression
You can write unit tests in JavaScript to cover conversions
Smaller app size as all the code can live on server
String resources can live on the server leading to smaller app size
You can unit test your bindings with string resources in TypeScript

Cons of JavaScript Data Binding

You cannot use CLR Value Converters
You cannot use it in Control Templates

One Time JavaScript Binding

One time binding offers expression evaluation at later stage. As component is being built, not all properties are set at time of creation, order of property initialization is completely random.

   <XF.Label
       text={Bind.oneTime( () => this.viewModel.label )}
       />

You can also do the same by typing,

   <XF.Label
       text={this.viewModel.label}
       />

but it may fail as viewModel or label may not have been initialized.

One Way JavaScript Binding

One way binding offers expression evaluation whenever any of referenced properties are updated.

   <XF.Label
       text={Bind.oneWay(
           () => `${this.viewModel.firstName} ${this.viewModel.lastName}`)}
       />

The above example offers simple concatenation of first name and last name whenever any of them is modified. Doing same in C# apart from simple string operations usually requires separate converter and binding expressions becomes very complex.

Data Binding in items scope

   <XF.CollectionView>
       <XF.CollectionView.itemTemplate>
          <XF.DataTemplate>
              <XF.Label
                  backgroundColor={Bind.oneWay(
                    (x) => this.selectedItem == x.data
                           ? Colors.lightGreen
                           : Colors.white
                    )}
                  text={Bind.oneWay((x) => x.data.label)}
                  />
          </XF.DataTemplate>
       </XF.CollectionView.itemTemplate>
   </XF.CollectionView>

In above example, every item of CollectionView receives an extra parameter x that refers to UI Element in collection. And data property of Element is the item in collection. Notice, that this expression can watch for changes in this.selectedItem as well as x.data (as x.data changes while item template is reused). This successfully changes color when selected item is updated.

So Data Binding can easily works at nested scopes without having to create complex named relations which are required in CLR Data Binding.

So OneWay binding will watch for changes in any of this.*.*.... expression and expression of type x.*.*.... where x is first parameter of Bind.oneWay method.

Intellisense in `Bind.oneWay`

TypeScript with VS Code offers excellent intellisense, we can use it by declaring some interfaces.


   const CustomerBinding = Bind.withData<ICustomer>;

   <XF.CollectionView>
       <XF.CollectionView.itemTemplate>
          <XF.DataTemplate>
              <XF.Label
                  backgroundColor={CustomerBinding.oneWay(
                    (x) => this.selectedItem == x.data
                           ? Colors.lightGreen
                           : Colors.white
                    )}
                  text={CustomerBinding.oneWay((x) => /* error */x.data.label)}
                  />
          </XF.DataTemplate>
       </XF.CollectionView.itemTemplate>
   </XF.CollectionView>

In above example, we get an error that there is no label on ICustomer. While typing . after data will immediately display list of properties/fields that exists inside interface ICustomer.

Two Way JavaScript Binding

Web Atoms offers two way data binding same as in CLR.

   <XF.SearchBar
       text={Bind.twoWays(() => this.viewModel.search)}
       />

CLR Data Binding

Though JavaScript Data Binding is sufficient in many ways, it lacks ability to provide control over Control Templates.

You can write ControlTemplate in TSX, though you can use some JavaScript bindings but when you want to bind properties of Template Owner, you cannot do that with JavaScript.

But, You can create CLR DataBinding object, and it will work exactly in same way. Let's look at the ControlTemplate of AtomForm which allows you to change look and field of each field.

<WA.AtomForm>
    <WA.AtomForm.fieldStyle>
        <XF.ControlTemplate>
            <XF.Grid>
                <XF.Grid.rowDefinitions>
                    <XF.RowDefinition height="Auto"/>
                    <XF.RowDefinition/>
                    <XF.RowDefinition height="Auto"/>
                 </XF.Grid.rowDefinitions>
                 <XF.Label
                     text={X.TemplateBinding("Label")}
                     textColor="Green"
                     />
                 <XF.ContentPresenter
                      { ... XF.Grid.row(1)}
                      />
             </XF.Grid>
        </XF.ControlTemplate>
    </WA.AtomForm.fieldStyle>
    <WA.AtomField
        label="Username:"
        isRequired={true}
        error={Bind.oneWay(() => this.viewModel.errorUsername)}>
           <XF.Entry text={Bind.twoWays(() => this.viewModel.model.username)}/>
    </WA.AtomField>
    <WA.AtomField
        label="Password"
        isRequired={true}
        error={Bind.oneWay(() => this.viewModel.errorPassword)}>
        <XF.Entry
            isPassword={true}
            text={Bind.twoWays(() => this.viewModel.model.password)}
            />
    </WA.AtomField>
    <XF.Button
        command={Bind.event((s, e) => this.viewModel.signup())}
        text="Signup"/>
</WA.AtomForm>

In above example, you can see that X.TemplateBinding allows you to bind Label property of TemplateOwner. Similarly you can use X.Binding to bind CLR data objects.

Examples,


   <XF.Label
       text={X.Binding("path")}

You cannot use CLR DataBinding to bind JavaScript objects, this is not limitation but it is unnecessary step as watching expressions for changes in CLR is more time consuming and requires complex expressions. We may improve this in future based on performance analysis. Currently keeping all bindings JavaScript makes it easy to debug as you can easily create HTML component and test it in browser.

Pros of CLR Data Binding

You can use them in ControlTemplate
You can reuse ValueConverters that exists in your C# code.

Cons of CLR Data Binding

You cannot use them to bind JavaScript objects
You cannot write unit test in JavaScript
You have to recompile and republish your app if you make changes to value converters

Current Limitations

These are current limitations in TSX, however they will be added in future as we progress.

No Style
No Trigger

However, it seems that we can easily create StyleSheet.

Xamarin Forms StyleSheet


   // you can write style as template literal
   const style = `
     listview image {
        height: 60;
        width: 60;
     }

     stacklayout>image {
        height: 200;
        width: 200;
     }
   `;

    <XF.Grid>
       <XF.Grid.Resources>
           <XF.StyleSheet source={style}/>
       </XF.Grid.Resources>
    </XF.Grid>

All Xamarin Components will automatically inherit whatever default Styles and StyleSheet you have added in App.Resources.

So you can create a master style for your app and put it in your App. You can also dynamically load the content of style sheet for your app, so you don't have to recompile and republish your app.

How to write Xamarin.Forms events in TypeScript?

Akash Kava — Tue, 03 Mar 2020 04:49:50 +0000

Events and Commands

Both events and commands can be written in one single pattern.


<XF.Button
    command={(e) => this.viewModel.save()}
    />

// OR

<XF.Button
    command={Bind.event((s, e) => this.viewModel.save())}
    />

There are two ways you can create event handler, one is simply a lambda function that can accept single parameter. In this expression, you cannot access current control, which may be useful when you are inside a multiple items container such as ListView or CollectionView or even BindableLayout.

You could simply write a function, but sometimes you may need to access enclosing AtomControl and its data or viewModel property.

Multiple Items Control

<XF.CollectionView>
   <XF.CollectionView.itemTemplate>
      <XF.DataTemplate>
          <XF.Label>
             <XF.Label.gestureRecognizers>
                 <XF.TapGestureRecognizer
                      command={Bind.event((s, e) =>
                         this.viewModel.select(s.data) }
                      />
             </XF.Label.gestureRecognizers>
          </XF.Label>
      </XF.DataTemplate>
   </XF.CollectionView.itemTemplate>
</XF.CollectionView>

Every item inside items container has an atom control associated with it, to access the data (BindingContext) associated with the control, we need to wrap lambda in Bind.event which gives us data property.

The syntax is similar to event handler syntax of Xamarin.Forms, with only difference being, sender is the AtomControl.

Data vs BindingContext

In order to improve speed and to keep JavaScript code isolated and consistent throughout different frameworks, we use data property instead of BindingContext as sometimes you may need to access more JavaScript properties such as viewModel/localViewModel etc.

Keeping bindings free from underlying platform also reduces amount of possible data transfer between both platforms and reduces possibility of memory leaks.

When you move your code to Web or other native platforms, BindingContext could be called some different name on different platforms.

Event Parameter

Event parameter object is serialized in JavaScript using WeakReference, you can call method and get/set property on it. Since it is weak reference, you cannot store it in JavaScript. You can only extract some information and you can store that information with you.

Dispatch Event

In order to keep event dispatch exactly same as in Html, we have added CustomEvent and dispatchEvent support for native elements of Xamarin.Forms.


export default class MyCustomControl extends AtomXFContentView { 

   ...

   // dispatch..
   this.element.dispatchEvent(new CustomEvent("customEvent", { detail: param }));

   ...

Listen for event..


   <MyCustomControl
       eventCustomEvent={Bind.event((s, e) => this.viewModel.onEvent(e.detail))}
       />

Even though such event does not exist in Xamarin.Forms element, you can still subscribe to it and listen for it, it works exactly similar to HTML events.

Event Execution

All events are fired under main UI thread, so it is recommended that do not do any long processing in event handler.

Async Event Handler

All event handlers are assumed to be async by default, so if you return a promise in your event handler, error will be caught and it will be displayed in console.

`@Action()` decorator

In order to display an alert for any exception, you can decorate your event handler with @Action() decorator.

   @Action({ validate: true })
   public async save() {
      ....
   }

Validate

Setting validate true, will fire up all validations and action will be executed if only all validations pass through.

Success

If set to true, or a non empty string, an alert message box will be displayed after successful execution.

Memory Leaks

Since dealing with multiple runtimes can quickly introduce memory leaks, Web Atoms systematically disposes every event registered via TSX code. It is better if you register events only through TSX.

Otherwise, every event registration done in JavaScript returns a disposable, which you can add to your viewModel. View model has collection of disposables and it disposes every registered disposable when view model is disposed.

How to write Templates in Xamarin.Forms with TypeScript?

Akash Kava — Mon, 02 Mar 2020 07:37:53 +0000

List View

Same as in XAML, you can create DataTemplate easily in TSX as shown below, syntax is not very different then that of Xaml.


import Bind from "@web-atoms/core/dist/core/Bind";
import XNode from "@web-atoms/core/dist/core/XNode";
import { AtomXFControl } from "@web-atoms/core/dist/xf/controls/AtomXFControl";
import XF from "@web-atoms/xf-controls/dist/clr/XF";
import AtomXFContentPage from "@web-atoms/xf-controls/dist/pages/AtomXFContentPage";
import ListViewModel from "./ListViewModel";

export default class List extends AtomXFContentPage {

    public viewModel: ListViewModel;

    public create() {
        this.viewModel = this.resolve(ListViewModel);

        this.render(
            <XF.ContentPage title="List Sample">
                <XF.ListView itemsSource={Bind.oneWay(() => this.viewModel.movies.value)}>
                    <XF.ListView.itemTemplate>
                        <XF.DataTemplate>
                            <XF.ViewCell>
                                <XF.Label text={Bind.oneWay((x) => x.data.name)}/>
                            </XF.ViewCell>
                        </XF.DataTemplate>
                    </XF.ListView.itemTemplate>
                </XF.ListView>
            </XF.ContentPage>
        );
    }

}

Same as that of Xaml, you can define DataTemplate with a ViewCell or any element that is derived from Cell

Template Selector

Writing template selector requires little different syntax.

        this.render(<XF.ContentPage title="List with Template Selector">
            <XF.ListView itemsSource={Bind.oneWay(() => this.viewModel.movies.value)}>
                <WA.AtomTemplateSelector.templateSelector>
                    <WA.AtomTemplateSelector selector={(d: IMovie) => /horror/i.test(d.genre)
                        ? 1 : 0}>
                        {/* Template 0 */}
                        <XF.DataTemplate>
                            <XF.TextCell
                                text={Bind.oneWay((x) => x.data.name)}
                                textColor="black"
                                />
                        </XF.DataTemplate>
                        {/* Template 1 */}
                        <XF.DataTemplate>
                            <XF.TextCell
                                text={Bind.oneWay((x) => x.data.name)}
                                textColor="red"
                                />
                        </XF.DataTemplate>
                    </WA.AtomTemplateSelector>
                </WA.AtomTemplateSelector.templateSelector>
            </XF.ListView>
        </XF.ContentPage>);

As you can see, WA.AtomTemplateSelector is a placeholder element, which will simply set template based on some condition.

selector condition evaluates and returns an index of templates enclosed within AtomTemplateSelector.

Collection View

In collection view, you can write templates without cells, same as in Xaml.

   <XF.CollectionView 
       itemsSource={Bind.oneWay(() => this.viewModel.movies.value)}>
       <XF.CollectionView.itemTemplate>
            <XF.DataTemplate>
                <XF.Label text={Bind.oneWay((x) => x.data.name)}/> 
            </XF.DataTemplate>
       </XF.CollectionView.itemTemplate>
   </XF.CollectionView>

How does it work?

XF.DataTemplate translates to Xamarin.Forms.DataTemplate and it uses constructor with factory to create elements only when needed.

How to create control template?

Creating control template is exactly same with little difference in CLR Xamarin binding syntax.

Following example displays, how to change ControlTemplate of AtomField in form.

   <WA.AtomForm.fieldStyle>
      <XF.ControlTemplate>
         <XF.Grid>
            <XF.Grid.rowDefinitions>
               <XF.RowDefinition height="Auto"/>
                  <XF.RowDefinition/>
                  <XF.RowDefinition height="Auto"/>
            </XF.Grid.rowDefinitions>
            <XF.Label
               text={X.TemplateBinding("Label")}
               textColor="Green"
               />
            <XF.ContentPresenter
               { ... XF.Grid.row(1)}
               />
         </XF.Grid>
     </XF.ControlTemplate>
   </WA.AtomForm.fieldStyle>

Binding of Xamarin.Forms is actually replaced with X.Binding and X.TemplateBinding.

In above example, XF.ControlTemplate refers to ControlTemplate of Xamarin.Forms. Templates are optimized to be reused and there is no performance lag even when they are written in TypeScript.

Interoperability

Web Atoms allows you to use, both JavaScript as well as Xamarin Bindings on TemplateBinding as well as Binding. However, little care must be taken based on source object. To bind properties of classes written in C# you must use X.Binding and X.TemplateBinding respectively. To bind objects created in JavaScript, you must use Bind.oneWay/twoWays syntax.

How to use third party controls in Web Atoms for Xamarin.Forms?

Akash Kava — Wed, 19 Feb 2020 08:18:50 +0000

As you have seen in previous article on how to use TypeScript with TSX (JSX) for Xamarin.Forms, it describes usage of default Xamarin.Forms controls.

However, using third party control is super easy, you can either use reflection to generate the class definitions or you can write them easily.

How it works?

bridge.getClass(assemblyQualifiedName: string) returns a .Net Type proxy which you can use to create object.

Sample

Just by looking at definition, you will understand how to create one...

Define a class


declare class FormField extends RootObject {

   // static field lets you define inline templates
   public static fieldTemplate: NodeFactory;

   public label: string;

   public required: boolean;

   public error: string;

   public errorColor: ColorItem;

   public errorBackgroundColor: ColorItem;

}

const ThirdParty = {
    FormField: bridge.getClass("Namespace.FormField, AssemblyName")
        as typeof FormField
};

You may not need to create exact same hierarchy, as creating extra abstract classes do not serve any purpose unless they have some properties.

How to use?

Once all classes are defined, you can import and use them as shown below.


// this imports all default controls of Xamarin.Forms
import XF from "@web-atoms/xf-controls/dist/clr/XF";

import ThirdParty from "../clr/ThirdParty";

export default class MyFormPage extends AtomXFContentPage {

   public create() {
      this.render(
          <XF.ContentPage>
             <XF.StackLayout>

                 // This is typescript component
                 <MyPageHeader/>

                 // this is how you can use your
                 // third party control
                 <ThirdParty.FormField
                     label="Username:"
                     error={Bind.oneWay(() =>
                        this.viewModel.errorUsername)}>
                     <XF.Entry
                        text={Bind.twoWays(() =>
                            this.viewModel.model.username)}
                        />
                 </ThirdParty.FormField>
             </XF.StackLayout>
          </XF.ContentPage>
      );
   }

}

The only reason we include all classes inside a default declaration is, while creating JSX, we can visually distinguish between CLR classes and TypeScript components. So all elements without . (Dot) are TypeScript components and all elements with . are CLR classes.

Defining Expandable Properties

This is little hacky, but simple one. Let's see how can we write MasterDetailPage in TSX.

    <XF.MasterDetailPage>
       <XF.MasterDetailPage.Header>
           <XF.ContentPage ....
           </XF.ContentPage>
       </XF.MasterDetailPage.Header>
    </XF.MasterDetailPage>

Definition of MasterDetailPage is as follow,


class MasterDetailPage extends ContentPage {

   // this hacks is required to create expandable property
   public static header = XNode.property();

   public header: any;

}

Defining Attached Property

Control such as Grid has attached properties, which we can define and use as follow.

This is how grid is defined...

class Grid extends RootObject {

   // following are attached properties
   public static row = AttachedNode;

   public static column = AttachedNode;

   public static rowSpan = AttachedNode;

   public static columnSpan = AttachedNode;

   // following are expandable
   public static rowDefinitions = NodeFactory;

   public static columnDefinitions = NodeFactory;

}

Usage


   <XF.Grid>
       <XF.Grid.rowDefinitions>
           <XF.RowDefinition height="Auto"/>
           <XF.RowDefinition/>
       </XF.Grid.rowDefinitions>
       <XF.ListView
           // this is how attached property is used
           { ... XF.Grid.row(1) }
           { ... XF.Grid.columnSpan(2) }
           />
   </XF.Grid>

This way, you can define any third party components and you can use them inside TSX.

Simple Unit Testing with Web Atoms

Akash Kava — Tue, 18 Feb 2020 06:59:01 +0000

Test Class and Method

I know many would be unhappy seeing classes, but classes are only used to decorate and organize code, you can always do more functional things with Web Atoms Unit Tests.


/** Category decorator is optional, it just lets you specify name of test instead of name of class that extends TestItem */
@Category("Test Case 1")
export default class TestCase1 extends TestItem {

    @Test
    public parseTest() {
        Assert.equals(2, parseInt("2", 10));
    }

    /** You can specify name of test */
    @Test("Parse Float Test")
    public parseFloat() {
        Assert.equals(2.5, parseFloat("2.5"));
    }

}

How to run the test?

You can execute @web-atoms/unit-test/index.js script against folder of all scripts. You can also give path to single test file as well.

d:\git\test> node ./node_modules/@web-atoms/unit-test/index.js ./dist

Test Case 1 > parseTest success.
Test Case 1 > Parse Float Test success.

Async Tests

Your test method can also return Promise and it unit test engine will await for the result.


@Category("Async Test 1")
export default class TestCase1 extends TestItem {

    @Test
    public async asyncTestOne() {
        const p = method that returns Promise ....
        await p;
    }

}

Global Separation

Each unit test executes in a separate Global context in Node, this isolates every unit test method. Even same test methods in same class do not share same context.


declare var global: any;

export default class TestCase1 extends TestItem {

    @Test
    public async parseTest() {
        global.a = 1;
        await Atom.delay(100);
        Assert.equal(1, global.a);
    }

    @Test
    public async parseTest2() {
        global.a = 2;
        await Atom.delay(50);
        Assert.equal(2, global.a);
    }

}

Both tests will be successful.

How to test ViewModel?

Since AtomViewModel requires dependency injection, we have created a class AtomTest which sets up dependency injection with Mock Service Container.

This class contains app and it has a method waitForPendingCalls which allows you to wait for all pending initializations.

class TestVM extends AtomViewModel {

   public movies: IMovie[];

   public search: string = null;

   @Inject private movieService: MovieService;

   /** This will be executed when vm is initialized and it will
    * be executed when search will be updated 
    */
   @Load({ init: true, watch: true })
   public async loadItems(ct: CancelToken) {
      const s = this.search;
      this.movies = await this.movieService.loadMovies(s, ct);
   }

}

export default class TestVMCase extends AtomTest {

    @Test
    public async vmTest() {
        // this waits till loading of vm is complete
        const vm = await this.createViewModel(TestVM);
        Assert.equals(5, vm.movies.length);

        // lets update search
        vm.search = "a";

        // lets wait for few milliseconds
        // and we assume that mock will populate
        // results...
        await Atom.delay(100);
        Assert.equals(1, vm.movies.length);
    }

}

Mocks

Every dependency can specify mock as shown below.

@DISingleton({ mock: "./mocks/MockMovieService" })
export default class MovieService extends BaseService {

    @Get("/api/movies")
    public async loadMovies(
        @Query("search") search: string,
        ct: CancelToken) {
        return null;
    }
}

./Mocks/MockMovieService

export default class MockMovieService {

    public async loadMovies(
        search: string,
        ct: CancelToken) {
        // create artificial delay...
        await Atom.delay(1);
        if (ct.cancelled) throw new Error("cancelled");
        return [
           ... movies 
        ];
    }
}

Write your Xamarin.Forms apps with VS Code, TypeScript and TSX !!

Akash Kava — Mon, 17 Feb 2020 15:57:16 +0000

How is it possible?

We have created a JavaScript bridge for Android using V8 and in iOS using JavaScriptCore. This bridge allows you to load JavaScript and create Xamarin.Forms control on the fly.

TSX Instead of Xaml

Xaml is great, no doubt, but TSX in VS Code is even more powerful. Take a look at following code,

import Bind from "@web-atoms/core/dist/core/Bind";
import XNode from "@web-atoms/core/dist/core/XNode";
import { AtomXFControl } from "@web-atoms/core/dist/xf/controls/AtomXFControl";
import XF from "@web-atoms/xf-controls/dist/clr/XF";
import AtomXFContentPage from "@web-atoms/xf-controls/dist/pages/AtomXFContentPage";
import ListViewModel from "./ListViewModel";

export default class List extends AtomXFContentPage {

    public viewModel: ListViewModel;

    public create() {
        this.viewModel = this.resolve(ListViewModel);

        this.render(
            <XF.ContentPage title="List Sample">
                <XF.ListView 
                    itemsSource={Bind.oneWay(() =>
                        this.viewModel.movies.value)}>
                    <XF.ListView.itemTemplate>
                        <XF.DataTemplate>
                            <XF.ViewCell>
                                <XF.Label
                                   text={Bind.oneWay((x) => x.data.name)}/>
                            </XF.ViewCell>
                        </XF.DataTemplate>
                    </XF.ListView.itemTemplate>
                </XF.ListView>
            </XF.ContentPage>
        );
    }

}

Best of Both Worlds

NuGet + NPM, you can use most of both the worlds. It is very easy to expose services from C# to JavaScript.

Extend Library

You can easily create new component within JavaScript (TypeScript) and you can also write similar component in C# to improve performance.

Try Now

https://www.webatoms.in/play/demo/shapes/1

Explore new feature "Shapes" of Xamarin.Forms 4.7.

https://www.webatoms.in/play/demo/master-detail

Application with drawer and multiple pages, using navigation service to open pages, retrieve result and load unpacked pages.

https://www.webatoms.in/play/demo/list

Explore list view with Cell bindings. Using two way binding to update the selection.

https://www.webatoms.in/play/demo/form/3

Explore validation sample with simple form.

https://www.webatoms.in/play/demo/tabbed-page/3

Web Atoms MVVM with Xamarin.Forms Features

JavaScript Stack Trace

C# Code is little painful to debug in production as line numbers are missing. Not only that, JavaScript stack traces retains line numbers in production with source map making life lot easier.

Side by Side Versioning

This is by far the biggest benefit, in typical production application, you cannot change version immediately, but with Web Atoms, you can dynamically change version and even allow single user to change version. This allows you to investigate bugs and platform related issues easily.

Performance

Of course, JavaScript engine execution and lot of data transfer between JavaScript, CLR and native platform is expensive, and it is little slow compared to pure C# code. But at the same time, you can always tweak your code easily. We first roll out beta in JavaScript, we let it stabilize and then we move that part of code to C#. Only when you make changes to C# code, you have to republish app to the store.

Smaller App Size

Since your app only contains JavaScript engine code, your app becomes smaller, all your Views/View Models/Services stay on web server.

We have organized documentation and we are still in process of making more documentation available easily. Integration requires little effort, but once the application is setup, it is extremely easy to build/test and deploy.