angular / angular.io Goto Github PK

Website for the Angular project (see github.com/angular/angular for the project repo)

License: MIT License

HTML 59.78% CSS 4.70% JavaScript 6.32% TypeScript 28.86% Dart 0.12% Shell 0.23%

angular.io's Introduction

This angular.io documentation repository is closed and preserved just for archival purposes

Please post new issues and pull requests to the content folder in https://github.com/angular/angular/tree/master/aio/content.

Angular.io

Angular.io is site for Angular documentation .

This site also includes links to other helpful angular resources including AngularJS, Angular Material, and AngularFire.

Issues

Please file Developer Guide, Cookbook, and code sample issues only in this Angular.io github repo.

Angular API issues, cheatsheet corrections, feature requests, defect reports, and technical questions concerning Angular itself belong in the angular source code github repo. We can't handle those topics here and will ask you to re-post them on the angular repo.

How you can help

Filing issues is helpful but pull requests that improve the docs are even better!

Learn how to contribute to Angular.io.

Development Setup

This site relies heavily on node and npm.

Make sure you are using at least node v.5+ and latest npm; if not install nvm to get node going on your machine.
Install global npm packages by running ./scripts/before-install.sh
Clone

this repo
angular/angular source code repo

to the same parent directory. The cloned repo directories must be siblings, with the latter named angular.

cd into root directory angular.io/
Install local npm packages by running ./scripts/install.sh
See below for code sample development preparation.

Content Development

All documentation content is written in Jade which has its own syntax. Be aware of the strict demands imposed by this significant-whitespace language. We strongly recommend running one of the gulp serve-and-sync commands described below while editing content so you can see the effect of your changes as you type.

The documentation relies on specific styles and mixins. Learn about those in the documentation styleguide.

The jade documentation files are language-specific directories under either public/docs/. For example, all of the TypeScript docs are in public/docs/ts/latest, e.g.

public/docs/ts/latest/quickstart.jade
public/docs/ts/latest/guide/architecture.jade
public/docs/ts/latest/cookbook/component-communication.jade
public/docs/ts/latest/tutorial/toh-pt5.jade

Local server with watches and browser reload

cd into root directory angular.io/
run gulp serve-and-sync
browser will launch on localhost:3000 and stay refreshed automatically.

If you are only going to work on a specific part of the docs, such as the dev guide, then you can use one of the more specific gulp tasks to only watch those parts of the file system:

gulp serve-and-sync : watch all the local Jade/Sass files, the API source and examples, and the dev guide files
gulp serve-and-sync-api : watch only the API source and example files
gulp serve-and-sync-devguide : watch only the dev guide files
gulp build-and-serve : watch only the local Jade/Sass files

Code Sample Development

All documentation is supported by sample code and plunkers. Such code resides in the public/docs/_examples directory, under page-specific directories, further divided by language track.

For example, the TypeScript QuickStart sample is in public/docs/_examples/quickstart/ts.

All samples are in a consistent directory structure using the same styles and the same npm packages, including the latest release of Angular. This consistency is possible in part thanks to gulp-driven tooling. To run the samples locally and confirm that they work properly, take the following extra steps to prepare the environment:

cd to public/docs/_examples
install the canonical node packages for all samples by running npm install
cd back up to angular.io root: cd ../../..
run gulp add-example-boilerplate (elevate to admin on Windows) to copy canonical files to the sample directories and create symlinks there for node_modules.

Now cd into any particular sample's language directory (e.g., public/docs/_examples/quickstart/ts) and try:

npm start to simultaneously compile-with-watch and serve-in-browser-with-watch
npm run tsc to compile only
npm run lite to serve-and-watch in browser

Look at the scripts in package.json for other options. Also, open any plunkr.no-link.html to see the code execute in plunker (you may have to run gulp build-plunkers first to create/update).

You must check that your example is free of lint errors.

gulp lint

Sample end-to-end tests

All samples should be covered to some degree by end-to-end tests:

gulp run-e2e-tests to run all TypeScript and JavaScript tests
gulp run-e2e-tests --lang=all to run TypeScript and JavaScript tests
gulp run-e2e-tests --filter=quickstart to filter the examples to run, by name
gulp run-e2e-tests --fast to ignore npm install, webdriver update and boilerplate copy

