diff --git a/Modules30Changes.md b/Modules30Changes.md index 3b6db64c9..b4fb91d6c 100644 --- a/Modules30Changes.md +++ b/Modules30Changes.md @@ -2,16 +2,16 @@ ## General notes -We are moving the modules closer to ES6 standard. This introduces few limitations. One of them is modules can no longer export variable, in such cases variables were replace with get/set functions. +We are moving the modules closer to ES6 standard. This introduces few limitations. One of them is modules can no longer export variable, in such cases variables were replaced with get/set functions. ## TypeScript TypeScript projects need to reference the **ES6 and DOM libraries**. Add this to your tsconfig.json: -``` +``` json { "compilerOptions": { ... - "lib": ["es6", "dom"] + "lib": ["es6", "dom"], "baseUrl": ".", "paths": { "*": [ @@ -25,13 +25,13 @@ TypeScript projects need to reference the **ES6 and DOM libraries**. Add this to The `camera` module is removed. Use `nativescript-camera` plugin instead. ## Location -The `location` module is removed. Use `nativescript-geolocation”` plugin instead. +The `location` module is removed. Use `nativescript-geolocation` plugin instead. ## Changes in UI Modules ### Application We are using the following import statement for the code samples in this section -``` +``` ts import * as application from "tns-core-modules/application"; ``` @@ -77,15 +77,15 @@ Use `observableModule.fromObject(obj)` method instead. Removed method `insertTab()`. You can use `items` property for setting additional tabs. Removed method `getValidIndex()` - it was intended for internal use only. -The 'items' property os of type `SegmentedBarItem[]`. Items should be created using the `SegmentedBarItem` constructor. +The 'items' property is of type `SegmentedBarItem[]`. Items should be created using the `SegmentedBarItem` constructor. Old code: -``` +``` ts let firstItem = {"title": "first"}; segmentedBar.items = [ firstItem ]; ``` New code: -``` +``` ts let firstItem = new SegmentedBarItem(); firstItem.title = "first"; segmentedBar.items = [ firstItem ]; @@ -102,7 +102,7 @@ Removed methods and properties. These were for internal use only and not needed Removed properties of `TabView` class (`ui/tab-view` module): * `selectedColor` - use `selectedTabTextColor` instead. * `tabsBackgroundColor` - use `tabBackgroundColor` instead. -* `textTransform` - `textTransform` is can be set on the individual `TabViewItem`s instead on the `TabView` +* `textTransform` - `textTransform` can be set on the individual `TabViewItem`s instead on the `TabView` ### TextField & TextView (Android) Setting `text-transform` property on these controls will not change the text inside them. In case you want to transform the text you should do it before setting it to `text` property. @@ -117,7 +117,7 @@ import * as utils from "tns-core-modules/utils/utils"; ``` Removed `utils.parseJSON(source: string)` method – use `JSON.parse()` instead. -The following functions. These were for internal use only and not needed any more: +Removed the following functions. These were for internal use only and are not needed any more: * `utils.copyFrom(source: any, target: any)` * `utils.ad.setTextTransform(view, value: string)` * `utils.ad.setWhiteSpace(view, value: string)` @@ -131,11 +131,12 @@ The following functions. These were for internal use only and not needed any mor Property `cssClass` removed, use `className` instead. -The `_createUI()` methods is renamed to `createNativeView()`. It should now return a native view instance instead of setting it locally. Read more [here](#view-life-cycle) +The `_createUI()` method is renamed to `createNativeView()`. It should now return a native view instance instead of setting it locally. Read more [here](#view-life-cycle). -The `_onBindingContextChanged()` method is removed – if you are using this to set the `bindingContext` of an object if that object is extending `ViewBase` it will automatically have its `bindingContext` set. In case you need to know when `bindingContext` is changed you could add handler to `this.on("bindingContextChange", handlerMethod, this)`. +The `_onBindingContextChanged()` method is removed. +If you are using this to set the `bindingContext` of an object and that object is extending `ViewBase`, it will automatically have its `bindingContext` set. In case you need to know when `bindingContext` is changed you could add handler to `this.on("bindingContextChange", handlerMethod, this)`. -VerticalAlignment - `"center"` is removed from Typescript definition files but still supported through CSS/XML. In code – use `"middle"` instead of center. +VerticalAlignment - `"center"` is removed from Typescript definition files but is still supported through CSS/XML. In code – use `"middle"` instead of center. ### WebView The `url` property of `WebView` is removed, use `src` instead. @@ -153,11 +154,11 @@ There are several type of Properties in modules 3.0: There is a new property `nativeView` in `ViewBase` class. It is recommended to use `nativeView` instead of `ios` and `android` properties. The `ios` and `android` properties are left for compatibility, however all view-lifecycle methods and native property callbacks (explained below) should work with the `nativeView` property. ### Property Example -In here is how to define `text` (view property) and `text-align` (css property) for the text-View +Here is how to define `text` (view property) and `text-align` (css property) for the text-View `my-text-view-common.ts` with cross-platform code -``` +``` ts import { View, Property, CssProperty, InheritedCssProperty, Style, } from "tns-core-modules/ui/core/view"; export class MyTextViewCommon extends View { @@ -198,7 +199,7 @@ Recycling the native view of control is done only if `recycleNativeView` field i `my-text-view.android.ts` with android specific implementation: -``` +``` ts import { MyTextViewCommon, textAlignmentProperty, textProperty, ... } from "./my-text-view-common"; @@ -252,11 +253,11 @@ The way of defining properties using `Styler` class and property handlers are no ### View Class Hierarchy The class hierarchy prior 3.0 was: -``` +``` ts Observable > DependencyObservable > Bindable > ProxyObject > View ``` In 3.0 the redesign of the property system allowed us to collapse it to: -``` +``` ts Observable > ViewBase > View ``` @@ -265,9 +266,9 @@ Observable > ViewBase > View Consider using `View`, `ViewBase` or `Observable` instead. ### Property Types -As a part of the we have changed the types of many properties. The reasons for the changes: +As a part of the refactoring we have changed the types of many properties. The reasons for the changes: * Make better use of the TypeScript typings. - * Support for units (`dip`, `px`, `%`) for properties like `width`, `height`, `margin` + * Support for units (`dip`, `px`, `%`) for properties like `width`, `height`, `margin`. Here is a list of view and style properties that have their types changes: @@ -288,10 +289,10 @@ As a part of the we have changed the types of many properties. The reasons for t | Style.border[TopLeft/TopRight/BottomLeft/BottomRight]Radius | number | Length | | ListView.rowHeight | number | Length | -Many of the Style properties are also defined on the `View` class - the changes in the types are the same. +Many of the `Style` properties are also defined on the `View` class - the changes in the types are the same. -Note: The new types are back compatible when it comes to setters. For example: -``` +Note: The new types are backwards compatible when it comes to setters. For example: +``` ts let image = new Image(); // still works - sets the width in dips image.width = 100; @@ -300,7 +301,7 @@ image.width = 100; image.width = { value: 100, unit: "px" }; ``` -You will have to be careful when getting the value - you might get an complex object instead of `number` +You have to be careful when getting the value - you might get a complex object instead of `number`. ### Enumerations Enumeration from `ui/enums` modules are not used anymore. Most ot the properties that accepts specific strings are defined directly with the allowed values: @@ -309,9 +310,9 @@ TypeScript will warn in case you set invalid value. ### View Life-cycle -With 3.0 we are introducing nativeView recycling. With nativeView recycling we aim to reduce instantiation of native view which is really expensive operation in android. In order to be able to recycle it we need all properties exposed from the View to be of our new property system. +With 3.0 we are introducing nativeView recycling. With nativeView recycling we aim to reduce instantiation of native views which is really expensive operation in Android. In order to be able to recycle it, we need all properties exposed from the `View` to be of our new property system. -In short we have method that gets the default value for a property which is get the first time a property value is changed. Once we know that our View is not needed anymore we will reset the native view to its original state and put it in a map where some future View of the same type could reuse it. +In short, we have method that gets the default value for a property which is get the first time a property value is changed. Once we know that our `View` is not needed anymore we will reset the native view to its original state and put it in a map where some future `View`s of the same type could reuse it. There are 3 new important methods: * `createNativeView(): Object;` - method to create and return the native view instance. * `initNativeView(): void;` - method to initialize the native view. Attach handlers, owner, etc. @@ -321,15 +322,15 @@ There are 3 new important methods: There are two methods that allow you to traverse view-hierarchy: For getting `View` children use: -``` +``` ts public eachChildView(callback: (child: View) => boolean): void ``` This method was previously known as `_eachChildView()`. It will return `View` descendants only. For example `TabView` returns the view of each `TabViewItem` because is `TabViewItem` is of type `ViewBase`. Getting `ViewBase` children use: -``` +``` ts public eachChild(callback: (child: ViewBase) => boolean): void; ``` This method will return all views including `ViewBase`. It is used by the property system to apply native setters, propagate inherited properties, apply styles, etc. -In the case of `TabView` – this method will return `TabViewItem`'s as well so that they could be styled through CSS. +In the case of `TabView` – this method will return `TabViewItem`s as well so that they could be styled through CSS.