Skip to content

Commit b542f06

Browse files
vallemarvallemar
authored
docs: improve native code and typings docs (#129)
1 parent 0b03937 commit b542f06

File tree

6 files changed

+295
-121
lines changed

6 files changed

+295
-121
lines changed

‎content/guide/adding-native-code.md

+10-25
Original file line numberDiff line numberDiff line change
@@ -5,34 +5,19 @@ contributors:
55
- Ombuweb
66
- NathanWalker
77
- rigor789
8+
- vallemar
89
---
910

1011
If the native API you need is not exposed through [@nativescript/core](/core/#nativescript-core), [third party plugins](https://market.nativescript.org/) or [@nativescript/\* plugins](https://v8.docs.nativescript.org/plugins/index.html)), you can add it to your project and access it right away in TypeScript.
1112

12-
1. Add native code to [App_Resources](/project-structure/app-resources). For example, see
13+
1. Add native code to [App_Resources](/project-structure/app-resources):
14+
- [Adding Java/Kotlin code to an application](/guide/native-code/android)
15+
- [Adding ObjectiveC/Swift Code to an application](/guide/native-code/ios)
16+
2. Optionally [generate TypeScript types for the added APIs](/guide/native-code/generate-typings)
1317

14-
- [Adding Java/Kotlin code to an application](/project-structure/app-resources#adding-native-code-to-an-application)
15-
- [Adding ObjectiveC/Swift Code to an application](/project-structure/app-resources#adding-objectivec-swift-code-to-an-application)
18+
Additionally, NativeScript also supports Jetpack Compose and SwiftUI through plugins.
1619

17-
2. Generate types for the added APIs
18-
For iOS types run:
19-
20-
```cli
21-
ns typings ios
22-
```
23-
24-
For Android run:
25-
26-
```cli
27-
ns typings android --jar <path to a jar>
28-
# or
29-
ns typings android --aar <path to an aar>
30-
```
31-
32-
3. Reference the generated types in [references.d.ts](/project-structure/references-d-ts)
33-
34-
4. You can now code against the platform native APIs (_strongly typed_). For various examples on how to interact with native APIs in JavaScript/TypeScript, visit the [Subclassing](/guide/subclassing/), [iOS Marshalling](/guide/ios-marshalling) and [Android Marshalling](/guide/android-marshalling) pages.
35-
36-
## Additional Resources
37-
38-
- [Android d.ts Generator](https://github.com/NativeScript/android-dts-generator), for advanced types generation for Android
20+
1. [Jetpack Compose Plugin](/plugins/jetpack-compose)
21+
- [Jetpack Compose Introduction and example](https://dev.to/valorsoftware/introduction-to-jetpack-compose-for-nativescript-54d7)
22+
2. [SwiftUI Plugin](/plugins/swift-ui)
23+
- [SwiftUI Introduction and example](https://dev.to/valorsoftware/introduction-to-swiftui-for-nativescript-4m1b)

‎content/guide/native-code/android.md

+116
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
---
2+
title: Adding Java/Kotlin Code to an application
3+
contributors:
4+
- Ombuweb
5+
- NathanWalker
6+
- rigor789
7+
- vallemar
8+
---
9+
10+
## Adding native code to an application
11+
12+
There are different ways to add native code to an Android application. You can add `.jar` and `.aar` files, or Java/Kotlin source files in `App_Resources/Android/libs` and `App_Resources/Android/src` respectively.
13+
14+
```bash
15+
App_Resources/
16+
├─ Android/
17+
│ ├─ app.gradle
18+
│ ├─ libs/
19+
│ │ ├─ HelloAndroidLib.aar # Android Archive
20+
│ │ └─ HelloJavaLib.jar # Java Archive
21+
│ └─ src/
22+
│ └─ main/
23+
│ ├─ java/
24+
│ │ ├─ com/example/HelloKotlin.kt # Kotlin source code
25+
│ │ └─ com/example/HelloJava.java # Java source code
26+
│ └─ res/
27+
└─ ... more
28+
```
29+
30+
## Adding Java code
31+
32+
Define the java file in `App_Resources/Android/src/main/java`.
33+
34+
```java
35+
// HelloJava.java
36+
package com.example;
37+
38+
public class HelloJava {
39+
public String getString() {
40+
return "Hello from Java!";
41+
}
42+
}
43+
```
44+
45+
Given the example above, your JavaScript or TypeScript code can reference the Java code by using the full class name:
46+
47+
```typescript
48+
const helloJava = new com.example.HelloJava()
49+
console.log('Java says: ' + helloJava.getString())
50+
// prints: Java says: Hello from Java!
51+
```
52+
53+
:::tip Note
54+
55+
When using TypeScript, you may need to [generate typings](/guide/native-code/generate-typings), or alternatively declare the top level package name as `any`.
56+
57+
```typescript
58+
declare const com: any
59+
```
60+
61+
:::
62+
63+
## Adding Kotlin code
64+
65+
### Configuring Kotlin
66+
67+
#### Enable kotlin
68+
69+
When using Kotlin, it must be enabled first.
70+
71+
Set `useKotlin=true` in `App_Resources/Android/gradle.properties` (create the file if it doesn't exist).
72+
73+
```ini
74+
useKotlin=true
75+
```
76+
77+
#### Configure Kotlin version
78+
79+
Configure the version of Kotlin to use in the application in `App_Resources/Android/before-plugins.gradle` (create the file if it doesn't exist).
80+
81+
```groovy
82+
project.ext {
83+
kotlinVersion = "1.9.10"
84+
}
85+
```
86+
87+
### Using kotlin
88+
89+
Define the kotlin file in `App_Resources/Android/src/main/java`.
90+
91+
```kotlin
92+
// HelloKotlin.kt
93+
package com.example
94+
95+
class HelloKotlin {
96+
val hello = "Hello from Kotlin!"
97+
}
98+
```
99+
100+
Given the example above, your JavaScript or TypeScript code can reference the Kotlin code by using the full class name:
101+
102+
```typescript
103+
const helloKotlin = new com.example.HelloKotlin()
104+
console.log('Kotlin says: ' + helloKotlin.hello)
105+
// prints: Kotlin says: Hello from Kotlin!
106+
```
107+
108+
:::tip Note
109+
110+
When using TypeScript, you may need to [generate typings](/guide/native-code/generate-typings), or alternatively declare the top level package name as `any`.
111+
112+
```typescript
113+
declare const com: any
114+
```
115+
116+
:::

‎content/guide/native-code/generate-typings.md

+34
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
---
2+
title: Generating TypeScript types
3+
contributors:
4+
- Ombuweb
5+
- NathanWalker
6+
- rigor789
7+
---
8+
9+
## Generate types for iOS
10+
11+
```cli
12+
ns typings ios
13+
```
14+
15+
This will generate the following folder structure `typings/ios/arm64`
16+
17+
## Generate types for Android
18+
19+
For Android run:
20+
21+
```cli
22+
ns typings android --jar <path to a jar>
23+
# or
24+
ns typings android --aar <path to an aar>
25+
```
26+
27+
### Custom code
28+
29+
1. Reference the generated types in [references.d.ts](/project-structure/references-d-ts)
30+
2. You can now code against the platform native APIs (_strongly typed_). For various examples on how to interact with native APIs in JavaScript/TypeScript, visit the [Subclassing](/guide/subclassing/), [iOS Marshalling](/guide/ios-marshalling) and [Android Marshalling](/guide/android-marshalling) pages.
31+
32+
## Additional Resources
33+
34+
- [Android d.ts Generator](https://github.com/NativeScript/android-dts-generator), for advanced types generation for Android

‎content/guide/native-code/ios.md

+119
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
---
2+
title: Adding ObjectiveC/Swift Code to an application
3+
contributors:
4+
- Ombuweb
5+
- NathanWalker
6+
- rigor789
7+
- vallemar
8+
---
9+
10+
You can add Objective-C/Swift source files to `App_Resources/iOS/src`. For Objective-C files, create a `.modulemap` file. To add a [CocoaPod](https://guides.cocoapods.org/using/getting-started.html), edit `App_Resources/iOS/Podfile`:
11+
12+
```bash
13+
App_Resources/
14+
├─ iOS/
15+
│ ├─ src/
16+
│ │ ├─ Shimmer.swift
17+
│ │ ├─ Shimmer.h
18+
│ │ ├─ Shimmer.m
19+
│ │ └─ module.modulemap
20+
│ └─ Podfile
21+
└─ ... more
22+
```
23+
24+
### Adding Swift code
25+
26+
Define the swfit file in `App_Resources/iOS/src`.
27+
28+
```swift
29+
// HelloSwift.swift
30+
import UIKit
31+
32+
class HelloSwift: NSObject {
33+
@objc public var stringToReturn: String = "Hello from Swift!"
34+
35+
@objc public func getString() -> String {
36+
return stringToReturn;
37+
}
38+
}
39+
```
40+
41+
Given the example above, your JavaScript or TypeScript code can reference the Swift code by using the full class name:
42+
43+
```ts
44+
const helloSwift = new HelloSwift()
45+
helloSwift.stringToReturn = 'Custom hello from Swift!'
46+
console.log(helloSwift.getString())
47+
// prints: Custom hello from Swift!
48+
```
49+
50+
#### Using `@objc`
51+
52+
`@objc` allows exposing variables and functions to use them from JS/TS, note that in the example the variables and methods have this notation.
53+
54+
#### Using `@objcMembers`
55+
56+
A shortcut to the `@objc` notation is to use the `@objcMembers` notation at the class level to make the entire class accessible.
57+
58+
```swift
59+
// HelloSwift.swift
60+
import UIKit
61+
62+
@objcMembers
63+
class HelloSwift: NSObject {
64+
public var stringToReturn: String = "Hello from Swift!"
65+
66+
public func getString() -> String {
67+
return stringToReturn;
68+
}
69+
}
70+
```
71+
72+
<!---
73+
TODO: add Objective-C code
74+
### Adding Objective-C code
75+
76+
Define the Objective-C code within the path `App_Resources/iOS/src`.
77+
78+
### Create extension
79+
```swift
80+
// UIViewExtension.swift
81+
import UIKit
82+
83+
extension UIView {
84+
@objc func removeAllSubViews() {
85+
for view in self.subviews {
86+
view.removeFromSuperview()
87+
}
88+
}
89+
}
90+
```
91+
92+
```objc
93+
// UIView+Extension.h
94+
#import <UIKit/UIKit.h>
95+
96+
@interface UIView (SDExtension)
97+
98+
- (void) removeAllSubViews;
99+
100+
@end
101+
```
102+
103+
```objc
104+
// UIView+Extension.m
105+
#import "UIView+SDExtension.h"
106+
107+
@implementation UIView (SDExtension)
108+
109+
- (void) removeAllSubViews
110+
{
111+
for (int i = 0; i < [[self subviews] count]; i++ ) {
112+
[[[self subviews] objectAtIndex:i] removeFromSuperview];
113+
}
114+
}
115+
116+
@end
117+
```
118+
119+
-->

0 commit comments

Comments
 (0)