You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
<p>As you build more complex apps, you'll likely run into functionality that is not implemented in the NativeScript modules. But no worries, as NativeScript lets you leverage <ahref="https://www.npmjs.com/">npm</a> (node package manager) to import npm modules into your apps. Alternately, you can install NativeScript plugins, which are simply npm modules that can access native code and use Android and iOS SDKs, if required. </p>
1316
+
<p>In this chapter, you'll install and use and external email validator module to verify the format of email addresses as they are entered on the registration screen. Then, you'll add a NativeScript plugin, <ahref="https://www.npmjs.com/package/nativescript-social-share">NativeScript social share</a>, to let users share their grocery lists using their device's native sharing widget.</p>
1317
+
<h3id="using-an-npm-module-in-your-app">Using an npm module in your app</h3>
1318
+
<p>It would be nice to be able to make sure people are entering well-formatted email addresses into your app on the registration screen. You could write this functionality yourself, but validating email addresses is <ahref="http://stackoverflow.com/questions/46155/validate-email-address-in-javascript">surprisingly tricky</a>, and it's a lot easier to use one of many npm modules that already provide this validation. For Groceries let's see how to add this <ahref="https://www.npmjs.com/package/email-validator">email-validator module</a> to test for valid addresses.</p>
1319
+
<h4class="exercise-start">
1320
+
<b>Exercise</b>: Install the email validator module
1321
+
</h4>
1322
+
1323
+
<p>Return to your terminal and make sure that you are working in the root directory in your Groceries project folder, a.k.a. here:</p>
1324
+
<divclass="no-copy-button"></div>
1325
+
1326
+
<pre><code>sample-Groceries <----------------
1327
+
├── app
1328
+
│ └── ...
1329
+
├── package.json
1330
+
└── platforms
1331
+
├── android
1332
+
└── ios
1333
+
</code></pre><p>From the root directory install the email-validator module:</p>
1334
+
<pre><code>npm install email-validator --save
1335
+
</code></pre><divclass="exercise-end"></div>
1336
+
1337
+
<p>The install process does a few things in the background. First, because you added the <code>--save</code> flag, npm records this dependency in your app's <code>package.json</code>. If you open your <code>package.json</code> you should see <code>"email-validator"</code> in your app's <code>"dependencies"</code> array.</p>
<p>The npm CLI also creates a <code>node_modules</code> folder in the root of your app. This folder contains the code for the email-validator module, which is a bit of validation logic in <code>node_modules/email_validator/index.js</code>. </p>
1343
+
<blockquote>
1344
+
<p><strong>TIP</strong>: By saving your app's npm dependencies in your <code>package.json</code> file, you can always regenerate your <code>node_modules</code> folder by running <code>npm install</code>. Because of this, it's a common practice to exclude the <code>node_modules</code> folder from source control. The Groceries app uses git for source control, and as such includes <code>node_modules/</code> in its <code>.gitignore</code>.</p>
1345
+
</blockquote>
1346
+
<p>Now that you have the module installed let's look at how to use it.</p>
1347
+
<h4class="exercise-start">
1348
+
<b>Exercise</b>: Use the email validator module
1349
+
</h4>
1350
+
1351
+
<p>Open <code>/app/shared/user/user.ts</code> and replace the existing contents of the file with the code below:</p>
<p><strong>NOTE</strong>: The NativeScript framework's <code>require()</code> method is configured to look at the <code>"main"</code> value in an npm module's <code>package.json</code> file. In the case of this module, the <code>"main"</code> value is <code>"index.js"</code>. Therefore, when you run <code>require("email-validator")</code>, you're actually requiring the file at <code>node_modules/email_validator/index.js</code>. You could also type <code>require("email-validator/index")</code> to retrieve the same file.</p>
1364
+
</blockquote>
1365
+
<p>To make use of this validator, open <code>app/pages/login/login.component.ts</code> and paste the following code at the beginning of the existing <code>submit()</code> function:</p>
<p>In general npm modules greatly expand the number of things you're able to do in your NativeScript apps. Need date and time formatting? Use <ahref="https://www.npmjs.com/package/moment">moment</a>. Need utility functions for objects and arrays? Use <ahref="https://www.npmjs.com/package/lodash">lodash</a> or <ahref="https://www.npmjs.com/package/underscore">underscore</a>. This code reuse benefit gets even more powerful when you bring NativeScript plugins into the picture.</p>
1376
+
<blockquote>
1377
+
<p><strong>WARNING</strong>: Not all npm modules work in NativeScript apps. Specifically, modules that depend on Node.js or browser APIs will not work, as those APIs do not exist in NativeScript. The NativeScript wiki contains a <ahref="https://github.com/NativeScript/NativeScript/wiki/supported-npm-modules">list of some of the more popular npm modules that have been verified to work in NativeScript apps</a>.</p>
1378
+
</blockquote>
1379
+
<h3id="using-a-nativescript-plugin-in-your-app">Using a NativeScript plugin in your app</h3>
1380
+
<p>NativeScript plugins are npm modules that have the added ability to run native code and use iOS and Android frameworks. Because NativeScript plugins are just npm modules, a lot of the techniques you learned in the previous section still apply. The one big difference is in the command you use to install plugins. Let's look at how it works by installing the NativeScript social share plugin.</p>
1381
+
<h4class="exercise-start">
1382
+
<b>Exercise</b>: Install the social sharing plugin
1383
+
</h4>
1384
+
1385
+
<p>Return to your terminal, make sure you're still in the root of your app, and run the following command:</p>
<p>The install process does the same thing that the <code>npm install</code> command does—including retrieving the module from npm, installing the module in <code>node_modules</code>, and saving the module as a dependency in your app's <code>package.json</code>—but the <code>tns plugin add</code> command additionally configures any native code that the plugin needs to use.</p>
1390
+
<p>For example the <ahref="https://github.com/NativeScript/push-plugin">NativeScript push plugin</a> uses both iOS and Android SDKs, and the <code>tns plugin add</code> command takes care of installing those. The <ahref="https://github.com/tjvantoll/nativescript-flashlight">NativeScript flashlight plugin</a> needs permissions to use the camera on Android, and the <code>tns plugin add</code> command takes care of setting that up too.</p>
1391
+
<p>Now that you've installed the social share plugin, let's look at how to use it.</p>
1392
+
<h4class="exercise-start">
1393
+
<b>Exercise</b>: Use the social sharing plugin
1394
+
</h4>
1395
+
1396
+
<p>Open <code>app/pages/list/list.component.ts</code> and add the following line at the top of the file, which requires the social share module you just installed:</p>
<p>Next you have to build some UI that lets you share a grocery list. To do so, open <code>app/pages/list/list.html</code> and add the following code at the very top of the file:</p>
<p>This code defines an <ahref="{{site.baseurl}}/ApiReference/ui/action-bar/ActionBar">ActionBar</a>, which is a UI component that includes various menu items, or <code><ActionItem></code> components.</p>
1405
+
<blockquote>
1406
+
<p><strong>NOTE</strong>: On iOS devices, <code><ActionItem></code>s are placed from left to right in sequence; you can override that (as the code above does) by providing an <code>ios.position</code> attribute.</p>
1407
+
</blockquote>
1408
+
<p>Next, to add a bit of styling to this new <code><ActionBar></code>, add the following CSS to your <code>app/app.css</code> file:</p>
1409
+
<pre><codeclass="lang-CSS">ActionBar {
1410
+
background-color: black;
1411
+
color: white;
1412
+
}
1413
+
</code></pre>
1414
+
<p>Finally, now that you’ve installed and required the plugin, and setup a UI to use it, your last step is implementing the <code><ActionItem></code>'s <code>tap</code> handler (<code>share()</code>). Open <code>app/pages/list/list.component.ts</code> again and add the following function to the <code>ListPage</code> class:</p>
1415
+
<pre><codeclass="lang-TypeScript">share() {
1416
+
var list = [];
1417
+
for (var i = 0, size = this.groceryList.length; i < size ; i++) {
1418
+
list.push(this.groceryList[i].name);
1419
+
}
1420
+
var listString = list.join(", ").trim();
1421
+
socialShare.shareText(listString);
1422
+
}
1423
+
</code></pre>
1424
+
<divclass="exercise-end"></div>
1425
+
1426
+
<p>This code takes the grocery data from the grocery list array, converts the data into a comma-separated string, and passes that string to the social share plugin’s <code>shareText()</code> method.</p>
1427
+
<p>Now when you run the app, you'll see a new button at the top of the screen. When you tap it, the native iOS or Android sharing widget will show to let you post your groceries to your social networks, or send them via email, message, or any other method you prefer.</p>
1428
+
<p>TODO: Images</p>
1429
+
<p>Pretty cool, huh? The ability to use npm modules greatly expands the number of things you're able to do in a NativeScript app. Need to compose emails in your app? Try out the <ahref="https://www.npmjs.com/package/nativescript-email">NativeScript email plugin</a>. Need to use the clipboard in your app? Try out the <ahref="https://www.npmjs.com/package/nativescript-clipboard">NativeScript clipboard plugin</a>.</p>
1430
+
<p>If you're looking for NativeScript plugins start by searching both the <ahref="http://plugins.telerik.com/nativescript">NativeScript Plugins Marketplace</a> and <ahref="https://www.npmjs.com/search?q=nativescript">npm</a>. If you don't find the plugin you need, you can <ahref="https://nativescript.ideas.aha.io/">request the plugin on our ideas portal</a>, or you can take a stab at <ahref="https://docs.nativescript.org/plugins">creating the plugin yourself</a>.</p>
1431
+
<p>Between NativeScript modules, npm modules, and NativeScript plugins, the NativeScript framework provides a lot of functionality you can use to build your next app. However, we've yet to talk about NativeScript's most powerful feature: the ability to directly access iOS and Android APIs in JavaScript. Let's look at how it works.</p>
0 commit comments