Any combination of options is possible.

Resetting the project

This project generates a lot of untracked files, if you wish to reset it to a mint state, you can run:

git clean -xdf

Also, there is a script available for Linux, OSX and Windows Gitbash users that will setup the project using the steps shown in this section:

./scripts/install.sh

Run with current build instead of release packages

Can switch the @angular packages in ~/public/docs/_examples/node_modules to the current build packages with

gulp install-example-angular --build

Restore to RELEASE packages with

gulp install-example-angular

These commands will fail if something is locking any of the packages ... as an IDE often does.

The symptom typically is an error trying to rm -rf node_modules/@angular.

Solution: unlock the hold on the package(s). In VS Code, re-load the window (cmd-P then enter >relow).

Technology Used

Angular: Current Angular
AngularJS: A v.1.x version of Angular
Angular Material: An implementation of Material Design in Angular.js
Gulp: node-based tooling
Harp: The static web server with built-in preprocessing.
Sass: A professional grade CSS extension language
Normalize: A modern, HTML5-ready alternative to CSS resets
Grids: A highly customizable CSS Grid Framework built with Sass
Prettify: A JS module and CSS for syntax highlighting of source code snippets.
Icomoon: Custom built icon fonts

License

angular.io's People

Contributors

Stargazers

Watchers

Forkers

evanx nlnbich cironunes medavid kennethormandy icaliman naomiblack bradlygreen cwspear alexeagle iammerrick isc-host btford meenie alvarezmario leoxwebdev jcoyne mgechev mwilc0x un33k lintangarief fjavierjimenez lisposter 34r7h aciccarello jamesh79 jeffbcross kosssi jgatjens fredericksilva elmariofredo isaacweathers rodyhaddad stumblingrumblin 0x-r4bbit thierryve wakashige dkuerner sekibomazic elijaholeg tony-proum ideablade daliandragon kara angularjscollection vicb harshapat stevenroose quintep justinbeaudry c0debrain juleskremer gjungb igorminar brandonroberts saharj sumedhmeshram codejets fedy2 joeeames gaggigger filipesilva eladbezalel vikas-parashar jnnck gnomeontherun marclaval frankamp patrickjs foxandxss jeffwhelpley narretz andyperlitch fvanwijk simonkuang kirjs leandrodiniz shairez timruffles tomplusplus deborahk learn-web-dev mychaelgo tapas4java profoundry-us tamurashingo manekinekko mrajcok reemardelarosa kwalrath philipooo arliang devnoiseconsulting jweir johnapost estsauver mithun-daa okko bsimpson lightrabbit

angular.io's Issues

Create a press kit page

This page will include our branding guidelines and assets for public use.

Conditionals within prose

I'd like to know how to add conditional text in our Jade templates.

I have three cases:

Conditionally changing a phrase or word
Conditionally using different paragraphs:
I'd like to break up some of the content into separate files and conditionally inlining the contents of them: if (dart) { include('router/example1/dart.jade' } else { include('router/example1/es5.jade' } etc.

For all of these, I need to support four cases: ES5+Angular 1, ES5+Angular 2, TypeScript+Angular 2, Dart+Angular 2.

Jade probably supports this, but I do not have cycles to investigate. A short example would suffice. Thanks!

Style Guide

Within the guide, changing languages always puts you at the index

If I'm in "Angular 2 JS" docs for the router, and I click the "Angular 2 Dart" select box at the top of the page, I am taken to the index page for the "Angular 2 Dart docs" rather than to the page on the router in "Angular 2 Dart."

This makes it difficult for me to compare the JS and Dart versions of the Router while I'm maintaining two separate copies.

Change link on the homepage to point to the ng-conf playlist

keynote1 + playlist: https://www.youtube.com/watch?v=QHulaj5ZxbI&index=1&list=PLOETEcp3DkCoNnlhE-7fovYvqwVPrRiY7

or playlist alone: https://www.youtube.com/playlist?list=PLOETEcp3DkCoNnlhE-7fovYvqwVPrRiY7

router guide: add missing TS code

Look for the following and replace it with TypeScript code:

//TODO Need Angular2 Example here for TypeScript

I think there's just 1 occurrence, and it should be deleted.

