Skip to content
This repository was archived by the owner on Nov 17, 2022. It is now read-only.

Improve docs #1811

Merged
merged 1 commit into from
Oct 8, 2019
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions docs/cookbook/tab-view-ng.md
Original file line number Diff line number Diff line change
Expand Up @@ -112,8 +112,8 @@ export class DataItem {
}

@Component({
selector: "tab-view-test",
templateUrl: "tab-view-test.html"
selector: "tab-view-test",
templateUrl: "tab-view-test.html"
})
export class TabViewTest {
public items: Array<DataItem>;
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -149,7 +149,7 @@ let array = new NSMutableArray();
array.addObject(new NSObject());
```

This snippet creates an instance of `NSMutableArray` and adds an object to it using the `addObject(object)` method. Here is what happens behind the curtains: the `new NSMutableArray()` call is translated to a `[[NSMutableArray alloc] init]` call by the iOS Runtime. This instance is then wrapped in a JavaScript object and stored in the `array` variable. It contains all public properties and methods exposed by `NSMutableArray` (and its base classes) in its prototype chain. While the `addObject(object)` call is straightforward, calling Objective-C methods with more arguments follows several simple rules that define how Objective-C selectors are mapped to JavaScript functions. Let's consider the following `NSMutableArray` selector: `replaceObjectsInRange:withObjectsFromArray:range:`. In JavaScript it is represented by the following function: `replaceObjectsInRangeWithObjectsFromArrayRange(objectsToRange, souceArray, sourceRange)` (argument names are arbitrary). Note that the function name is generated by appending the names of the arguments as defined by the Objective-C selector by starting with a small letter for the first argument and appending each subsequent with a capital letter.
This snippet creates an instance of `NSMutableArray` and adds an object to it using the `addObject(object)` method. Here is what happens behind the curtains: the `new NSMutableArray()` call is translated to a `[[NSMutableArray alloc] init]` call by the iOS Runtime. This instance is then wrapped in a JavaScript object and stored in the `array` variable. It contains all public properties and methods exposed by `NSMutableArray` (and its base classes) in its prototype chain. While the `addObject(object)` call is straightforward, calling Objective-C methods with more arguments follows several simple rules that define how Objective-C selectors are mapped to JavaScript functions. Let's consider the following `NSMutableArray` selector: `replaceObjectsInRange:withObjectsFromArray:range:`. In JavaScript it is represented by the following function: `replaceObjectsInRangeWithObjectsFromArrayRange(objectsToRange, sourceArray, sourceRange)` (argument names are arbitrary). Note that the function name is generated by appending the names of the arguments as defined by the Objective-C selector by starting with a small letter for the first argument and appending each subsequent with a capital letter.

#### NSDictionary

Expand Down
2 changes: 1 addition & 1 deletion docs/core-concepts/angular-data-binding.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,7 @@ onButtonTap(args: EventData) {

> Before we can use the ngModel directive in a two-way data binding, we must import the **NativeScriptFormsModule** and add it to the Angular module's imports list:
> ```typescript
import {NativeScriptFormsModule} from "nativescript-angular/forms"
import { NativeScriptFormsModule } from "nativescript-angular/forms"
@NgModule({
imports: [
NativeScriptModule,
Expand Down
112 changes: 56 additions & 56 deletions docs/core-concepts/angular-navigation.md
Original file line number Diff line number Diff line change
Expand Up @@ -67,8 +67,8 @@ import { RouterExtensions } from "nativescript-angular/router";
})
export class MainComponent {

constructor(private routerExtensions: RouterExtensions) {
}
constructor(private routerExtensions: RouterExtensions) {
}
}
```

Expand Down Expand Up @@ -240,17 +240,17 @@ export class AppComponent { }
import { Component, OnInit } from "@angular/core";

@Component({
selector: "Hub",
templateUrl: "./hub.component.html",
styleUrls: ['./hub.component.css']
selector: "Hub",
templateUrl: "./hub.component.html",
styleUrls: ['./hub.component.css']
})
export class HubComponent implements OnInit {

constructor() {
}
constructor() {
}

ngOnInit(): void {
}
ngOnInit(): void {
}
}
```
```hub.component.html
Expand All @@ -268,21 +268,21 @@ import { Component, OnInit } from "@angular/core";
import { Location } from "@angular/common";

@Component({
selector: "Featured",
templateUrl: "./featured.component.html",
styleUrls: ['./featured.component.css']
selector: "Featured",
templateUrl: "./featured.component.html",
styleUrls: ['./featured.component.css']
})
export class FeaturedComponent implements OnInit {

constructor(private location: Location) {
}
constructor(private location: Location) {
}

ngOnInit(): void {
}
ngOnInit(): void {
}

goBack(): void {
this.location.back();
}
goBack(): void {
this.location.back();
}
}
```
```featured.component.html
Expand Down Expand Up @@ -372,17 +372,17 @@ import { Component, OnInit } from "@angular/core";
import { RouterExtensions } from "nativescript-angular/router";

@Component({
selector: "Featured",
templateUrl: "./featured.component.html",
styleUrls: ['./featured.component.css']
selector: "Featured",
templateUrl: "./featured.component.html",
styleUrls: ['./featured.component.css']
})
export class FeaturedComponent implements OnInit {

constructor(private routerExtensions: RouterExtensions) {
}
constructor(private routerExtensions: RouterExtensions) {
}

ngOnInit(): void {
}
ngOnInit(): void {
}
}
```
```featured.component.html
Expand All @@ -398,17 +398,17 @@ export class FeaturedComponent implements OnInit {
import { Component, OnInit } from "@angular/core";

@Component({
selector: "Item",
templateUrl: "./item.component.html",
styleUrls: ['./item.component.css']
selector: "Item",
templateUrl: "./item.component.html",
styleUrls: ['./item.component.css']
})
export class ItemComponent implements OnInit {

constructor() {
}
constructor() {
}

ngOnInit(): void {
}
ngOnInit(): void {
}
}
```
```item.component.html
Expand All @@ -434,21 +434,21 @@ import { Component, OnInit } from "@angular/core";
import { RouterExtensions } from "nativescript-angular/router";

@Component({
selector: "Item",
templateUrl: "./item.component.html",
styleUrls: ['./item.component.css']
selector: "Item",
templateUrl: "./item.component.html",
styleUrls: ['./item.component.css']
})
export class ItemComponent implements OnInit {

constructor(private routerExtensions: RouterExtensions) {
}
constructor(private routerExtensions: RouterExtensions) {
}

ngOnInit(): void {
}
ngOnInit(): void {
}

goBack(): void {
this.routerExtensions.back();
}
goBack(): void {
this.routerExtensions.back();
}
}
```
```item.component.html
Expand Down Expand Up @@ -561,11 +561,11 @@ import { Component, OnInit } from "@angular/core";
})
export class HubComponent implements OnInit {

constructor() {
}
constructor() {
}

ngOnInit(): void {
}
ngOnInit(): void {
}
}
```
```hub.component.html
Expand Down Expand Up @@ -620,7 +620,7 @@ The `TabView` component enables the user to arbitrarily navigate between several

![navigation-diagram-ng-tab](../img/navigation/navigation-diagram-ng-tab.png?raw=true)

The `BottomNavigation` container provides its lateral navigation logic automatically by providing the user with tabs which they can select. To set up a `BottomNavigation` you need to simply declare the UI of each container via a `TabItemContent` and set the title and icon via coresponding `tabStripItem` (details on the basic structure [here](http://localhost:9192/angular/ui/ng-ui-widgets/bottom-navigation#usage)). Each separate UI container is represented by the `TabContentItem` component. As with other containers, you can enable forward and backward navigation inside each of them by embedding a `page-router-outlet` in it. In this case we need to use three sibling outlets. The way to do this with the Angular router is to use [named outlets](https://angular.io/guide/router#displaying-multiple-routes-in-named-outlets). Each of our outlets will be named with the name of the feature that it represents.
The `BottomNavigation` container provides its lateral navigation logic automatically by providing the user with tabs which they can select. To set up a `BottomNavigation` you need to simply declare the UI of each container via a `TabItemContent` and set the title and icon via corresponding `tabStripItem` (details on the basic structure [here](http://localhost:9192/angular/ui/ng-ui-widgets/bottom-navigation#usage)). Each separate UI container is represented by the `TabContentItem` component. As with other containers, you can enable forward and backward navigation inside each of them by embedding a `page-router-outlet` in it. In this case we need to use three sibling outlets. The way to do this with the Angular router is to use [named outlets](https://angular.io/guide/router#displaying-multiple-routes-in-named-outlets). Each of our outlets will be named with the name of the feature that it represents.

The `BottomNavigation` widget also provides two important features connected to lateral navigation:

Expand Down Expand Up @@ -712,7 +712,7 @@ export class AppComponent {
```app.component.html
<BottomNavigation selectedIndex="1">

<!-- The bottom tab UI is created via TabStrip (the containier) and TabStripItem (for each tab)-->
<!-- The bottom tab UI is created via TabStrip (the container) and TabStripItem (for each tab)-->
<TabStrip>
<TabStripItem>
<Label text="Home"></Label>
Expand Down Expand Up @@ -747,17 +747,17 @@ export class AppComponent {
import { Component, OnInit } from "@angular/core";

@Component({
selector: "Featured",
templateUrl: "./featured.component.html",
styleUrls: ['./featured.component.css']
selector: "Featured",
templateUrl: "./featured.component.html",
styleUrls: ['./featured.component.css']
})
export class FeaturedComponent implements OnInit {

constructor() {
}
constructor() {
}

ngOnInit(): void {
}
ngOnInit(): void {
}
}
```
```featured.component.html
Expand Down
30 changes: 15 additions & 15 deletions docs/core-concepts/data-binding.md
Original file line number Diff line number Diff line change
Expand Up @@ -240,22 +240,22 @@ Another common case in working with bindings is requesting access to the parent
_Example 4: Creating ListView child items based on the itemTemplate._
``` XML
<Page navigatingTo="onNavigatingTo" xmlns="http://schemas.nativescript.org/tns.xsd">
<GridLayout rows="*" >{%raw%}
<ListView items="{{ items }}">
<!--Describing how the element will look like-->
<ListView.itemTemplate>
<GridLayout columns="auto, *">
<Label text="{{ $value }}" col="0"/>
<!--The TextField has a different bindingCotnext from the ListView, but has to use its properties. Thus the parents['ListView'] has to be used.-->
<!-- Parent binding to a string property -->
<GridLayout rows="*" >{%raw%}
<ListView items="{{ items }}">
<!--Describing how the element will look like-->
<ListView.itemTemplate>
<GridLayout columns="auto, *">
<Label text="{{ $value }}" col="0"/>
<!--The TextField has a different bindingCotnext from the ListView, but has to use its properties. Thus the parents['ListView'] has to be used.-->
<!-- Parent binding to a string property -->
<TextField text="{{ $parents['ListView'].test, $parents['ListView'].test }}" col="1"/>

<!-- Parent binding to a method onTap -->
<Button text="Tap me" tap="{{ $parents['ListView'].onTap, $parents['ListView'].onTap }}" />
</GridLayout>
</ListView.itemTemplate>
</ListView>
{%endraw%}</GridLayout>
</GridLayout>
</ListView.itemTemplate>
</ListView>
{%endraw%}</GridLayout>
</Page>
```
``` JavaScript
Expand Down Expand Up @@ -301,9 +301,9 @@ You can create a custom expression for bindings. Custom expressions could help i

``` XML
<Page xmlns="http://schemas.nativescript.org/tns.xsd">
<StackLayout>{%raw%}
<TextField text="{{ sourceProperty, sourceProperty + ' some static text' }}" />
{%endraw%} </StackLayout>
<StackLayout>{%raw%}
<TextField text="{{ sourceProperty, sourceProperty + ' some static text' }}" />
{%endraw%}</StackLayout>
</Page>
```

Expand Down
16 changes: 9 additions & 7 deletions docs/core-concepts/error-handling.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,26 +43,28 @@ This API also introduces a technique, which allows the developers to define cust

Example:

```
```javascript
import "./bundle-config";
import * as application from "tns-core-modules/application";
import * as traceModule from "tns-core-modules/trace"
import * as traceModule from "tns-core-modules/trace";

const errorHandler: traceModule.ErrorHandler = {
handlerError(err){
//option 1 (development) - throw the error
handlerError(err) {
// Option 1 (development) - throw the error
throw err;

//option 2 (development) - logging the error via write method provided from trace module
// Option 2 (development) - logging the error via write method provided from trace module
traceModule.write(err, "unhandled-error", type.error);

//(production) - custom functionality for error handling
//reportToAnalytics(err)
// (production) - custom functionality for error handling
// reportToAnalytics(err)
}
}

traceModule.setErrorHandler(errorHandler)
application.run({ moduleName: 'app-root' });
```

The example shows how to define a custom handler and three possible options for handling the error via [trace]({%slug trace%}) module or while using custom functionality.

Further info about the error handing in NativeScript can be found [here](https://github.com/NativeScript/NativeScript/blob/master/HandlingErrors.md).
Expand Down
2 changes: 1 addition & 1 deletion docs/core-concepts/memory-management.md
Original file line number Diff line number Diff line change
Expand Up @@ -141,7 +141,7 @@ Unlike iOS, both the Java and JavaScript in the Android runtime are managed. The
Memory leaks are rare. If there is a pool of unreachable splices from either Java or JavaScript, at some point the V8 GC will notify the JavaScript instances that they are marked for collection, then the reference to the Java counterpart will be made weak. Then the next Android VM GC will collect the Java instances and the V8 GC after that will collect the JavaScript instances (because the Java counterparts will be dead).

#### Half-Dead Splice
Since collection is driven by the garbage collectors it is possible to hold a weak reference to the JavaScript instance of a splice. After a V8 GC, the splice can make the reference to the Java instance weak allowing the Android VM GC to collect it. Then, if before the next V8 GC the JavaScript instance is obtained from the weak reference and its methods are called, it will result in accessinga a half-dead splice (since the Java counterpart is dead already). The error reported by the runtime points out that we've failed to find an object for a given id. These problems are perceived as random and are quite hard to reproduce.
Since collection is driven by the garbage collectors it is possible to hold a weak reference to the JavaScript instance of a splice. After a V8 GC, the splice can make the reference to the Java instance weak allowing the Android VM GC to collect it. Then, if before the next V8 GC the JavaScript instance is obtained from the weak reference and its methods are called, it will result in accessing a half-dead splice (since the Java counterpart is dead already). The error reported by the runtime points out that we've failed to find an object for a given id. These problems are perceived as random and are quite hard to reproduce.

#### Splices Die Fast
Multiple splices and JavaScript instances can be created for a single Java object, properties may be lost.
Expand Down
2 changes: 1 addition & 1 deletion docs/core-concepts/plugins.md
Original file line number Diff line number Diff line change
Expand Up @@ -53,7 +53,7 @@ As shown above the command **tns plugin add <plugin-name>** is actually doing **
npm i tns-platform-declarations --save-dev
```

> **Note:** The difference between dependencies and developer dependencies is that **dependencies** are required to run, while **devDependencies** are needed only during development. Example for dependency is the **nativescript-camera** plugin which is required runtime so you could use the hardware camera. On the other hand, the **tns-platform-declarations** is a developer dependency required only for intelliSense during the development process. The `devDependncies` should not be installed as `dependencies` to avoid large output build files (large application size). Example `package.json` file using both `dependencies` and `devDependencies` can be found [here](https://github.com/NativeScript/nativescript-sdk-examples-js/blob/master/package.json#L31-L44).
> **Note:** The difference between dependencies and developer dependencies is that **dependencies** are required to run, while **devDependencies** are needed only during development. Example for dependency is the **nativescript-camera** plugin which is required runtime so you could use the hardware camera. On the other hand, the **tns-platform-declarations** is a developer dependency required only for intelliSense during the development process. The `devDependencies` should not be installed as `dependencies` to avoid large output build files (large application size). Example `package.json` file using both `dependencies` and `devDependencies` can be found [here](https://github.com/NativeScript/nativescript-sdk-examples-js/blob/master/package.json#L31-L44).

## Importing and Using Plugins

Expand Down
8 changes: 4 additions & 4 deletions docs/core-concepts/properties.md
Original file line number Diff line number Diff line change
Expand Up @@ -131,16 +131,16 @@ marginBottomProperty.register(Style);
The `CoercibleProperty` is a property that extends the base Property class by providing the capability to be coercible. For better illustration when a property might need to be coercible let's assume that we are working on `selectedIndex` property of some UI element that can hold different number of `items`. The base case would suggest that the `selectedIndex` would vary within the number of items, but what would cover the case where the items are changed dynamically (and the `selectedIndex` is not within the length range)? This is the case that can be handled by a property that can coerce the value.


Creating the `selectedIndex` as coercible property dependend on the number of items
Creating the `selectedIndex` as coercible property dependent on the number of items
```TypeScript
export const selectedIndexProperty = new CoercibleProperty<SegmentedBarBase, number>({
name: "selectedIndex", defaultValue: -1,
valueChanged: (target, oldValue, newValue) => {
target.notify(<SelectedIndexChangedEventData>{ eventName: SegmentedBarBase.selectedIndexChangedEvent, object: target, oldIndex: oldValue, newIndex: newValue });
},

// in this case the coerse value will change depending on whether the actual number of items
// is more or less than the value we want to appl for selectedIndex
// in this case the coerce value will change depending on whether the actual number of items
// is more or less than the value we want to apply for selectedIndex
coerceValue: (target, value) => {
let items = target.items;
if (items) {
Expand Down Expand Up @@ -280,7 +280,7 @@ Each UI element extends the `View` class (e.g., like `StackLayout` or `Label`) a
> As an alternative, in Angular, we can get reference to the native elements using the `ViewChild` directive and the `nativeElement` property.
> ```HTML
> <StackLayout #myNgStack id="myStackId">
> <Label text="Using ViewChild agains getViewById" />
> <Label text="Using ViewChild against getViewById" />
> </StackLayout>
> ```
> ```TypeScript
Expand Down
Loading