"Fossies" - the Fresh Open Source Software Archive

Member "angular-1.8.2/docs/partials/tutorial.html" (21 Oct 2020, 17438 Bytes) of package /linux/www/angular-1.8.2.zip:

As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) HTML source code syntax highlighting (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 <a href='https://github.com/angular/angular.js/edit/v1.8.x/docs/content/tutorial/index.ngdoc?message=docs(tutorial%2FTutorial)%3A%20describe%20your%20change...' class='improve-docs btn btn-primary'><i class="glyphicon glyphicon-edit">&nbsp;</i>Improve this Doc</a>
    4 <h1 id="phonecat-tutorial-app">PhoneCat Tutorial App</h1>
    5 <p>A great way to get introduced to AngularJS is to work through this tutorial, which walks you through
    6 the construction of an AngularJS web app. The app you will build is a catalog that displays a list
    7 of Android devices, lets you filter the list to see only devices that interest you, and then view
    8 details for any device.</p>
    9 <p><img class="diagram" src="img/tutorial/catalog_screen.png" width="488" height="413"
   10     alt="demo application running in the browser"></p>
   11 <p>Follow the tutorial to see how AngularJS makes browsers smarter — without the use of native
   12 extensions or plug-ins:</p>
   13 <ul>
   14 <li>See examples of how to use client-side data binding to build dynamic views of data that change
   15 immediately in response to user actions.</li>
   16 <li>See how AngularJS keeps your views in sync with your data without the need for DOM manipulation.</li>
   17 <li>Learn a better, easier way to test your web apps, with Karma and Protractor.</li>
   18 <li>Learn how to use dependency injection and services to make common web tasks, such as getting data
   19 into your app, easier.</li>
   20 </ul>
   21 <p>When you finish the tutorial you will be able to:</p>
   22 <ul>
   23 <li>Create a dynamic application that works in all modern browsers.</li>
   24 <li>Use data binding to wire up your data model to your views.</li>
   25 <li>Create and run unit tests, with Karma.</li>
   26 <li>Create and run end-to-end tests, with Protractor.</li>
   27 <li>Move application logic out of the template and into components and controllers.</li>
   28 <li>Get data from a server using AngularJS services.</li>
   29 <li>Apply animations to your application, using the <code>ngAnimate</code> module.</li>
   30 <li>Structure your AngularJS applications in a modular way that scales well for larger projects.</li>
   31 <li>Identify resources for learning more about AngularJS.</li>
   32 </ul>
   33 <p>The tutorial guides you through the entire process of building a simple application, including
   34 writing and running unit and end-to-end tests. Experiments at the end of each step provide
   35 suggestions for you to learn more about AngularJS and the application you are building.</p>
   36 <p>You can go through the whole tutorial in a couple of hours or you may want to spend a pleasant day
   37 really digging into it. If you&#39;re looking for a shorter introduction to AngularJS, check out the
   38 <a href="misc/started">Getting Started</a> document.</p>
   39 <h1 id="environment-setup">Environment Setup</h1>
   40 <p>The rest of this page explains how you can set up your local machine for development.
   41 If you just want to <em>read</em> the tutorial, you can go straight to the first step:
   42 <a href="tutorial/step_00">Step 0 - Bootstrapping</a>.</p>
   43 <h2 id="working-with-the-code">Working with the Code</h2>
   44 <p>You can follow along with this tutorial and hack on the code in the comfort of your own computer.
   45 This way, you can get hands-on practice of really writing AngularJS code and also on using the
   46 recommended testing tools.</p>
   47 <p>The tutorial relies on the use of the <a href="https://git-scm.com/">Git</a> versioning system for source code management.
   48 You don&#39;t need to know anything about Git to follow the tutorial other than how to install and run
   49 a few git commands.</p>
   50 <h3 id="install-git">Install Git</h3>
   51 <p>You can download and install Git from <a href="https://git-scm.com/download">https://git-scm.com/download</a>. Once installed, you should have
   52 access to the <code>git</code> command line tool. The main commands that you will need to use are:</p>
   53 <ul>
   54 <li><code>git clone ...</code>: Clone a remote repository onto your local machine.</li>
   55 <li><code>git checkout ...</code>: Check out a particular branch or a tagged version of the code to hack on.</li>
   56 </ul>
   57 <h3 id="download-angular-phonecat">Download angular-phonecat</h3>
   58 <p>Clone the <a href="https://github.com/angular/angular-phonecat">angular-phonecat repository</a> located at GitHub by running the following
   59 command:</p>
   60 <pre><code>git clone --depth=16 https://github.com/angular/angular-phonecat.git
   61 </code></pre>
   62 <p>This command creates an <code>angular-phonecat</code> sub-directory in your current directory.</p>
   63 <div class="alert alert-info">
   64   The <code>--depth=16</code> option tells Git to pull down only the last 16 commits.
   65   This makes the download much smaller and faster.
   66 </div>
   68 <p>Change your current directory to <code>angular-phonecat</code>.</p>
   69 <pre><code>cd angular-phonecat
   70 </code></pre>
   71 <p>The tutorial instructions, from now on, assume you are running all commands from within the
   72 <code>angular-phonecat</code> directory.</p>
   73 <h3 id="install-node-js">Install Node.js</h3>
   74 <p>In order to install dependencies (such as the test tools and AngularJS itself) and run the
   75 preconfigured local web server, you will also need <a href="https://nodejs.org/">Node.js v6+</a>.</p>
   76 <p>You can download a Node.js installer for your operating system from <a href="https://nodejs.org/en/download/">https://nodejs.org/en/download/</a>.</p>
   77 <p>Check the version of Node.js that you have installed by running the following command:</p>
   78 <pre><code>node --version
   79 </code></pre>
   80 <p>In Debian based distributions, there might be a name clash with another utility called <code>node</code>. The
   81 suggested solution is to also install the <code>nodejs-legacy</code> apt package, which renames <code>node</code> to
   82 <code>nodejs</code>.</p>
   83 <pre><code>apt-get install nodejs-legacy npm
   84 nodejs --version
   85 npm --version
   86 </code></pre>
   87 <div class="alert alert-info">
   88   If you need to run different versions of Node.js in your local environment, consider installing
   89   <a href="https://github.com/creationix/nvm">Node Version Manager (nvm)</a> or <a href="https://github.com/coreybutler/nvm-windows">Node Version Manager (nvm) for Windows</a>.
   90 </div>
   92 <p>By installing Node.js, you also get <a href="https://www.npmjs.com/">npm</a>, which is a command line executable for downloading
   93 and managing Node.js packages. We use it to download the AngularJS framework as well as development
   94 and testing tools.</p>
   95 <p>Once you have Node.js installed on your machine, you can download these dependencies by running:</p>
   96 <pre><code>npm install
   97 </code></pre>
   98 <p>This command reads angular-phonecat&#39;s <code>package.json</code> file and downloads the following dependencies
   99 into the <code>node_modules</code> directory:</p>
  100 <ul>
  101 <li><a href="https://github.com/nodeapps/http-server">Http-Server</a> - simple local static web server</li>
  102 <li><a href="https://karma-runner.github.io/">Karma</a> - unit test runner</li>
  103 <li><a href="https://github.com/angular/protractor">Protractor</a> - end-to-end (E2E) test runner</li>
  104 </ul>
  105 <p>Running <code>npm install</code> will also automatically copy the AngularJS framework and other dependencies
  106 necessary for our app to work into the <code>app/lib/</code> directory.</p>
  107 <div class="alert alert-info">
  108   Note the angular-phonecat project is setup to install and run these utilities via npm scripts.
  109   This means that you do not have to have any of these utilities installed globally on your system
  110   to follow the tutorial. See <a href="tutorial/#install-helper-tools-optional-">Installing Helper Tools</a>
  111   below for more information.
  112 </div>
  114 <p>The project is preconfigured with a number of npm helper scripts to make it easy to run the common
  115 tasks that you will need while developing:</p>
  116 <ul>
  117 <li><code>npm start</code>: Start a local development web server.</li>
  118 <li><code>npm test</code>: Start the Karma unit test runner.</li>
  119 <li><code>npm run protractor</code>: Run the Protractor end-to-end (E2E) tests.</li>
  120 <li><code>npm run update-webdriver</code>: Install the drivers needed by Protractor.</li>
  121 </ul>
  122 <h3 id="install-helper-tools-optional-">Install Helper Tools (optional)</h3>
  123 <p>The Http-Server, Karma and Protractor modules are also executables, which can be installed globally
  124 and run directly from a terminal/command prompt. You don&#39;t need to do this to follow the tutorial,
  125 but if you decide you do want to run them directly, you can install these modules globally using,
  126 <code>sudo npm install --global ...</code>.</p>
  127 <p>For instance, to install the <code>http-server</code> command line executable you would do:</p>
  128 <pre><code>sudo npm install --global http-server
  129 </code></pre>
  130 <p><em>(Omit the sudo if running on Windows.)</em></p>
  131 <p>Then you can run the <code>http-server</code> tool directly, such as:</p>
  132 <pre><code>http-server ./app
  133 </code></pre>
  134 <h3 id="running-the-development-web-server">Running the Development Web Server</h3>
  135 <p>While AngularJS applications are purely client-side code, and it is possible to open them in a web
  136 browser directly from the file system, it is better to serve them from an HTTP web server. In
  137 particular, for security reasons, most modern browsers will not allow JavaScript to make server
  138 requests if the page is loaded directly from the file system.</p>
  139 <p>The angular-phonecat project is configured with a simple static web server for hosting the
  140 application during development. Start the web server by running:</p>
  141 <pre><code>npm start
  142 </code></pre>
  143 <p>This will create a local web server that is listening to port 8000 on your local machine.
  144 You can now browse to the application at <a href="http://localhost:8000/index.html">http://localhost:8000/index.html</a>.</p>
  145 <div class="alert alert-info">
  146   To serve the web app on a different IP address or port, edit the &quot;start&quot; script within
  147   <code>package.json</code>. You can use <code>-a</code> to set the address and <code>-p</code> to set the port. You also need to
  148   update the <code>baseUrl</code> configuration property in <code>e2e-test/protractor.conf.js</code>.
  149 </div>
  152 <h3 id="running-unit-tests">Running Unit Tests</h3>
  153 <p>We use unit tests to ensure that the JavaScript code in our application is operating correctly.
  154 Unit tests focus on testing small isolated parts of the application. The unit tests are kept in test
  155 files (specs) side-by-side with the application code. This way it&#39;s easier to find them and keep
  156 them up-to-date with the code under test. It also makes refactoring our app structure easier, since
  157 tests are moved together with the source code.</p>
  158 <p>The angular-phonecat project is configured to use <a href="https://karma-runner.github.io/">Karma</a> to run the unit tests for the
  159 application. Start Karma by running:</p>
  160 <pre><code>npm test
  161 </code></pre>
  162 <p>This will start the Karma unit test runner. Karma will read the configuration file <code>karma.conf.js</code>,
  163 located at the root of the project directory. This configuration file tells Karma to:</p>
  164 <ul>
  165 <li>Open up instances of the Chrome and Firefox browsers and connect them to Karma.</li>
  166 <li>Execute all the unit tests in these browsers.</li>
  167 <li>Report the results of these tests in the terminal/command line window.</li>
  168 <li>Watch all the project&#39;s JavaScript files and re-run the tests whenever any of these change.</li>
  169 </ul>
  170 <p>It is good to leave this running all the time, in the background, as it will give you immediate
  171 feedback about whether your changes pass the unit tests while you are working on the code.</p>
  172 <h3 id="running-e2e-tests">Running E2E Tests</h3>
  173 <p>We use E2E (end-to-end) tests to ensure that the application as a whole operates as expected.
  174 E2E tests are designed to test the whole client-side application, in particular that the views are
  175 displaying and behaving correctly. It does this by simulating real user interaction with the real
  176 application running in the browser.</p>
  177 <p>The E2E tests are kept in the <code>e2e-tests</code> directory.</p>
  178 <p>The angular-phonecat project is configured to use <a href="https://github.com/angular/protractor">Protractor</a> to run the E2E tests for
  179 the application. Protractor relies upon a set of drivers to allow it to interact with the browser.
  180 You can install these drivers by running:</p>
  181 <pre><code>npm run update-webdriver
  182 </code></pre>
  183 <div class="alert alert-info">
  184   You don&#39;t have to manually run this command. Our npm scripts are configured so that it will be
  185   automatically executed as part of the command that runs the E2E tests.
  186 </div>
  188 <p>Since Protractor works by interacting with a running application, we need to start our web server:</p>
  189 <pre><code>npm start
  190 </code></pre>
  191 <p>Then, in a <em>separate</em> terminal/command line window, we can run the Protractor test scripts against
  192 the application by running:</p>
  193 <pre><code>npm run protractor
  194 </code></pre>
  195 <p>Protractor will read the configuration file at <code>e2e-tests/protractor.conf.js</code>. This configuration
  196 file tells Protractor to:</p>
  197 <ul>
  198 <li>Open up a Chrome browser and connect it to the application.</li>
  199 <li>Execute all the E2E tests in this browser.</li>
  200 <li>Report the results of these tests in the terminal/command line window.</li>
  201 <li>Close the browser and exit.</li>
  202 </ul>
  203 <p>It is good to run the E2E tests whenever you make changes to the HTML views or want to check that
  204 the application as a whole is executing correctly. It is very common to run E2E tests before pushing
  205 a new commit of changes to a remote repository.</p>
  206 <div class="alert alert-warning">
  207   <p>
  208     Each version of Protractor is compatible with specific browser versions. If you are reading this
  209     some time in the future, it is possible that the specified Protractor version is no longer
  210     compatible with the latest version of Chrome that you are using.
  211   </p>
  212   <p>
  213     If that is the case, you can try upgrading Protractor to newer version. For instructions on how
  214     to upgrade dependencies see <a href="tutorial/#updating-dependencies">Updating dependencies</a>.
  215   </p>
  216 </div>
  219 <h3 id="updating-dependencies">Updating dependencies</h3>
  220 <p>In order to avoid surprises, all dependencies listed in <code>package.json</code> are pinned to specific
  221 versions (this is what the <a href="https://docs.npmjs.com/files/package-lock.json">package-lock.json</a> file is about). This ensures that the
  222 same version of a dependency is installed every time.</p>
  223 <p>Since all dependencies are acquired via npm, you can use the same tool to easily update them as
  224 well (although you probably don&#39;t need to for the purpose of this tutorial). Simply run the
  225 preconfigured script:</p>
  226 <pre><code>npm run update-deps
  227 </code></pre>
  228 <p>This will update all packages to the latest version that satisfy their version ranges (as specified
  229 in <code>package.json</code>) and also copy the necessary files into <code>app/lib/</code>. For example, if <code>package.json</code>
  230 contains <code>&quot;some-package&quot;: &quot;1.2.x&quot;</code>, it will be updated to the latest 1.2.x version (e.g. 1.2.99),
  231 but not to 1.3.x (e.g. 1.3.0).</p>
  232 <p>If you want to update a dependency to a version newer than what the specificed range would permit,
  233 you can change the version range in <code>package.json</code> and then run <code>npm run update-deps</code> as usual.</p>
  234 <div class="alert alert-info">
  235   See <a href="https://docs.npmjs.com/misc/semver#ranges">here</a> for more info on the various version range formats.
  236 </div>
  239 <h3 id="common-issues">Common Issues</h3>
  240 <p><br />
  241 <strong>Firewall / Proxy issues</strong></p>
  242 <p>Git and other tools, often use the <code>git:</code> protocol for accessing files in remote repositories.
  243 Some firewall configurations are blocking <code>git://</code> URLs, which leads to errors when trying to clone
  244 repositories or download dependencies. (For example corporate firewalls are &quot;notorious&quot; for blocking
  245 <code>git:</code>.)</p>
  246 <p>If you run into this issue, you can force the use of <code>https:</code> instead, by running the following
  247 command: <code>git config --global url.&quot;https://&quot;.insteadOf git://</code></p>
  248 <p><br />
  249 <strong>Updating WebDriver takes too long</strong></p>
  250 <p>Running <code>update-webdriver</code> for the first time may take from several seconds up to a few minutes
  251 (depending on your hardware and network connection). If you cancel the operation (e.g. using
  252 <code>Ctrl+C</code>), you might get errors, when trying to run Protractor later.</p>
  253 <p>In that case, you can delete the <code>node_modules/</code> directory and run <code>npm install</code> again.</p>
  254 <p><br />
  255 <strong>Protractor dependencies</strong></p>
  256 <p>Under the hood, Protractor uses the <a href="https://docs.seleniumhq.org/">Selenium Standalone Server</a>, which in turn requires
  257 the <a href="https://en.wikipedia.org/wiki/Java_Development_Kit">Java Development Kit (JDK)</a> to be installed on your local machine. Check this by running
  258 <code>java -version</code> from the command line.</p>
  259 <p>If JDK is not already installed, you can download it <a href="https://www.oracle.com/technetwork/java/javase/downloads/index.html">here</a>.</p>
  260 <p><br />
  261 <strong>Error running the web server</strong></p>
  262 <p>The web server is configured to use port 8000. If the port is already in use (for example by another
  263 instance of a running web server) you will get an <code>EADDRINUSE</code> error. Make sure the port is
  264 available, before running <code>npm start</code>.</p>
  265 <hr />
  267 <p>Now that you have set up your local machine, let&#39;s get started with the tutorial:
  268 <a href="tutorial/step_00">Step 0 - Bootstrapping</a></p>