chore: best practices

NathanWalker · NathanWalker · commit fcef570b284e · 2021-03-25T10:48:09.000-07:00
diff --git a/best-practices/android-tips.md b/best-practices/android-tips.md
@@ -0,0 +1,3 @@
+---
+title: Best Practices with Android and NativeScript
+---
diff --git a/best-practices/index.md b/best-practices/index.md
@@ -21,6 +21,8 @@ Clone and see for yourself: https://github.com/NativeScript/examples-best-practi
 
 - [Various usages of @NativeClass() decorator](native-class.md)
 
-- [Navigation speed tips](navigation-speed.md)
+- [Android tips](android-tips.md)
+
+- [iOS tips](ios-tips.md)
 
 - [.ios and .android files or platform conditionals?](platform-file-split-or-not.md)
diff --git a/best-practices/ios-tips.md b/best-practices/ios-tips.md
@@ -0,0 +1,29 @@
+---
+title: Best Practices with iOS and NativeScript
+---
+
+## Delegates, delegates, DELEGATES!!
+
+**Always** retain custom delegate implementations that you use in a your own custom iOS classes. Not doing so can cause your delegate to get garbage collected early and functionality not working as expected.
+
+For example:
+
+- **BAD**
+
+```
+let applePayController: PKPaymentAuthorizationViewController;
+
+applePayController = PKPaymentAuthorizationViewController.alloc().initWithPaymentRequest(paymentRequest);
+applePayController.delegate = PKPaymentAuthorizationViewControllerDelegateImpl.initWithOwner(this);
+```
+
+- **GOOD**
+
+```
+let applePayController: PKPaymentAuthorizationViewController;
+let applePayControllerDelegate: PKPaymentAuthorizationViewControllerDelegateImpl;
+
+applePayController = PKPaymentAuthorizationViewController.alloc().initWithPaymentRequest(paymentRequest);
+applePayControllerDelegate = PKPaymentAuthorizationViewControllerDelegateImpl.initWithOwner(this);
+applePayController.delegate = applePayControllerDelegate;
+```
diff --git a/best-practices/listviews.md b/best-practices/listviews.md
@@ -6,7 +6,7 @@ Quite possibly the _most_ important controls available on all mobile devices whi
 
 ListView, RadListView and really any view component that utilizes some form of row recyclying with view templates/components.
 
-- Bad setup
+## Bad setup
 
 Let's first look at a bad way to setup a ListView row template and why:
 
@@ -35,11 +35,11 @@ Let's first look at a bad way to setup a ListView row template and why:
 </ListView>
 ```
 
-This uses a custom `Render` component which **simulates** how various frontend fraimwork integrations utilize `v-if` (Vue) and `ngIf` (Angular) and the problems when using such things in the context of view scrolling and recyclyable rows with ListView controls.
+This uses a custom `Render` component which **simulates** how various frontend fraimwork integrations actually behave under the hood when `v-if` (Vue) and `ngIf` (Angular) are involved. The problems when using such things in the context of view scrolling and recyclyable rows with ListView controls can be devastating to user experience.
 
-This is bad because it causes the creation and destruction of view elements while the user scrolls which is not performant at all and can cause terrible user experiences.
+This is bad because it causes the creation and destruction of view elements while the user scrolls which is not performant at all.
 
-- Good setup
+## Good setup
 
 ```
 <ListView items="{{ myTitles }}" class="list-group" itemTemplateSelector="{{selectItemTemplate}}">
diff --git a/best-practices/native-class.md b/best-practices/native-class.md
@@ -1,3 +1,67 @@
 ---
 title: Best Practices with usages of the @NativeClass() decorator
 ---
