diff --git a/aio/content/start/index.en.md b/aio/content/start/index.en.md new file mode 100644 index 000000000000..26992786de5a --- /dev/null +++ b/aio/content/start/index.en.md @@ -0,0 +1,360 @@ +# Part 1: Getting started with a basic Angular app + +Welcome to Angular! + +This tutorial introduces you to the essentials of Angular by walking you through a simple e-commerce site with a catalog, shopping cart, and check-out form. +To help you get started right away, this guide uses a simple ready-made application that you can examine and modify interactively (without having to [set up a local work environment](guide/setup-local "Setup guide")). + +
+
New to web development?
+ + There are many resources to complement the Angular docs. Mozilla's MDN docs include both [HTML](https://developer.mozilla.org/en-US/docs/Learn/HTML "Learning HTML: Guides and tutorials") and [JavaScript](https://developer.mozilla.org/en-US/docs/Web/JavaScript "JavaScript") introductions. [TypeScript's docs](https://www.typescriptlang.org/docs/home.html "TypeScript documentation") include a 5-minute tutorial. Various online course platforms, such as [Udemy](http://www.udemy.com "Udemy online courses") and [Codecademy](https://www.codecademy.com/ "Codecademy online courses"), also cover web development basics. + +
+ + +{@a new-project} +## Create the sample project + +

+Click here to create the ready-made sample project in StackBlitz. +

+ +
+ Starter online store app +
+ +* The preview pane on the right shows the starting state of the sample Angular app. +It defines a frame with a top bar (containing the store name and checkout icon) and the title for a product list (which will be populated and dynamically updated with data from the application). + +* The project pane on the left shows the source files that make up the application, including all of the infrastructure and configuration files. The currently selected file shows up in the editor pane in the middle. + +Before going into the source structure, the next section shows how to fill out the HTML *template* for the product list, using the provided sample data. +This should give you an idea how easy it is to modify and update the page dynamically. + +
+
StackBlitz tips
+ +* Log into StackBlitz so you can save and resume your work. +If you have a GitHub account, you can log into StackBlitz +with that account. In order to save your progress, first +fork the project using the Fork button at the top left, +then you'll be able to save your work to your own StackBlitz +account by clicking the Save button. +* To copy a code example from this tutorial, click the icon +at the top right of the code example box, and then paste the +code snippet from the clipboard into StackBlitz. +* If the StackBlitz preview pane isn't showing what you +expect, save and then click the refresh button. +* StackBlitz is continually improving, so there may be +slight differences in generated code, but the app's +behavior will be the same. +* When you generate the StackBlitz example apps that +accompany the tutorials, StackBlitz creates the starter +files and mock data for you. The files you'll use throughout +the tutorials are in the `src` folder of the StackBlitz +example apps. + +
+ +
+ +If you go directly to the [StackBlitz online development environment](https://stackblitz.com/) and choose to [start a new Angular workspace](https://stackblitz.com/fork/angular), you get a generic stub application, rather than this [illustrative sample](#new-project). Once you have been introduced to the basic concepts here, this can be helpful for working interactively while you are learning Angular. + +In actual development you will typically use the [Angular CLI](guide/glossary#command-line-interface-cli "Definition of CLI"), a powerful command-line tool that lets you generate and modify applications. For a full step-by-step guide that shows how to use the CLI to create a new project and all of its parts, see [Tutorial: Tour of Heroes](tutorial). + +
+ + +{@a template-syntax} +## Template syntax + +Angular's template syntax extends HTML and JavaScript. +This section introduces template syntax by enhancing the "Products" area. + +
+ +To help you get going, the following steps use predefined product data from the `products.ts` file (already created in StackBlitz example) and methods from the `product-list.component.ts` file. + +
+ +1. In the `product-list` folder, open the template file `product-list.component.html`. + +1. Modify the product list template to display a list of product names. + + 1. Each product in the list displays the same way, one after another on the page. To iterate over the predefined list of products, put the `*ngFor` directive on a `
`, as follows: + + + + + With `*ngFor`, the `
` repeats for each product in the list. + +
+ + `*ngFor` is a "structural directive". Structural directives shape or reshape the DOM's structure, typically by adding, removing, and manipulating the elements to which they are attached. Directives with an asterisk, `*`, are structural directives. + +
+ + 1. To display the names of the products, use the interpolation syntax `{{ }}`. Interpolation renders a property's value as text. Inside the `
`, add an `

` to display the interpolation of the product's name property: + + + + + The preview pane immediately updates to display the name of each product in the list. + +
+ Product names added to list +
+ +1. To make each product name a link to product details, add the `` element and set its title to be the product's name by using the property binding `[ ]` syntax, as follows: + + + + + In the preview pane, hold the pointer over a product + name to see the bound name property value, which is + the product name plus the word "details". + Interpolation `{{ }}` lets you render the + property value as text; property binding `[ ]` lets you + use the property value in a template expression. + +
+ Product name anchor text is product name property +
+ + +4. Add the product descriptions. On the `

` element, use an `*ngIf` directive so that Angular only creates the `

` element if the current product has a description. + + + + + The app now displays the name and description of each product in the list. Notice that the final product does not have a description paragraph. Because the product's description property is empty, Angular doesn't create the `

` element—including the word "Description". + +

+ Product descriptions added to list +
+ +5. Add a button so users can share a product with friends. Bind the button's `click` event to the `share()` method (in `product-list.component.ts`). Event binding uses a set of parentheses, `( )`, around the event, as in the following `