Move Resources (blog post links and video from the team) to a forever home

The old Resources page had some useful blog post links and video from the core team. Need a nice way to organize this kind of content.

Ability for users to find Angular Google Drive Folder

I constantly hear from people that they can't find our google drive folder with all the design docs, notes and presentations.

This is why we recently added the eye-stabbing yellow button to https://angularjs.org.

Can a link to the same folder be added to some highly visible place?

The url is: http://goo.gl/sj0Nk1

Site menu is broken om toch devices

I have this problem both om iPhone 6 and on HTC nexus tablet (only in portraitmode)

When the top toolbar is in narrow mode the toolbar turns into a dropdown button. Clicking this drop down you are not able to select from the menu on these touch devices. Using a mouse on a desktop computer works

resolve issues with harp 17

David ran into issues here -- need to investigate

Enable including example files

I'd love to be able to (1) include my test files in angular.io (maybe visible on the site, maybe not) and (2) include those same files into HTML pages.

As an example, look at displaying-data.jade. I'd like it to have code sections like this:

  .code-box
    pre.prettyprint.lang-dart(data-name="dart")
      code.
        <include /path/to/sample/web/main.dart show 'web/main.dart'>
    pre.prettyprint.lang-html(data-name="html")
      code.
        <include /path/to/sample/web/index.html show 'web/index.html'>
    pre.prettyprint.lang-yaml(data-name="yaml")
      code.
        <include /path/to/sample/pubspec.yaml show 'pubspec.yaml'>

Instead, it has pretty horrible stuff like this:

  .code-box
    pre.prettyprint.lang-dart(data-name="dart")
      code.
        // web/main.dart
        library displaying_data;

        import 'package:angular2/angular2.dart';
        import 'package:angular2/src/reflection/reflection.dart' show reflector;
        import 'package:angular2/src/reflection/reflection_capabilities.dart' show ReflectionCapabilities;

        part 'show_properties.dart';

        main() {
          reflector.reflectionCapabilities = new ReflectionCapabilities();
          bootstrap(DisplayComponent);
        }
    pre.prettyprint.lang-html(data-name="html")
      code.
        &lt;!-- web/index.html --&gt;
        &lt;!DOCTYPE html&gt;
        &lt;html&gt;
          &lt;head&gt;
            &lt;link rel=&quot;stylesheet&quot; href=&quot;style.css&quot;&gt;
          &lt;/head&gt;
          &lt;body&gt;

            &lt;display&gt;&lt;/display&gt;

            &lt;script type=&quot;application/dart&quot; src=&quot;main.dart&quot;&gt;&lt;/script&gt;
            &lt;script src=&quot;packages/browser/dart.js&quot;&gt;&lt;/script&gt;
          &lt;/body&gt;
        &lt;/html&gt;
    pre.prettyprint.lang-yaml(data-name="yaml")
      code.
        # pubspec.yaml
        name: displaying_data
        description: Dart version of Angular 2 example, Displaying Data
        version: 0.0.1
        dependencies:
          angular2: 2.0.0-alpha.20
          browser: any

Module-level descriptions are not generated in output API docs

