## PR Checklist
Please check if your PR fulfills the following requirements:
* [x] The commit message follows our guidelines: https://github.com/angular/angular/blob/master/CONTRIBUTING.md#commit
* [ ] Tests for the changes have been added (for bug fixes / features)
* [x] Docs have been added / updated (for bug fixes / features)
## PR Type
What kind of change does this PR introduce?
* [ ] Bugfix
* [ ] Feature
* [ ] Code style update (formatting, local variables)
* [ ] Refactoring (no functional changes, no api changes)
* [ ] Build related changes
* [ ] CI related changes
* [x] Documentation content changes
* [ ] angular.io application / infrastructure changes
* [ ] Other... Please describe:
## What is the current behavior?
Issue Number: N/A
## What is the new behavior?
## Does this PR introduce a breaking change?
* [ ] Yes
* [x] No
## Other information
PR Close#28206
Currently, when we navigate in the `CLI COMMANDS` section, the "hamburger button" isn't present because the class css `folder-cli` is missing.
This PR add this class in order to show this button when we are in this section.
PR Close#28418
This ensures that the SW is cleaned up, even in cases where
synchronization is disabled (and thus the clean-up inside `goTo()`
happens without waiting for Angular).
PR Close#28290
For asynchronous callbacks, this can be done either by calling
`done.fail()` or by returning the promise directly (without requesting a
`done` callback). (Using the latter, because it is shorter.)
PR Close#28290
Show top menu at 992px screen width. The JS expression was checking just for screen widths
strictly greater than 992px to show the menu, while the CSS media query was showing the hamburger
icon just for screen widths strictly smaller than 992px, so there was a gap of 1px that the user
could't navigate through the top menu.
closes#24324
PR Close#26418
The `.properties-table` selector does not match any element and the
styles don't look relevant for the similarly named `.property-table`
class.
PR Close#28104
Right now, we post such comments whenever a file has been touched that
could potentially have affected the docs. Since the API docs are built
from comments in the source code, almost all non-docs changes are
generating such preview comments, even though most of the time they are
irrelevant to the author and create unnecessary noise on the PR
(especially for actively worked-on PRs).
This commit removes the `team` GitHub team from the list of teams whose
members will automatically get preview comments.
(Adding the `aio: preview` label would still work on any PR.)
Jira: FW-967
PR Close#28211
I think only should be after BrowserModule , because we can import more than BrowserModule and I think we need to import other modules to AppModule in most of cases and we should import BrowserModule only in AppModule,so that thing seems okay.
PR Close#27677
Link to the document "53 percent of mobile site visits" was changed, updated link. Old link led to a page that didn't have the statistics on it.
PR Close#26628
Occasionally, URLs take longer to load, which causes CI flakes.
In #27903, the timeout for external URLs was increased, but internal
URLs turned out to be affected as well.
PR Close#28103
Changes:
- Change the project type to `service-worker`, so that it gets
appropriate `package.json` (with `@angular/service-worker` dependency)
and `angular.json` (with `serviceWorker: true` in production config).
- Move `ngsw-config.json` to the correct directory.
- Specify custom test commands for aio's `yarn example-e2e` to also
verify that the ServiceWorker bits are set up correctly.
PR Close#28020
Previously, cli-based docs examples were tested using `yarn e2e ...`. In
some cases, it might make sense to run different or additional checks
for a docs example (when running `yarn example-e2e` in `aio/`).
Currently, the only option is to define a custom project type and
overwrite the `e2e` yarn script in `package.json`. Doing so (in addition
to being cumbersome and verbose) would also end up in the `.zip` archive
that users can download to run the example locally. This would be
confusing, if these custom tests are specific to our CI needs.
This commit adds support for defining a custom list of commands per
example. These commands (if specified) would be run instead of the
default `yarn e2e ...`, when testing the docs examples on CI (via
`yarn example-e2e`).
(This feature will be used to verify that the
`service-worker-getting-started` example is set up correctly in a
subsequent commit, but can be useful in other cases as well.)
PR Close#28020
File overwrites:
- **angular.json**: Add `serviceWorker: true` to production config.
- **package.json**: Add `@angular/service-worker` to dependencies.
This will make any `service-worker` examples work out-of-the-box, when
downloading and running locally from the `.zip` archives.
PR Close#28020
This change matches the routes found in the following code example
for auth.guard.ts as well as the login.component.1.ts in the "Add
the LoginComponent" section.
PR Close#27879
The existing example makes it seem like zip is a pipeable operator. It can be used this way, but I think that is for backwards compatibility. You can achieve the same functionality by using it as an Observable creator. I think this also makes the example clearer.
PR Close#26790
This new version of dgeni-packages gives the main (implemented)
overload of a method the correct id and aliases, which allow it to be
automatically linked.
See 398f35da30Fixes#27820Closes#27821
PR Close#27864
We need to do this because we don't yet have a released version of angular
with typescript 3.2 support and on CI we test both against the snapshot and
whatever is in aio/yarn.lock.
Once we have the next rc or a stable relase we should be able to remove
this flag.
PS: I also removed the preserveWhitespace:false because that's the default now.
PR Close#27536
cli is not yet officially compatible with typescript 3.2, so we need to disable the version check via:
ng config cli.warnings.typescriptMismatch false
PR Close#27536
It's unclear why `import as` results in the aliases to be undefined.
Plain tsc seems to do the right thing and emits the correct code, so it
might be some kind of interaction in @angular/cli or webpack that are
causing the failure.
This should be investigated separately from the tsc update in
angular/angular. See angular/angular-cli#13212
PR Close#27536
the clickable region of the top menu item is expanded beyond the focused area, so the clickable area is spans the entire height of the navigation
fixes#27618
PR Close#27633
the clickable region of the top menu item is reduced to the focused area, so no cursor pointer is shown outside the clickable area
fixes#27618
PR Close#27620
The `FETCH_ERROR` document is used when we are unable to retrieve a
document (except for 404 errors), which includes when there is no
internet connection. Using the `<current-location>` element in the
document's template to show the path of the page we failed to retrieve
assumes that the element's bundle is available (e.g. cached by the SW)
or can be fetched from the server.
When none of these conditions is met, the `DocViewer` is unable to
prepare the document and fails, never showing the `FETCH_ERROR` page to
the user.
Furthermore, the path we are looking to retrieve via
`<current-location>` is essentially the document ID, which we already
have. Thus, loading and instantiating a whole component just for that is
overkill.
This commit addresses both issues by getting rid of the
`<current-location>` component and directly embedding the document ID
into the `FETCH_ERROR` content.
PR Close#27250
When using relative paths for CSS resources (such as background images),
`@angular/cli` will move them to the root `dist/` directory (and update
the paths in CSS accordingly). This results in the SW being unable to
cache the resource, because it is not where it expects it to be.
This commit fixes this issue for the footer background image, by using
an absolute path for the URL. (It also removes an unused style that
would have been affected by the same issue.)
PR Close#27250
In order for 'Material Icons' to work offline, their `.woff2` file needs
to have been cached by the SW. This file is not requested by the
browser, until an element needs to use the icon font.
In order to speed up the initial page load and avoid FOUC, we use
inlined SVGs for all icons in the app shell. As a result, the `.woff2`
file may not be requested, when a user visits angular.io. If they go
offline before visiting a page that does actually use 'Material Icons',
then such icons will not work correctly (e.g. the `error_outline` icon
used in the error page for failed requests due to network
unanvailability).
This commit fixes this, by adding a non-visible element that needs the
'Material Icons' font on the main component. Thids ensures that the
`.woff2` file will always be loaded, even if the page does not use any
material icons.
(Note: The element is inserted lazily to avoid affecting the initial
rendering.)
PR Close#27250
These icons are part of the app shell and used on every load (on both
desktop and mobile). Inlining them ensures they are rendered asap.
PR Close#27250
Previously, we did not load the Roboto font, instead relying on the user
to have it available on their system and falling back to different fonts
otherwise. This resulted in the page being styled slightly differently
for those people that didn't have the font installed locally.
PR Close#27250
This can help with debugging issues, e.g. with the communication between
the preview server and CI, as it gives a better idea of exactly when was
the preview made available and how long it took.
PR Close#27436
With this change, we no longer depend on CircleCI to trigger the webhook
(which it sometimes does with considerable delay or not at all).
This has the added benefit that other jobs will not unnecessarily
trigger webhooks and spam the preview server logs. It is only the
`aio_preview` job's webhook that we care about.
Related to #27352.
PR Close#27458
Reported issue in #18138 is due to EasyList being selected in ABP. This commit fixes both the image at the bottom of the Dynamic Component Loader example, and the Stackblitz demo.
Fixes#18138
PR Close#27212
Earlier versions may transitively depend on a malicious version of
`flatmap-stream` (see dominictarr/event-stream#116).
The `aio-builds-setup/` had an older version of `event-stream` (3.3.4),
which did not depend on `flatmap-stream`, but upgraded it anyway.
PR Close#27274
Some engineers were already on Yarn 0.10.x which was permitted by the range in our package.json#engines
However this introduced 'integrity sha512' lines into the yarn.lock files.
Then when engineers use yarn 0.9 (in particular, Bazel did this) then the lock files get tons of meaningless edits.
We could force everyone back to yarn 0.9 but this commit chooses to instead advance everyone past 0.10
PR Close#27193
Currently, calling `downgradeModule()` more than once is not supported.
If one wants to downgrade multiple Angular modules, they can create a
"super-module" that imports all the rest and downgrade that.
This commit adds support for downgrading multiple Angular modules. If
multiple modules are downgraded, then one must explicitly specify the
downgraded module that each downgraded component or injectable belongs
to, when calling `downgradeComponent()` and `downgradeInjectable()`
respectively.
No modification is needed (i.e. there is no need to specify a module for
downgraded components and injectables), if an app is not using
`downgradeModule()` or if there is only one downgraded Angular module.
Fixes#26062
PR Close#26217
In some overloads, the parameter type can be a large anonymous
object type.
This change displays such types as `object`. It is then up to the
documentation author to put more information about the type in the
method usage notes.
PR Close#24976
* Make individual overloads collapsible
* Show only the first overload expanded, rest collapsed
* Text changes to 'collapse all' once 'show all' is clicked
* Fix chevron/carrot rotation animation when overloads / overload item is expanded or collapsed
PR Close#24976
Add link to protactor.angular.io
Replace link from github.com/angular/universal to universal.angular.io
Replace link from github.com/angular/material2 to material.angular.io
fix#18257
PR Close#26653
Some of the text in CLI API docs were being auto-linked to API
pages. This was not correct, and in fact these blocks should not
have any auto links to Angular API at all.
Closes#26570
PR Close#26675
Previously, `firebase-tools@3.x` was used and the deployment from
CircleCI failed with `Unexpected error` (HTTP code: 410).
This commit ensures that we use a recent version of `firebase-tools` for
deploying to Firebase. It also ensures that we use the locally installed
`firebase-tools` (not sure where it came from before 😁).
PR Close#26746
This commit includes the following changes:
* CLI version information is read from the CLI package from which
we read the help files.
* CLI API pages now contain GH links
* line numbers are not shown in GH links, if the doc does not
have a truthy `startingLine` value. This allows us to remove
hard coded checks for `guide` pages
* content pages and CLI api docs no longer have a `startingLine`
* the hard-coded `packages` path segment has been removed from
the templates; instead we now only use the `realProjectRelativePath`.
* the `realProjectRelativePath` has been updated accordingly for API
and CLI API docs.
PR Close#26515
Since #26396, the `title` property is ignored and `header` should be
used instead for specifying a code snippet's header.
This commit ensures that we don't accidentally set `title` have it be
silently ignored.
PR Close#26514
Added word *relative* to the **Routes at the app level** section description. This was not specified before. The routes in the *lazy-loading-ngmodules/src/app/app-routing.module.ts* also had `loadChildren` values starting with `app/...`.
The code for `app-routing.module.ts` is already fixed in [this commit](67ad9468d3)
PR Close#26504
Change the headings of the template-driven forms guide page.
This makes the first heading consistent with other guide pages and the menu label reducing confusion to users browsing the guide.
PR Close#25900
This commit also removes the extra jasminewd2 typings, since the changes
have been merged in the official typings with
DefinitelyTyped/DefinitelyTyped#28957.
PR Close#26139
Previously CLI was being treated like the API page, where the top level item
had to be highlighted for any command page. But now the CLI commands all
have their own navigation item, which can be selected, so there is no need
to special case CLI paths any more.
Closes#26373
PR Close#26388
The JSON files from which cli command docs for angular.io are generated
is broken on master (e.g. angular/cli-builds@e0ec86757), which cause foc
generation (and CI) to fail.
Pinning the git ref where we pull cli sources from to a version that is
known to be working (until we figure out what the best approach is)
PR Close#26391
This is necessary to avoid webpack/webpack#8082, when installing
dependencies without taking the lockfile into account (e.g. with
`yarn aio-use-local` - locally or on CI).
PR Close#26202
If the documentation contains a `@selectors` tag then the content of that
is used to describe the selectors of a directive.
Otherwise the selector string is split and each selector is listed as
a list item in an unordered list.
PR Close#25768
line 39: `highly-interactive` is the pre-qualifier of `Angular application`, which is the subject so the comma is not necessary (I think). I think this will make it easier for non-native speakers.
PR Close#25853
As it turns out, in GitHub API paginated requests, page numbering is
1-based. (https://developer.github.com/v3/#pagination)
Starting at page 0 (which returns the first page), results in making the
same request twice and logging incorrect numbers (since the first 100
items are listed twice).
PR Close#25671
Includes the following fixes:
- Fix cron entry format for clean-up script.
Crontabs in `/etc` should not have a user field. No idea why it used
to work before, but it started giving errors recently:
`/bin/sh: root: not found`.
- Set required env variable in clean-up script. (Broken in cc6f36a9d.)
This was producing the following error:
`ERROR: Missing required environment variable 'AIO_CIRCLE_CI_TOKEN'!`
- Use the correct path for downloads to be removed. (Broken in cc6f36a9d.)
PR Close#25671
The deployment of PR previews is triggered by the notification webhook
of the `aio_preview` CircleCI job (which creates and stores the build
artifacts).
This commit adds a new job (`test_aio_preview`), which waits for the
preview to be deployed (for PRs that do have a preview) and then runs
some tests against it (currently only PWA tests).
Fixes#23818
PR Close#25671
There several reasons why PRs cannot have (public) previews:
- The PR did not affect any relevant files (e.g. non-spec files in
`aio/` or `packages/`).
- The PR cannot be automatically verified as "trusted" (based on its
author or labels).
Note:
The endpoint does not check whether there currently is a (public)
preview for the specified PR; only whether there can be one.
PR Close#25671
According to the docs, the response of GitHub's [PR files API][1]
_"includes a maximum of 300 files"_. This means that if a PR contains
more files, it is possible that not all files are retrieved (which
could, for example, give a false negative for the "significant files
touched" check - not likely but possible).
This commit fixes it by using paginated requests to retrieve all changed
files.
[1]: https://developer.github.com/v3/pulls/#list-pull-requests-files
PR Close#25671
Some tests where comparing actual with expected paths, without taking
into account that paths will be different on Windows.
This commit uses `path.resolve()` to convert expected paths to their
OS-specific form.
PR Close#25671
Previously, due to multiple scripts re-building during `yarn dev`
initialization, there could be race conditions that led to errors.
This commit fixes it by ensuring `yarn build` is run once (before
the main `yarn dev` script).
PR Close#25671
When we have navigated to the site via a URL that contains a search
query param, the site shows the search results.
We want to remove that query param from the URL when the search
results are closed, but the current implementation is also removing
other query params unnecessarily.
Now only the search param is removed when the search results are
closed.
See https://github.com/angular/angular/pull/25479/files#r219497804
for more context.
PR Close#26056
The default dgeni config is to concatenate leading comments in front of API items.
In the case that you have an API item that starts a file with no import statements,
the license comment at the top of the file was being added to the front of the
API item's comment. SInce the license comment includes the `@license` tag
and the API item's comment did not start with `@description` the content of
the API item's comment was being put inside the `@license` tag, and no
description was being extracted from the API item's comment.
This commit updates to a version of dgeni-packages that has a switch to turn off
this concatenation, and then also configures this switch.
Closes#26045
PR Close#26050
All directives and pipes must now be tagged with one ore more
public NgModule, from which they are exported.
If an item is exported transitively via a re-exported internal NgModule
then it may be that the item appears to be exported from more than
one public NgModule. For example, there are shared directives that
are exported in this way from `FormsModule` and `ReactiveFormsModule`.
The doc-gen will error and fail if a directive or pipe is not tagged correctly.
NgModule pages now list all the directives and pipes that are exported from it.
Directive and Pipe pages now list any NgModule from which they are exported.
Packages also now list any NgModules that are contained - previously they were
missed.
PR Close#25734
`TypeScript` only supports merging and extending of `compilerOptions`. This is an implementation to support extending and inheriting of `angularCompilerOptions` from multiple files.
Closes: #22684
PR Close#22717
Firebase used to do it automatically (with `cleanUrls: true`), but it
stopped doing it unless the resulting URL corresponds to an existing
file (which is not always the case in angular.io; e.g. the resulting URL
might be matched by a new redirect rule).
This change in Firebase hosting behavior resulted in some URLs not being
correctly redirected (e.g. URLs to the archived v2 site, or `.html`
suffixed URLs from 3rd-party sites).
This commit fixes it, by configuring Firebase hosting to strip off the
`.html` extension and redirect (if no other redirect rule matched).
PR Close#25999
Enables Chrome users to search angular.io and its subdomains from the browsers navigation bar.
Not sure if compatible with Firefox yet.
The queried term in the URL is removed after closing the search-results.
PR Close#25479
Since `aio/src/generated/` is git-ignored, it is easy for stale content
(e.g. removed images, examples, zips, etc.) to remain there on local
clones and then get copied into the `dist/` directory.
This commit ensures `aio/src/generated/` is cleaned up before generating
the new content.
PR Close#25841
As part of the tests run in the CircleCI `aio_monitoring` job, we need
to retrieve `sitemap.xml` from the site under test. Previously, the URL
used to retrieve that contained a double-slash (`//`). At some point,
Firebase (which is used for hosting the site) stopped normalizing
double-slashes to a single slash, causing the test to fail.
This commit fixes the problem by ensuring that the constructed URLs do
not contain double-slashes.
PR Close#25641
Now that the doc-gen parses the imports of TS source
files we need to ensure that the root node_modules
exists. Otherwise running `yarn docs` produces an
obscure error:
```
Error: No SourceFile found with path node_modules/@types/jasmine/index.d.ts
```
Closes#25759
PR Close#25811
Due to unknown reasons, Firebase seems to return a 301 response for
`/index.html`, but without a `Location` header. According to the spec,
the browser will not follow the redirect, considering the response as
failed, instead.
This commit temporarily removes `index.html` from hashed resources and
changes `index` to `/` in `ngsw-config.json`, until we figure out an
appropriate long-term solution.
PR Close#25692
In an overloaded method, the overload with the function body is the
actual method doc, and this doc is not included in the list of "additional"
overloads.
Moreover, the logic (all in dgeni-packages) is that if none of the items
has a body then we use the first overload as the actual method doc.
In the case of abstract methods, none of the methods have a body. So we
have a situation where the overloads collection does not contain the first
abstract method, even though it is not the "implementation" of the method.
Therefore we need to still render it.
Closes#25610
PR Close#25670
This allows URLs to be passed through to the server (where they are
properly redirected), instead of serving `index.html` from the SW.
Known issue:
`/docs/` will be passed through to the server. `/docs` (without the
trailing slash) will be correctly treated as a navigation URL and
handled by the SW.
We don't link to `/docs/` from within the app, but if there are external
links to `/docs/` they will require a round-trip to the server and will
not work in offline mode.
PR Close#19795
AIO is currently using a beta version of @angular/service-worker.
Since that was implemented, the SW has been rewritten and released
as part of Angular 5.0.0. This commit updates AIO to use the latest
implementation, with an appropriate configuration file that caches
the various AIO assets in useful ways.
PR Close#19795
Previously, Travis pushed the build artitfacts to the preview server.
This required us to use JWT to secure the POST request from Travis, to
ensure we couldn't receive malicious builds.
JWT has been deprecated and we are moving our builds to CircleCI.
This commit rewrites the TypeScript part of the preview server that
handles converting build artifact into hosted previews of the docs.
George Kalpakas
Jeremy Elbourn
Jeff Cross
jithil-kore
Matti Järvinen
Nazar Nasirzada
Janghyun Han
onlyflix
WilliamKoza
Alan Agius
Dhananjay Kumar
Carlos Schneider
Dario Braun
Daniel Ruf
Kapunahele Wong
Giorgos Bamparopoulos
Luiz Machado
Hamza TEI
ericksoen
Stepan Suvorov
Tomas Veras
Kayce Basques
krzysztof-grzybek
Malgosia
javatutorials2016
Shivam_Vyas
Ashinze Ekene
Brad Brandhorst
coultonluke
Brandon Roberts
Sasidhar Vanga
Steve Dignan
Courtney Pattison
cyraid
Judy Bogart
Pete Bacon Darwin
Adam Plumer
Joseph Harrison-Lim
Mark Goho
Johannes Hoppe
Michael De Wree
Paul Gschwendtner
Andrew Crites
Zheng Kai
Enmanuel
Ronen Gelman
Mohammed Salman
Cyrille Tuzi
Nico Jansen
Preetham Viswanathan
Igor Minar
Sharath George M
Emilio Martinez
bmarkov
zackarychapple
Esteban Marin
Emmanuel DEMEY
Lucas
Michał Jawulski
Isaac Sunkes
volshibenik
dennisameling
seunggabi
Minko Gechev
Grant Timmerman
Jacob Foshee
Amadou Sall
Alex Eagle
Elan Hasson
Rae Krantz
Ferdinand Malcher
Andrew Anikin
Matthew Harris
Frederik Schlemmer
Jonathan Sharpe
Alvaro Junqueira
Manish Bansal
Sarun Intaralawan
Radoslav Kirilov
Nikhil Sharma
Vito Meuli
hariberry
Stefanie Fluin
Jason Aden
djy0
Ivan Tham
Alexander Teplyashin
Daniel Lewis BSc (Hons)
fisherspy
Brian Love
Luis Reinoso
jenniferfell
nazanin1369
Katerina Skroumpelou
Rob Phoenix
lovelangy
Siddharth Ajmera
William Marques
Vladimir Erygin
George Wilde
Vani
Simone Bigozzi
Wei Lun
Ashish Patel
siddhant
JiaLi.Passion
Atuuh
thanhpd
Kirankumar Sripati
Charles Lyding
Suguru Inatomi
Jordan Whitfield
Ben Lesh
arjunyel
Max Belsky
George Wilde
sajeetharan
Sergej
songjunting
Plamena Radneva
Liad Idan
Maicon Wagner
Rob Wormald
Stephen Fluin
Jonathan Pool
Martin Sikora
Alex Rickabaugh
Bert Verhelst
Sergey Koshechkin
JinBeom Hong
Ana María Martínez Gómez
Greg Magolan