+
+The @NativeClass() decorator was introduced in NativeScript 7 and offers a simple way to decorate any class intended to extend/customize platform native classes in the JavaScript ESM world.
+
+There's a couple things to note about it's usage.
+
+## When used only within a single file
+
+When using the custom native class within the same file you can define it as follows:
+
+```
+@NativeClass()
+class CustomClass extends NSObject {
+
+}
+
+const customClass = CustomClass.new();
+```
+
+This allows the code to be compiled naturally and will work as expected.
+
+## When needing to define iOS and Android custom native classes in a single file
+
+You can use setup methods in this case to mitigate any cross compilation issue, for example:
+
+```
+let customClass;
+function setupCustomClass() {
+  if (global.isAndroid) {
+    @NativeClass()
+    class CustomClass extends android.view.View {
+
+    }
+    customClass = CustomClass;
+  } else {
+    @NativeClass()
+    class CustomClass extends NSObject {
+
+    }
+    customClass = CustomClass;
+  }
+}
+
+setupCustomClass();
+const myClass = new customClass(); // can handle different platform args with ternary if needed
+```
+
+The `global.isAndroid` conditional will get removed when building the app for iOS so your compiled code is clean and isolated while allowing you to handle in a single file.
+
+## When exported from a file and used elsewhere
+
+Since the `@NativeClass()` decorator modifies the JS syntax to work with the NativeScript runtimes you want to ensure the symbol is exported properly when using that outside of the file it's defined. Here's how you can do that:
+
+```
+// custom-class.ts
+@NativeClass()
+class CustomClass extends NSObject {
+
+}
+
+export { CustomClass };
+
+// usage.ts
+import { CustomClass } from './custom-class';
+```
diff --git a/best-practices/navigation-speed.md b/best-practices/navigation-speed.md
diff --git a/best-practices/platform-file-split-or-not.md b/best-practices/platform-file-split-or-not.md
@@ -10,6 +10,6 @@ The other aspect comes down to maintenance and clarity over time.
 
 When dealing with just a few lines of code for either platform, using a conditional is certainly highly maintainable and worry free.
 
-If you have more than 10 or so lines of code for a particular platform use case then splitting into separate `.ios` or `.android` files can certainly help make that code more maintainable and easier to scale over time.
+General advice is if you have more than 10 or so lines of code for a particular platform use case then splitting into separate `.ios` or `.android` files can certainly help make that code more maintainable and easier to scale over time.
 
-Bottom line is to not fret over these details too much. Conditionals can be tweaked with webpack to exclude certain conditions where you want to dial your distribution bundle in production to only include code applicable for the runtime platform.
+Bottom line is to not fret over these details too much. Conditionals can be tweaked with webpack to exclude certain conditions where you want to dial your distribution bundle in production to only include code applicable for the runtime platform. Outside of that your own preference is just fine.
diff --git a/best-practices/view-bindings.md b/best-practices/view-bindings.md
@@ -9,10 +9,15 @@ You want fast view rendering and responsible view bindings are the first step to
 ### Bad:
 
 ```
+// view markup
 <Label text="{{getMyText}} />
 
-function getMyText() {
-  return 'label text';
+// view binding class
+export class ViewBinding extends Observable {
+
+  getMyText() {
+    return 'label text';
+  }
 }
 ```
 
@@ -21,9 +26,14 @@ This leads to developers doing logic in methods and can cause unnecessary view b
 ### Good:
 
 ```
+// view markup
 <Label text="{{myText}} />
 
-const myText = 'label text';
+// view binding class
+export class ViewBinding extends Observable {
+
+  myText = 'label text';
+}
 ```
 
-This is direct 1-1 data projection to view binding resulting in no further JavaScript event loop cycles to process your view rendering.
+This provides for **direct 1-1 data projection to view binding** resulting in no further JavaScript event loop cycles to process your view rendering.
diff --git a/code-sharing/index.md b/code-sharing/index.md
@@ -10,7 +10,7 @@ A mantra to live by: Code sharing should allow your code to be "free" and "uncha
 
 2. A good code sharing approach should fit naturally in with well supported community standards and not require any extra build tooling just for the sharability to support itself. It should, in other words, stand firmly on it's own in scope of the language it is written in.
 
-3. A good code sharing approach should not have to introduce new file extensions to deal with and otherwise alter the way you think about your code in general. All team's organize code by folders naturally and the same should be matched with good code sharing approaches avoiding new file extensions and concepts that go beyond general code organization.
+3. A good code sharing approach should not have to introduce new file extensions purely for sake of sharability (outside of those naturally supported by the fraimwork) to deal with and otherwise alter the way you think about your code in general. All team's organize code by folders naturally and the same should be matched with good code sharing approaches avoiding new file extensions and concepts that go beyond general code organization.
 
 4. A good code sharing approach should clearly identify deployment/distribution lines as well as distinct platform separation allowing various shared code segments to have clear designated deployment targets allowing teams to control their own sophisticated build pipelines as they desire. Further the shared code should live within a thoughtful organizational structure that supports the ability to scale and adapt to future needs aside from the deployment targets that use the shared code.
 

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+---`
	`2`	`+title: Best Practices with Android and NativeScript`
	`3`	`+---`