Module-level descriptions e.g. for Annotations here (https://github.com/angular/angular/blob/master/modules/angular2/annotations.js) are picked up by dgeni and output but aren't making it to the angular.io API docs. @petebacondarwin any idea what the issue is?

Dropdown for quickstart lists JS but shows TS

The quick start https://angular.io/docs/js/latest/quickstart.html seems to list JS and Dart, but if you select JS it shows TS.

Would be cool if you could select TS, JS (for vanilla ES5/ES6), or Dart.

Enable case-sensitive filenames in tabs

Tabs in code-box sections currently have UPPER CASE letters and seem geared toward displaying alternate files in different languages (e.g. ES5 & TypeScript versions of the same code). That isn't great if you're displaying multiple files in the same language, or files with different purposes (that happen to be in different languages).

For example, Dart examples typically have 1 or more Dart files, 1 or more HTML files, and 1 pubspec.yaml file. An example is at the top and bottom of my latest copy of displaying-data.jade.

Generate a Dart API doc version

Needs infrastructure for conditional code examples, and Dart examples in the API

Add Angular U conference to website

Add superpowers?

Angular since the early beginings uses superpowers or superheroes for theming various aspects of the project.

examples:

all releases are published with a release name that describes a superpower (often quirky ones)
many talks about Angular make reference to super heroes or super powers
many blog posts build on top of the superhero theme (see the ionic example )
ng-conf used super-powers in their environment design
some tools for angular use references to superheros as well (e.g. batarang)
our t-shirts are superhero like

Overall, the community really likes this quirky part of the project and it would be great to preserve it lightly in the angular.io design.

router guide: add missing ES5 code

Search for the following string, and replace it with code.

//TODO Need Angular2 Example here for ES5

I count at least 7 occurrences where there really is no ES5 code:

"Then you can add the router into your app by importing the Router module in your app.js file:"
"So how do we configure the app? Let's open app.js and find out. Add this to the file:"
"Let's make a controller:"
"And add the controller's module as a dependency to our main module in app.js:"
"In app.js:"
"In detail.js, we implement a controller that uses the id route parameter:"
"For example, as specified below, when a user navigates to /, the URL changes to /user and the outlet at that level loads the user component."

Some additional occurrences appear to be cases where there is an ES5 example above, so the code exists but needs to be presented correctly.

Search layout is broken

Font is antialiased on the toolbar buttons on non-retina displays

@alexwolfe can we do anything to sharpen that text up on lower res displays?

Use a filter for escaping HTML

It's cumbersome to do this manually: https://github.com/angular/angular.io/blob/master/public/docs/js/latest/guide/displaying-data.jade#L149-L155

Jade docs: http://jade-lang.com/reference/filters/

Why are we stopping event propagation?

For instance:

big image is too big

https://github.com/angular/angular.io/blob/master/public/docs/dart/latest/guide/user-input-example1.png is too big (visually and in bytes).

Could you please resize it? (Or give me a little coaching, and I can do it myself.)

We should not recommend installing with sudo

From the readme:

sudo npm install -g [email protected]

This is poor practice.

See:

Add David's Forms Video to Resources page

https://www.youtube.com/watch?v=4C4bmDOV5hk

Why are we manually manipulating the DOM instead of using bindings?

Here, for instance: https://github.com/angular/angular.io/blob/master/public/resources/js/site.js#L75-L117

This code is really hard to understand. Taking better advantage of Angular's data binding would help a lot, and would let us easily drop the jQuery dependency.

Clarify TypeScript support

Someone mentioned on twitter(?) the other day a good place for clarification:

https://angular.io/download/

It lists JavaScript and Dart, but not TypeScript. To help clarify, may want to list as "JavaScript (and TypeScript)" as a text change.

Dart quickstart is broken (fix is available)

Use TypeScript for the Quickstart page

Hi,

since AtScript is TypeScript now, I think we should use TypeScript in the example on https://angular.io/docs/js/latest/quickstart.html so we don't need an explanation of AtScript and es6-shim.

Usage header in API docs for router is too large

See https://angular.io/docs/js/latest/api/router/Router-class.html

remove the ".x" from the Angular 1 menu items

just cleanup. We can say "Angular 1" -- it's more consistent with "Angular 2"

Service inject example is not correct for TypeScript

At https://angular.io/docs/js/latest/guide/displaying-data.html#Create-a-class, there is the example for inject the Service in the components.

ES5 example is:

//ES5
function FriendsService() {
  this.names = ["Alice", "Aarav", "Martín", "Shannon", "Ariana", "Kai"];
}
function DisplayComponent(friends) {
  this.myName = "Alice";
  this.names = friends.names;
}
DisplayComponent.annotations = [
  new angular.Component({
    selector: "display",
    injectables: [FriendsService]
  }),
  new angular.View({
    template: '{{ myName }} <ul> <li *for="#name of names">{{ name }}</li> </ul>',
    directives: [angular.For, angular.If]
  })
];
DisplayComponent.parameters = [[FriendsService]];
document.addEventListener("DOMContentLoaded", function() {
  angular.bootstrap(DisplayComponent);
});

But TypeScript example is:

//TypeScript
import {Component, View, bootstrap, For} from
...
  directives: [For]

I think TypeScript example should be:

import {Component, View, bootstrap, For, If} from 'angular2/angular2';

class FriendsService {
  constructor() {
    this.names = ["Alice", "Aarav", "Martín", "Shannon", "Ariana", "Kai"];      
  }
}

@Component({
  selector: 'display',
  injectables: [FriendsService]
})

@View({
  template: `
  <p>My name: {{ myName }}</p>
      <p>Friends:</p>
      <ul>
        <li *for="#name of names">
          {{ name }}
        </li>
      </ul>
      <p *if="names.length > 3">You have many friends!
   </p>`,
  directives: [For, If]
})

class DisplayComponent {
  myName: string;
  name: Array;

  constructor(friends:FriendsService) {
      this.myName = "Alice";
      this.names = friends.names;
  }
}

bootstrap(DisplayComponent);

Bio modal only works for the first row of images

When you look at the bios, the first row works well if you click on any images.
Then if you scroll down to the second row, you only see half of the modal.
On the third row, you only see the very bottom of the modal.
On the forth row, the modal is totally gone.

I think you may need to line the modal to the top of the page and not the top of the sliding page.
The position of the modal is 'relative' I think.

https://angular.io/about/

Why is modal template constructed from string concat?

See: https://github.com/angular/angular.io/blob/master/public/resources/js/site.js#L162-L174

Why not just use bindings?

angularIOApp should use "controller as"

It's a best practice and will make it easier to migrate later.

favicon is missing from second-level pages

angular.io has a favicon
https://angular.io/about/ does not

Write some text for the Angular 2 for Dart API landing page pointing to the JS docs

Need some interim placeholder text until we conditionalize the API doc output.

Should go here: https://angular.io/docs/dart/latest/api/

Mistake in step 8 of quickstart tutorial

Hi,

I noticed that in Step 8 of the quickstart, the instructions state that a HTTP server should be spun up serving from the directory containing index.html. However, in index.html, paths used for System.paths and the es6-shim script tag assume that the parent directory of quickstart is being served:

System.paths = {
    'angular2/*':'/quickstart/angular2/*.js', // Angular
    'rtts_assert/*': '/quickstart/rtts_assert/*.js', // Runtime assertions
    'app': 'app.es6' // The my-app component
  };

Add Print Styles

Be sure to create a separate scss file for print print.scss and include the print styles in there.

Print styles should hide the following items:

Top Nav
Side Nav
Footer

They should also update the layout so that during print the full page is used and the margins are correct.

Switch license to Apache 2

All Google projects should now use Apache 2 license unless there is a good reason not to use it.

See the internal open source office site for more info if more info is needed to implement this change.

Docs need to be regenerated

It's unclear how the jade files get generated, but the "defined in" for Annotations class was invalidated in this commit: angular/angular@fb67e37

Can you regenerate so they are correct?

Mobile navigation broken on angular.io/docs/js/latest/

On Nexus 5 in Chrome when I click on "Site Menu" or "Docs", the menu flickers -- doesn't remain open, immediately disappear.

Optionally show filename in code sections

This would let us avoid having to put a comment on the first line with the filename. Adding that comment made me hesitate to use line numbers in files, since we don't have those comments in the actual files.

For an example, see code in https://angular.io/docs/dart/latest/guide/displaying-data.html.

Here's an example of code that has a filename (from https://www.dartlang.org/codelabs/darrrt/):

The name could be at the upper or lower right, or maybe you have a better idea. Of course, we'd need to be careful not to cover up actual code.

quickstart repo does not have app.ts at root

Despite the fact it's defined in tsconfig.json:
https://github.com/angular/ts-quickstart/blob/master/tsconfig.json#L17

Thus when you start the compiler you get:

$ tsc -w
error TS6053: File 'app.ts' not found.
message TS6042: Compilation complete. Watching for file changes.

Should app.ts be moved out of complete/ and down to the root?

I would have reported this on the ts-quickstart repo, but issues are not enabled there.

Uncaught SyntaxError: In strict mode code, functions can only be declared at top level or immediately within another function.
[email protected]:2605 GET https://registry.jspm.io/app.js 404 (Not Found)
[email protected]:140 Potentially unhandled rejection [3] Error loading "app" at https://registry.jspm.io/app.js
Not Found: https://registry.jspm.io/app.js (WARNING: non-Error used)