The markdown processor expects an empty line between an opening tag and the
markdown content. (If there is no empty line, the content is interpreted as
plain HTML.)
Previously, the line between the opening `<td>` and the content contained
whitespace, which caused the content to be interpreted as HTML and not markdown.
Fixes#18312
PR Close#18349
In Node.JS console.log/error/warn functions actually resuls in a socket
write which in turn is considered by Zone.js as an async task.
This means that if there is any exception during change detection in a platform-server
application the error handler will make the Angular Zone unstable which
in turn will cause change detection to run on next tick and cause an
infinite loop.
It is also better to run the error handler outside of the Angular Zone
in general on all platforms so that an error in the error handler itself doesn't cause an
infinite loop.
Fixes#17073, #7774.
PR Close#18269
Note 4.3 only!
Prior to this fix when [@.disabled] was used in a component that
contained zero animation code it wouldn't register properly because the
renderer associated with that component was not an animation renderer.
This patch ensures that it gets registered even when there are no
animations set.
* Tell the app that this will have no Table of Contents, since we have no
h2 headings anyway.
* Remove all the `nbsp;` from the code since that doesn't help with layout
* Remove side padding from sidenav-content when screen is narrow
* Restyle the cheatsheet table when the screen is narrow
Possibly overlooked testing documentation mistake fixed:
- `http.get('/data')` probably ought to be paired with `httpMock.expectOne('/data')` instead of `httpMock.expectOne('/data')`.
Note 4.3 only!
Prior to this fix when [@.disabled] was used in a component that
contained zero animation code it wouldn't register properly because the
renderer associated with that component was not an animation renderer.
This patch ensures that it gets registered even when there are no
animations set.
The API docs have changed. The line numbers are now found in
`startingLine` and `endingLine` properties rather than the `location`
property, which moved into the `fileInfo` property anyway.
In our attempt to remove the material ripple effect from tab labels, we were
killing all `transform`-based animations on other `md-tab-group` elements, such
as animating the content when entering/leaving. (This wasn't an issue on Chrome,
because it didn't respect our `!important` flag.)
This commit fixes it by properly hiding the ripple effect (using a feature
introduced in angular/material2@e4789c7b8) and allowing other animations to
execute normally.
Fixes#17998
Now that we have upgraded to the latest lunr search engine, the results
from the standard `search` method are more appropriate.
So we do not need to create our own special queries to get good results.
Since 808bd4af4, we are no longer pre-verifying PRs before uploading the build
artifacts to the preview server, thus we no longer need the
`travis-preverify-pr.sh` script or the `GITHUB_TEAM_MEMBERSHIP_CHECK_KEY`
variable.
This commit adds an API endpoint for notifying the preview server about PR
updates (`/pr-updated`). According to the update, the preview server can take
several actions. Currently, it will only check and (if necessary) update the
PR's preview visibility (but more actions could be supported in the future).
The API can be used with an automatic trigger (e.g. a GitHub webhook) to
instantly update a PR's preview visibility when it changes.
Fixes#16526
Previously, `BuildCreator#changePrVisibility()` would throw an error if the PR's
visibility was already up-to-date or if the PR directory did not exist (e.g. was
removed). This method was only used from inside `BuildCreator#create()`, which
had already checked for the existence of the directories.
This commit renames `changePrVisibility()` to `updatePrVisibility()` and makes
it more "forgiving" (i.e. it will only throw if both public and non-public
directories exist). This allows it to be used on events that may or may not have
caused the PR's visibility to change (e.g. a GitHub webhook triggered whenever a
PR's labels change).
Previously, there was a distinction between GET requests to invalid URLs and all
other requests. This was mainly because the upload-server only accepts GET
requests, but that is not a hard limitation and may change in the future.
Thus, it makes sense to return a 404 response for requests to invalid URLs
regardless of the method used.
HttpClient is an evolution of the existing Angular HTTP API, which exists
alongside of it in a separate package, @angular/common/http. This structure
ensures that existing codebases can slowly migrate to the new API.
The new API improves significantly on the ergonomics and features of the legacy
API. A partial list of new features includes:
* Typed, synchronous response body access, including support for JSON body types
* JSON is an assumed default and no longer needs to be explicitly parsed
* Interceptors allow middleware logic to be inserted into the pipeline
* Immutable request/response objects
* Progress events for both request upload and response download
* Post-request verification & flush based testing framework
Previouly, whenever a new ServiceWorker update was detected the user was
prompted to update (with a notification). This turned out to be more distracting
than helpful. Also, one would get notifications on all open browser tabs/windows
and had to manually reload each one in order for the whole content (including
the app) to be updated.
This commit changes the update strategy as follows:
- Whenever a new update is detected, it is immediately activated (and all
tabs/windows will be notified).
- Once an update is activated (regardless of whether the activation was
initiated by the current tab/window or not), a flag will be set to do a
"full page navigation" the next time the user navigates to a document.
Benefits:
- All tabs/windows are updated asap.
- The updates are applied authomatically, without the user's needing to do
anything.
- The updates are applied in a way that:
a. Ensures that the app and content versions are always compatible.
b. Does not distract the user from their usual workflow.
NOTE:
The "full page navigation" may cause a flash (while the page is loading from
scratch), but this is expected to be minimal, since at that point almost all
necessary resources are cached by and served from the ServiceWorker.
Fixes#17539
`Object.assign` is not available in all supported browsers and one had to
provide a polyfill. This commit replaces `Object.assign` with the spread
operator (`...`), which TypeScript will transpile to ES5-compatible code.
(#17971)
This commit changes the dynamic version of ngUpgrade to use `UpgradeHelper`,
thus bringing its behavior (wrt upgraded components) much closer to
`upgrade/static`. Fixes/features include:
- Fix template compilation: Now takes place in the correct DOM context, instead
of in a detached node (thus has access to required ancestors etc).
- Fix support for the `$onInit()` lifecycle hook.
- Fix single-slot transclusion (including optional transclusion and fallback
content).
- Add support for multi-slot transclusion (inclusing optional slots and fallback
content).
- Add support for binding required controllers to the directive's controller
(and make the `require` behavior more consistent with AngularJS).
- Add support for pre-/post-linking functions.
(This also ports the fixes from #16627 to the dynamic version.)
Fixes#11044
(#17971)
Although, pre- and post-linking functions are correctly called during directive
linking, directives with `link.post` would throw an error. Interestingly, having
`link.pre` only or defining `link: fn` (which is an alias for `link.post: fn`)
would not throw.
This commit removes this check and allows directives with pre- and/or
post-linking functions to work.
Previously, only simple, single-slot transclusion worked on upgraded components.
This commit fixes/adds support for the following:
- Multi-slot transclusion.
- Using fallback content when no transclusion content is provided.
- Destroy unused scope (when using fallback content).
Fixes#13271
Firebase does not allow `.` in the path, so when trying to upload payload size
data for branches like `4.2.x`, the following error is thrown:
```
HTTP Error: 400, Invalid path: Invalid token in path
```
This commit fixes it by replacing `.` with `_` in branch names.
There have been some issues lately with Travis jobs failing due to
`print-log.sh`. This is likely due to trying to print the Lighthouse PWA report,
which is too large.
This commit stops printing that report (since it was rarely used and is pretty
easy to acquire when needed) and restores the `print-logs.sh` script (that was
temporarily removed with dfcca66fd).
closes#17665
Restores keyboard focus that was removed by commit b8b91d3.
Raises the right-TOC by 20px (96px->76px) because was too far down.
To prevent keyboard focus on hidden child nodes,
also collapses inner expanded nodes when parent node is collapsed.
The implicit parent node of top nodes is always expanded.
The window title is derived based on the current document's `<h1>` heading. Such
headings may contain hidden/non-visible content (e.g. textual name of font
ligatures: `<i class="material-icons">link</i>`) that should not be included in
the title.
This commit fixes this by using `innerText` (instead of `textContent`) to
extract the visible text from the `<h1>` heading. It will still fall back to
`textContent` on browsers that do not support `innerText` (e.g. Firefox 44).
Fixes#17732
Use the 7 first characters of the 40-chars long SHAs for shorter/cleaner URLs.
The collision probability is extremely low (since all SHAs are further
"namespaced" under the corresponding PR). In case of a collision, the second PR
will not be deployed, in order to avoid overwriting the original build.
(This is a design decision to keep the implementation simple. It can be changed
later if necessary.)
The previous clean-up code for PR directories on the preview server assumed that
all directories were named after the PR number. With the changes introduced
in #17640 it is possible to have PR directories that do not follow that naming
convention (e.g. "non-public" directories).
This PR ensures that both public and non-public directories are removed when
cleaning up.
When creating a new docker image for the preview server, the TypeScript source
code in `scripts-js/` is not copied over. Instead only the generated JavaScript
core in `scripts-js/dist/` are. Because of that, it is necessary to have run
`yarn build` before running `docker build`, so that the new docker image
contains the latest changes in `scripts-js/`.
This was previously part of the `create-image.sh` script, but was accidentally
removed in 21d213dfc.
- /deep/ is deprecated and being removed from Chrome
- >>> is semantically invalid in a stylesheet
- sass will no longer support either in any version of sass
-> use ::ng-deep in emulated shadow DOM mode
Because the deep combinator is deprecated in the CSS spec,
`/deep/`, `>>>` and `::ng-deep` are also deprecated in emulated shadow DOM mode
and will be removed in the future.
see https://www.chromestatus.com/features/6750456638341120
This commit introduces the ability to show previews for PRs by any author. It works as follows:
- The build artifacts of all PRs are uploaded to the preview server.
- Automatically verified PRs (i.e. from trusted authors or having a specific label) are deployed and
publicly accessible as usual.
- PRs that could not be automatically verified are stored for later use (after re-verification).
- A PR can be marked as "trusted" and make its preview publicly accessible by adding the GitHub
label specified in the `AIO_TRUSTED_PR_LABEL` env var of the preview server.
At the moment, there is no automatic mechanism for notifying the preview server about changes to the
PR's verification status. The PR's "visibility" will be checked and updated every time a new build
is uploaded.
Before 4f37f8643, we were using `innerText` to retrieved the code content for
copying. This preserved the text layout (including newlines), but suffered from
other issues (browser support, performance). With 4f37f8643 we switched to
`textContent`, which works well except in the following case:
When `prettify` formats the code to have line numbers, it removes the newlines
and uses `<li>` elements instead. This affects `textContent`.
This commit fixes this by keeping a reference of the code as text and using that
for copying.
Fixes#17659
We expect this behavior because it's what Travis does. Also it's better because we want
to test what happens if we merge the PR, not the status of the PR branch.
Running the patch script on Windows (with `patch` available) yields an invalid syntax warning, and does not apply patches.
```
kamik@T460p MINGW64 /d/work/angular/aio (master)
$ yarn postinstall
yarn postinstall v0.24.6
$ node tools/cli-patches/patch.js && uglifyjs node_modules/lunr/lunr.js -c -m -o src/assets/js/lunr.min.js --source-map
The syntax of the command is incorrect.
Done in 1.52s.
```
Destructuring of the form:
function foo({a, b}: {a?, b?} = {})
breaks strictNullChecks, due to the TypeScript bug https://github.com/microsoft/typescript/issues/10078.
This change eliminates usage of destructuring in function argument lists in cases where it would leak
into the public API .d.ts.
toString() from DefaultKeyValueDiffer is only used in tests and should not
be part of the production code. toString() methods from differs add
~ 0.3KB (min+gzip) to the production bundle size.
With 4.2, we introduced the min and max validator directives. This was actually a breaking change because their selectors could include custom value accessors using the min/max properties for their own purposes.
For now, we are rolling back the change by removing the exports. At the least, we should wait to add them until a major version. In the meantime, we will have further discussion about what the best solution is going forward for all validator directives.
Closes#17491.
----
PR #17551 tried to roll this back, but did not remove the dead code. This failed internal tests that were checking that all declared directives were used.
This PR rolls back the original PR and commit the same as #17551 while also removing the dead code.
This version fixes the DISCONNECTED errors (described in #17543) and removes the
need to the workaround (8af203c).
The relevant jasmine commit is jasmine/jasmine@c60d66994.
`innerText` is not supported in Firefox prior to v45. In most cases (at least
the ones we are interested in), `innerText` and `textContent` work equally well,
but `textContent` is more performant (as it doesn't require a reflow).
From [MDN][1] on the differences of `innerText` vs `textContent`:
> - [...]
> - `innerText` is aware of style and will not return the text of hidden
> elements, whereas `textContent` will.
> - As `innerText` is aware of CSS styling, it will trigger a reflow, whereas
> `textContent` will not.
> - [...]
[1]: https://developer.mozilla.org/en-US/docs/Web/API/Node/textContent#Differences_from_innerTextFixes#17585
Previously, we had redirect rules for Firebase for `/docs/ts/latest` and
`/styleguide`, but once the ServiceWorker was activated, it would take over
routing and rewrite these requests to `/index.html`.
This commit fixes it by excluding them from ServiceWorker routing.
Fixes#17542
With 4.2, we introduced the min and max validator directives. This was actually a breaking change because
their selectors could include custom value accessors using the min/max properties for their own purposes.
For now, we are rolling back the change by removing the exports.
Closes#17491.
With SHA 2c3e948e61 the biography of Paul Gschwendtner has been accidentally removed.
This re-adds the biography entry (picture still present) as requested on Slack.
Previously, there was an issue with testing the PWA score on staging and failing
the build was temporarily disabled. It works now, so we need to enable failing
the build is the score drops below some threshold.
The footer background (implemented via `footer:after`) had a higher `z-index`
than other footer elements and was obscuring the footer links on certain
browsers (Firefox, Edge, IE), which made them unclickable.
This commit lowers the index of `footer:after`, so that links are clickable on
these browsers.
Fixes#17460
You can now specify what environment you are building
by add it to the `yarn build` command. For example:
```
yarn build -- --env=stage
```
Moreover the `deploy-to-firebase.sh` script will automatically apply the
appropriate environment.
The API docs tests have very variable run times, depending
upon the build environment.
This change doubles their test timeout values to prevent
false-negative failures.
Previously, we always assumed that elements would be scrolled to the top of the
page, when calling `element.scrollIntoView()`. This is not true for elements
that cannot be scrolled to the top, e.g. when the viewport height is larger than
the height of the content after the element (common for small sections near the
end of the page).
In such cases, we would unnecessarily scroll up to account for the static
toolbar, which was unnecessary (since the element was not behind the toolbar
anyway) and caused ScrollSpy to fail to identify the scrolled-to section as
active.
This commit fixes it by ensuring that we do not scroll more than necessary in
order to align the top of the element with the bottom of the toolbar.
Fixes#17452
* update to latest version of lunr search
* add trailing wildcard to search terms to increase matches
* fix unwanted error when escape was pressed
Closes#17417
Using `<a>` inside a `<button>` is not syntactically valid HTML and breaks on
some browsers (e.g. Firefox). Furthermore, clicking the button doesn't do
anything unless you click on the link (e.g. clicking on the padding around the
link does nothing), which is inconvenient and confusing.
Fixes#17448
* Remove the "info-banner" styling from the filters.
* Fix alignment of the search box on a narrow screen (closes#17395)
* Remove unnecessary whitespace before section headers
The current stable branch is determined based on the current version mapped to
the npm `latest` tag (by replacing the patch version number with 'x' - e.g.
`1.2.3` --> `1.2.x`).
PRs against the stable branch will be deployed to the preview server (as long as
the rest of the requirements are met). Commits on the stable branch itself will
be deployed to production.
Fixes#16908
This puts the behavior introduced in 573b8611bc behind the new flag
`alwaysCompileGeneratedCode` to not break users that might have relied
on this behavior.
This PR fixes an issue where `query(':enter')` will only collect elements up until it an element that is found that isn't apart of the `:enter` query.
Closes#17440
Chrome (v58+) often gets disconnected during unit tests (causing them to fail).
This has been happening locally (on Windows) and on Travis. The exact reasons
are not known, but it seems that some of the `AppComponent` tests are to blame.
Based on the discussion in https://github.com/jasmine/jasmine/issues/1327 (and
plenty of trial-and-error), using Jasmine's `done()` callback before each of
test (even calling it synchronously) fixes the issue.
Previously the RequestOptions/ResponseOptions classes had constructors
with a destructured argument hash (represented by the
{Request,Response}OptionsArgs type). This type consists entirely of
optional members.
This produces a .d.ts file which includes the constructor declaration:
constructor({param, otherParam}?: OptionsArgs);
However, this declaration doesn't type-check properly. TypeScript
determines the actual type of the hash parameter to be OptionsArgs | undefined,
which it then concludes does not have a `param` or `otherParam` member.
This is a bug in TypeScript ( https://github.com/microsoft/typescript/issues/10078 ).
As a workaround, destructuring is moved inside the method, where it does not produce
broken artifacts in the .d.ts.
Fixes#16663.
Motivation: `yarn outdated`, for exmaple, shows the homepage URL on the command line. If copy-pasting or clicking on the URL, it's nice to see the repo's page instead of a 404.
Closes#17245 and #17253
When the user selects a doc item in the side nav:
1) expand folder(s) leading to the selected doc item
2) on a wide display, keep other already expanded folders open
3) on narrow (mobile) display, collapse other expanded folders
Used to do (3) when wide. Issue #17245 asks for (2).
That logic was bypassed for selected node when we allowed headers to have content
because that unintentionally expanded the header’s folder when selected.
Because the selected node is no longer a header with content, removing this exclusion
also means that folders are expanded/collapsed with above logic even for API pages.
Rather than hard coding excludes into the dgeni config,
use the fact that we are already ignoring the boilerplate
and generated files via the .gitignore file.
Previously, the main content would always leave a 18% margin on the right to be
occupied by the ToC (even if there was no ToC).
This commit lets the main content expand to the right to occupy all the
available space when there is no ToC.
Fixes#17205Fixes#17270
Previously, when scrolling the ToC and reaching the top/bottom, further
mousewheel events would result in scrolling the window (and thus the main
content). This is standard browser behavior. In the case of the ToC though, the
`ScrollSpy` would detect scrolling in the main content and scroll the active ToC
to entry into view, thus resetting the scroll position of the ToC.
Reproduction:
1. Open `~/guide/template-syntax`.
2. Start scrolling through the long ToC.
3. Try to go to the bottom of the ToC.
4. Once you reach the bottom, the main content starts scrolling down.
5. The first section ("HTML in templates") becomes "active", so the ToC is
scrolled back up to make its corresponding entry visible.
6. Go back to step 2.
This commit improves the UX, by not allowing the main content to scroll when the
cursor is ovr the ToC and the user has scrolled all the way to the top/bottom of
it.
When navigating from a page with open SideNav to a page without closed SideNav,
the main content area animates from a non-zero left margin to zero left margin.
Additionally, the top-bar on the homepage is transparent, which allows the white
background behind the main content to be seen while the left margin is animated
to zero, making it appear as if something (e.g. the SideNav covers the top-bar).
This commit works around this issue, by not making the top-bar transparent
immediately when navigating to the homepage, but animating it from its blue
color to transparent with a delay.
Fixes#17248
An ellipsis was used to separate the most relevant search
results from the alphabetic list. The separator was confusing
because it was not clear what it represented.
This has been removed and the most relevant results are now
indicated by styling with a more bold font and a bit of whitespace
between them and the rest of the results.
To keep things consistent, if there are fewer than 5 results all the
results are now displayed as priorityPages.
Closes#17233
In the marketing pages we do not want to show heading anchors on hover.
Previously, this was achieved by using div rather than heading elements.
Now we can use semantically accurate headings while hiding the anchor.
Closes#17244Closes#17264
Previously, the top-bar's height wasn't taken into account when scrolling an
element into view. As a result, the element would be hidden behind the top-bar.
Taking the top-bar height into account was not necessary before #17155, because
the top-bar was not fixed (i.e. it scrolled away).
This commit fixes the scrolling behavior by accounting for the top-bar's height
when scrolling an element into view.
(This partially reverts #17102.)
Fixes#17219Fixes#17226
This wraps the $interval service when using upgrade to run the
$interval() call outside the Angular zone. However, the callback is
invoked within the Angular zone, so changes still propagate to
downgraded components.
- Fixed topnav on all mobile
- Fixed topnav on all docs pages
- Absolute topnav on all marketing pages
- Cleanup and code consolidation for all top-menu styles
- Add styling to topnav links on focus
When more than one node matches a url, the last
node defined in the navigation.json file won. This
meant that, for instance, items in both the
TopBarNarrow and the Footer views would not
indicate that they were active.
Now, each url is associated with a map of current
nodes keyed off their view.
Closes#17022
Previously, the progress bar would be placed right under the static top bar. Now
that the top bar i not tatic any more, it makes more sense to place the progress
bar at the top of the page.
Fixes#17103
* Remove whitespace before type specifiers
* Generate `new` and `call` member info for interfaces
* Ensure that there is no double space after class names
Previously, the `#top-of-page` element (used when scrolling to top) was placed
inside the content section (which at the time had zero top margin and padding).
Furthermore, there was a top offset applied when scrolling that took the static
top bar's height into account. Since now the top bar is not static any more and
the content section has a non-zero top padding, scrolling to top does not work
as expected.
This commit fixes this by:
- Moving the `#top-of-page` element to the top of the `aio-shell`.
- Stop accounting for the top bar's top.
Fixes#17006
Refactoring the compiler to use transformers moves the code generation
after type-checking which suppresses the errors TypeScript would
generate in the user code.
`TypeChecker` currently produces the same factory code that was
generated prior the switch to transfomers, getting back the same
diagnostics as before. The refactoring will allow the code to
diverge from the factory code and allow better diagnostic error
messages than was previously possible by type-checking the factories.
* fix(aio): make the search-pane larger
Fixes#17094
* feat(aio): give the search-box a type of "search"
This enables browsers to style it better (e.g. add an `x` button for clearing
the field, which allows users to quickly reset the search query and hide
results).
There seems to have been a bad rebase of #16228 on top of #16959, which affected
ToC styles from both PRs. This commit restores the horizontal line under `.h1`
elements and the vertical blue bar on the left-hand side of the ToC (with the
circle running along the bar to indicate the active section).
Fixes#17098
Now converts shorthand imports for every TypeScript target. Tsickle is able to expand index shorthand imports for every TypeScript target and module possibility.
Expanding shorthand imports for CommonJS modules is also helpful when testing in the browser. Module loaders like SystemJS are not able to understand directory imports (or index shorthand imports)
- Add styling for active TOC item
- Add sidenav styles
- Change header tags to divs from index marketing page to remove anchors
- Fix use of card mixin and create separate card-docs class
- Add marketing styling
- Topnav styling when on home landing page
- Remove hamburger menu on home page
- Add fully rounded border to top nav toolbar search input
- Add mobile styles
- Add title banner to other marketing pages
Use this file if we need to turn off the service worker in deployed sites
in an emergency where the worker has a bug that is blocking the application
from working.
Closes#16897
this means we'll be temporarily duplicating the helpers (onces included via scripts
and secondly imported via es imports) - once rxjs, core and material migrate over
to tslib, we can drop the scripts/global dupe.
The `TopBarNarrow` now only shows a single top level container, "About Angular",
and the original `TopBar` items will be children of this container.
The `TopBarNarrow` styling is changed to match the rest of the `SideNav`.
* refactor(aio): use explicit CSS class for TOC container
This makes the styling less fragile to changes in the HTML
* fix(aio): schedule TocComponent.activeIndex updates via AsapScheduler
We use the `asap` scheduler because updates to `activeItemIndex` are triggered by DOM changes,
which, in turn, are caused by the rendering that happened due to a ChangeDetection.
Without asap, we would be updating the model while still in a ChangeDetection handler,
which is disallowed by Angular.
* refactor(aio): do not instantiate floating ToC if not displayed
* feat(aio): display the h1 at the top of the floating TOC
Closes#16900
* refactor(aio): combine the TOC booleans flags into a "type" state
* refactor(aio): remove unnecessary `hostElement` property
* fix(aio): ensure that transition works on TOC
* fix(aio): use strict equality in ToC template
If there is a `TopBarNarrow` nav view then use this when the screen is narrow.
Otherwise just use the normal `TopBar`.
This commit also creates such a narrow topbar view where the "Docs" item is
in a different position
Closes#16940
These files are needed so that:
- user code can compile even without real codegen
- as tsc transformers cannot create but only change existing files
in the transformation pipeline.
This is required as e.g. `token` from `@Inject` is
accessed in string form via makeParamDecorator
but as a property in the `ReflectiveInjector`.
Closes#16889 as this is a more general fix.
Add source location as a note tag as `<note category="location">path/to/file.ts:start_line[,end_line]</note>`.
`[,end_line]` part is optional and specified only if the end line is different from the start line.
Fixes #16531
`flush()` can now be used from within fakeAsync tests to simulate moving
time forward until all macrotask events have been cleared from the
event queue.
Previously we hardcoded the current version into the navigation items.
Now only previous versions are included there. The current version is
computed from the currentVersion info.
Closes#16909
Based on optional title passed in from parent element such as CodeExample or CodeTabs.
Darkens uncovered copy button slightly as recommended for a11y.
PR #16808
- Use buttons for the TOC “Contents” label when embedded-and-expandable or TOC on the right to satisfy a11y.
- Add aria-pressed setting for the toggles in TOC and NavItem.
- Clicking the right panel TOC “Contents” button scrolls to top.
- When embedded use same rotating caret as sidebar
- When embedded and no secondaries, “Content” is just a label.
- Gray background for focused buttons rather than outline because can’t get carets to work with outline.
This commit was worked on by a number of people including
@filipesilva, @gkalpak and @wardbell. It contains changes that:
* remove unused files,
* fix the bootstrap approach to ensure that bootstrap is in the correct Zone
* fix unclosed code-example tags
* replace use of "we" with "you"
* remove broken dual router example
Related to angular/angular.io#3541
Lighthouse v1.6.5 treats localhost/1.2.7.0.0.1 as secure domains (i.e. as if they where HTTPS), so we need to stop handling the is-on-https audit specially.
In some cases (unclear when), traceviewer-js, used by Lighthouse under the hood,
assumes `atob`/`btoa` are defined in the global scope. This is true for browser
environments, but not on node.
As a result, some aggregations that required access to model-tracing failed to
produce results, dropping the overall PWA score.
This affected #16665 (e.g. commit 0de6eec7a).
This fixes a flicker when transitioning from server rendered page to client rendered page in lazy loaded routes by waiting for the lazy loaded route to finish loading, assuming initialNavigation on the route is set to 'enabled'.
Fixes#15716
If a usage of `{@link ...}` does not provide a title then
compute it based on the `title` and/or `name` properties
or set the link to invalid.
Closes#16811
Sidenav headers had been anchors w/o hrefs. These can’t take focus which makes you can’t navigate through them with keyboard. For a11y purposes, this PR turns them into buttons.
By reflex we began all component tests with an async `beforeEach` that called `compileComponents`.
In at least one case (`live-example.component.spec.ts`) that led to the `it` tests being async as well.
There is no need to call `.compileComponents` because CLI web pack + plugin inlines all templates and styles.
While `.compileComponents` was harmless, it added complexity and distraction which we should not inflict on future readers and testers.
Previously the logic for deciding when to display
the search result was spread between different
parts of the application and used non-intuitive logic
such as sending a blank results set to the searchResults.
This commit moves the management of displaying
the search results (and also setting focus of the
search input box) to the AppComponent. This makes
it easier to understand what happens and why; but
also allows the search UI components to be more
easily reused (such as embedding them in the 404
page).
(Coincidentally), this wasn't an issue before fdfeaaf1f, because
pre-verification was run after `test.sh`, during which `aio-builds-setup` was
built.
Now that `deploy-staging.sh` is being run before `test.sh`, we need to build
the `aio-builds-setup` scripts first.
Previously, `aio/aio-builds-setup/scripts/travis-preverify-pr.sh` was supposed
to exit with 1 if a PR did not meet the preconditions and 2 if an error occurred
during pre-verification.
It relied on the exit codes of the node script that did the actual work, but
didn't account for errors that would be thrown in the `sh` script itself (e.g.
if the node script was not available). This caused such errors to appear as
non-verified PRs, instead of real errors that should fail the build.
This commit swaps the exit codes, so that now a 2 means non-verified PR and 1
designates an error.
Hybrid apps (mix of Angular and AngularJS) might return AngularJS implementation
of Promises that do not play well with the change detection. Wrapping them in
native Promises fix this issue.
This could be the case when a Resolver returns a `$q` promise.
Use bracket notation to access $inject in downgradeInjectable to
support property renaming. Since the return type is any,
Closure compiler renames $inject.
Since abb36e3cb, we no longer rely on the cli to set up ServiceWorker, but do it
manually as part of `yarn build`. When using `ng serve`, registering the
ServiceWorker fails, because we haven't created `ngsw-manifest.json` nor copied
`worker-basic.min.js` into dist.
This commit works around this, by only registering the service worker in
production mode (which is what the cli does too).
Caveat:
It is not possible to enable ServiceWorker with `ng serve`/`yarn start` and
using the `--prod` flag will try to register it, but fail because the necessary
files (`ngsw-manifest.json` and `worker-basic.min.js`) will not be available.
(As a work-around, you can use `yarn build` and serve the files in `dist/` with
`yarn http-server -- dist -p 4200`.)
Previously, PR previews were deployed after successfully running all tests.
While this makes sense for staging/production deployments, previews should be
available as soon as possible (and regardless of the outcome of tests).
Fixes#16705
Previously, no previews would be deployed for PRs that didn't touch files inside
`aio/`. Now, previews will be deployed for PRs that touch non-spec files inside
either `aio/` or `packages/` (as long as other preconditions are met).
Partially addresses #16526.
* refactor(core): provide error message in stack for reflective DI
Fixes#16355
* fix(compiler): make AOT work with `noUnusedParameters`
Fixes#15532
* refactor: use view engine also for `NgModuleFactory`s
This is a prerequisite for being able to mock providers
in AOTed code later on.
Template expressions can now use a post-fix `!` operator
that asserts the target of the operator is not null. This is
similar to the TypeScript non-null assert operator. Expressions
generated in factories will be generated with the non-null assert
operator.
Closes: #10855
Only one h1 is allowed per document, and this is provided by the template.
So we cannot have any h1 tags (or `#` markdown shorthand) in any API docs.
Closes#16193
Only one h1 is allowed per document.
(Also took the opportunity to remove unnecessary blank lines from these
docs, and a bit of general tidying.)
Closes#16193
This fail behaviour is only turned on for `yarn docs`;
in `yarn docs-watch` you only receive a warning.
This is because you can get false errors when watching
since we don't parse all the docs in that case.
* fix(aio): allow code blocks to clear floated images
Previously the negative margin on the code headings were causing
floated images to overlay the start of a code block. Now all code block
successfully clear all floated elements.
* feat(aio): add a `.clear` class for clearing floating images
* fix(aio): tidy up image styles
The css rules for `img.right` and `img.left` allow authors easy
access to floating an image on the left or right, respectively.
The `.image-display` rule which was always found on a figure
has been simplified so that all figures have this styling. It is very
unlikely that a figure will be used outside the content area; and
at this time it seems like `figure` is as good an indicator that we
want this kind of styling as anything.
Now that images are all tagged with width and height values, we cannot
assume to modify these dimensions via CSS as it can cause the image to
lose its correct proportions. Until we find a better solition we must set
`height` to `auto` when the screen width is below 1300px to ensure that
these images maintain their proportions as they get shrunk to fit.
* docs(aio): general tidy up of image HTML in guides
Previously, the guides have a lot of inline image styling and unnecessary
use of the `image-display` css class.
Images over 700px are problematic for guide docs, so those have been given
specific widths and associated heights.
* docs(aio): use correct anchor for "back to the top" link
The `#toc` anchor does not work when the page is
wide enough that the TOC is floating to the side.
* build(aio): add `#top-of-page` to path variants for link checking
Since the `#top-of-page` is outside the rendered docs
the `checkAnchorLinks` processor doesn't find them
as valid targets for links.
Adding them as a `pathVariant` solves this problem
but will still catch links to docs that do not actually exist.
* fix(aio): ensure that headings clear floated images
* fix(aio): do not force live-example embedded image to 100% size
This made them look too big, generally. Leaving them with no size means
that they will look reasonable in large viewports and switch to 100% width
in narrow viewports.
* docs(animations): fix links to `Component` animations
* docs(core): fix links to `ReflectiveInjector` methods
The `resolve` and other methods were moved from the
`Injector` to the `ReflectiveInjector`.
* docs(core): fix links to `Renderer`
The local links were assuming that that methods were on the
current document (e.g. `RootRenderer`), but they are actually
on the `Renderer` class.
* docs(router): fix links to methods
* docs(forms): fix links to methods
* docs(core): fix links to methods
* docs(router): fix API page links and an internal link
closes#16608
Formerly, tried to navigate when user clicked an anchor with an image url (to view image in a new tab) resulting in 404.
Now ignores href URL with any extension and lets browser handle it.
This code only runs in ES5 mode in the test suite, so this is difficult to test.
However `updateFromTemplate` is being called with a spread operator, as
`...updateFromTemplate(...)`. The spread operator should fail on `null` values.
This change avoids the problem by always returning a (possibly empty) array.
PR Close#16547
This also clarifies via a test
that we only update projected views when the view is created or destroyed,
but not when it is attached/detached/moved.
Fixes#15578
PR Close#16592
Previously a projected view was only dirty checked when the
component in which it was inserted was dirty checked.
This fix changes the behavior so that a view is also dirty checked if
the declaring component is dirty checked.
Note: This does not change the order of change detection,
only the fact whether a projected view is dirty checked or not.
Fixes#14321
closes#16603
As before this PR, when wide (side-by-side), the sidenav open/close status only changes when nav to/from marketing page in which case it opens for guide/api and closes for marketing page.
Fundamentals and Techniques nav groups we also links to pages. This caused
counterintuitive behaviour when clicking on them.
This commit moves each link from the group item to a children item, called
Introduction.
Closes#16604
The CSS rule for positioning the automated header links was too general,
causing other links inside headings to be positioned incorrectly.
Closes#16573
Previously the `hasToc` was initialised to true, which caused a flash of
unwanted "Contents" [sic] even if the page was not going to need a ToC.
Closes#16597
TOC appears in right panel when wide and hides embedded TOC
Right TOC panel height adjusts dynamically during scroll
Refactored `TocService` and its tests for clarity.
@angular/http/testing used to publish a metadata structure which paralleled
the .d.ts structure. This causes ngc to write incorrect imports for this
bundle when compiling providers using MockBackend and other http testing
classes.
This change restructures the @angular/http/testing build a bit, modeling it
after @angular/platform-browser-animations, and produces a FESM structure
that has flat metadata.
Fixes#15521.
Currently, if a Response has an ArrayBuffer body and text() is called, Angular
attempts to convert the ArrayBuffer to a string. Doing this requires knowing
the encoding of the bytes in the buffer, which is context that we don't have.
Instead, we assume that the buffer is encoded in UTF-16, and attempt to process
it that way. Unfortunately the approach chosen (interpret buffer as Uint16Array and
create a Javascript string from each entry using String.fromCharCode) is incorrect
as it does not handle UTF-16 surrogate pairs. What Angular actually implements, then,
is UCS-2 decoding, which is equivalent to UTF-16 with characters restricted to the
base plane.
No standard way of decoding UTF-8 or UTF-16 exists in the browser today. APIs like
TextDecoder are only supported in a few browsers, and although hacks like using the
FileReader API with a Blob to force browsers to do content encoding detection and
decoding exist, they're slow and not compatible with the synchronous text() API.
Thus, this bug is fixed by introducing an encodingHint parameter to text(). The
default value of this parameter is 'legacy', indicating that the existing broken
behavior should be used - this prevents breaking existing apps. The only other
possible value of the hint is 'iso-8859' which interprets each byte of the buffer
with String.fromCharCode. UTF-8 and UTF-16 are not supported - it is up to the
consumer to get the ArrayBuffer and decode it themselves.
The parameter is a hint, as it's not always used (for example, if the conversion
to text doesn't involve an ArrayBuffer source). Additionally, this leaves the door
open for future implementations to perform more sophisticated encoding detection
and ignore the user-provided value if it can be proven to be incorrect.
Fixes#15932.
PR Close#16420
Currently `new Request({search: ...})` is not honored, and
`new Request({params: {'x': 'y'}) doesn't work either, as this object would have
toString() called. This change allows both of these cases to work, as proved by
the 2 new tests.
Fixes#15761
PR Close#16392
- Moved info bar section in pipe template to be the first section to match other templates
- Fixed label styling for type label
- Added label styling for status label
closes#16521
`LocationService` sends `GaService` a url stripped of fragment and query strings.
`GaService` already guards against re-send of the prior url so it will only report doc changes.
The latest rxjs release works with closure compiler out of the box.
We no longer need to compile our own.
Also put closure options into a file rather than using a shell script.
Previously, non-bracketed inputs (e.g. `xyz="foo"`) on downgraded components
were initialized using `attrs.$observe()` (which uses `$evalAsync()` under the
hood), while bracketed inputs (e.g. `[xyz]="'foo'"`) were initialized using
`$watch()`. If the downgraded component was created during a `$digest` (e.g. by
an `ng-if` watcher), the non-bracketed inputs were not initialized in time for
the initial call to `ngOnChanges()` and `ngOnInit()`.
This commit fixes it by using `$watch()` to initialize all inputs. `$observe()`
is still used for subsequent updates on non-bracketed inputs, because it is more
performant.
Fixes#16212
These utils support flexible, natural attribute interpretation as applied to code-example and code-pane. Then apply those utils to code-example and live-example
This contains a fix for the typescript module reader.
Previously, TS modules that were of the form:
```
a/b/index.ts
```
Would be given the name `index` and id of `a/b/index`.
This is not desirable, so the new version of dgeni-packages/typescript
removes this `index` from the id and name, which results in name of
`b` and id of `a/b`.
Update to in-memory-web-api should handle id=0.
Make sure this works by having a hero with id=0 in ToH.
Coincidentally delete lingering dead app/ folders
Todo: fix ToH images (which have to do anyway)
In the API docs there are occasions where we do not wish the code snippet
to have a copy button. This commit supports that by providing a new `hideCopy`
attribute.
- prevents unsubscribing from the zone on error
- prevents unsubscribing from directive `EventEmitter`s on error
- prevents detaching views in dev mode if there on error
- ensures that `ngOnInit` is only called 1x (also in prod mode)
Fixes#9531Fixes#2413Fixes#15925
Parse all `<img>` tags, during doc-gen, and insert the width and height of
the sourceed image, if neither are already specified.
Warnings are reported if the `<img>` tag has no `src` attribute or the image
cannot be loaded.
The work is done in the `addImageDimensions` post-processor, which must be
configured with a `basePath` so that it knows where to find the images.
Closes#15888
- Changed search result link hover state to white to be more legible
- Increased the max-height on search results container to remove the jitter
- Changed search results to have space-around vs space-between for more appropriate spacing
Reworked some of the code so asserts are no longer necessary.
Added additional and potentially redundant checks
Added checks where the null checker found real problems.
PR Close#16422
Angular uses the `ng-version` attribute to indicate which elements
were used to bootstrap an application. However, after 4.0 we also
added this attribute for all dynamically created components.
Fixes#15880
PR Close#16394
When a directive lives on the same element as a component
(e.g. `<my-comp myDir>`), the directive was not able to get hold
of the `ChangeDetectorRef` of the component on that element. However,
as directives are supposed to decorate components, this is incorrect.
This commit enables this use case.
Closes#12816
The autolinking is now done on the `renderedContent` which means it also
captures and autolinks headings that were generated outside of markdown.
PR Close#16336
Previously the CSS styling for material icons was too broad and affected
all instances of icons. This commit constrains the position of copy button
icons only to copy buttons.
This commit adds a new parameter to ngc named `missingTranslation` to set the MissingTranslationStrategy for AoT, it takes the value `error`, `warning` or `ignore`.
Fixes#15808
PR Close#15987
Because:
1. `docs` feels like a "top level" page, similar to `features`, `resources`, `events` etc.
2. This enables the ServiceWorker to pre-fetch/cache the document (similar to what happens with all
other direct children of `content/docs/`), without the need for special-casing it in
`ngsw-manifest.json`.
- Banner class code consolidation for API pages
- Set up temporary table of contents class and file
- API pages title styling
- Add color styling to doc-type listed on each API details page
- Classes and SCSS variables refactor
- Mobile optimization on headers, info-banner, and API pages
- API page table custom styling
- API Class Overview template code overview into table format
- Content container now has a max width and made the body background the same offwhite color so the cut-off is not visible
- Sidenav will always remain at the left of the page
- Added a max width to the api banner of filter search inputs
- Left aligned content container so it is flush with sidenav
- Changed API filter width to match size of filter results
- Add snackbar and pointer cursor for copy code button inside aio-code components
- Flex cenetered content in features page
- Removed duplicate global css class
- Add styles to links inside of sub-sections
- Remove focus outline on top nav bar links
We were filtering this document from the docs list but
not removing it from the module export lists.
We can actually filter it out much easier at the TypeScript
parsing point, which means we do not need the
`filterIgnoredDocs` processor any more.
Closes#16287
Previously, when using a different property/attribute name for an upgraded
component's binding (e.g. `bindings: {propName: '<attrName'}`), the property and
attribute names were swapped (e.g. using `attrName` as the property name and
`propName` as the attribute name). This resulted in unexpected behavior.
This commit fixes this using the correct names for properties and attributes.
This only affects `upgrade/dynamic`. `upgrade/static` works correctly already.
Fixes#8856
PR Close#16128
The side nav and menu buttons need to appear early on in the loading of the page.
Currently we are using icon fonts with ligatures to get icons for these areas.
This can result in a flash of unstyled font.
By replacing these with SVG icons, we get a better user experience.
By overriding the `MdIconRegistry` we can inline the SVG source, which
means that there will never by a delay in rendering the icons.
The new `CustomMdIconRegistry` expects a multi-provider containing an array
of `SvgIconInfo` objects. These objects hold the name and SVG source of the
icon. When `MdIconComponent` requests an SVG icon we will get it from the
pre-loading cache, if available, before delegating back to the original
`MdIconRegistry`.
Note that SVG versions of `md-icon` do not apply the `material-icons` CSS
class to the element, so the styling for the icons that we are preloading
has been changed to use `.mat-icon` instead.
Closes#16100
This is to tidy up the `author-packagse`, which currently duplicates a
lot of the configuration in the main packages. We need to
DRY this up so that we don't fall foul of a change in one being missed in
the other.
closes#16125
API search still updates query params as sending someone a pre-filtered API search link is handy.
While typing in the search box no longer updates the URL in the addr bar, you can still create a link like `~/?search=animations` and it will open the search dialog and profile the search box as it may be useful to email such a thing to someone.
Previously, the path returned by `LocationService.path()` preserved leading
slashes, which resulted in requests with consequtive slashes in the URL. Such
requests would fail (with a 404) on staging.
This commit fixes it, by removing leading slashes from the path. It also
refactors `LocationService` a bit, converting path to an observable,
`currentPath` (similar to `currentUrl`), and applies certain clean-ups (e.g.
stripping slashes, query, hash) in one place, which simplifies consumption.
Closes#16230
Changed description from h3 to h2 to match the other header
Created api page classes for consistent styling
Add styles for info-bar section
Wrapped pre tags for code not to go off of screen
This helps to ensure that the full docs have been
generated before we begin watching.
You can disable this by providing the `--watch-only`
flag. E.g. `yarn docs-watch -- --watch-only`.
Dgeni is now providing the `id` for all the documents to be viewed. So we
no longer need to add this to the DocumentContents object.
There are some notable changes in the refactoring:
`DocumentService`:
* The id of the document to render is now obtained from `LocationService.path()`.
* The `getFileNotFoundDoc` and `getErrorDoc` methods have been extracted from
the `fetchDocument` method.
`AppComponent`:
* the `pageId` is now computed in a separate `setPageId` method.
`AppComponen` spec file:
* The `TestHttp` has had the hard coded documents removed and replaced with
a function that will generate docs as needed.
* Scrolls to hash element or top of page when no hash.
* Scrolls down a bit (80px) to account for top menu overhang.
* No longer scrolls when the hash element is not found.
* Adds `<a id="top-of-page"></a>` which will benefit future efforts to
navigate there from within a page.
Index: Changed h3s to h2s given hierarchy
Index: Aligned text and image blocks to be centered
Index: Announcement bar button darkened for appropriate contrast
Search Results: Changed to list items in unordered list to accommodate accessibility and updated styles accordingly
closure compiler warns in generated .ngfactory.ts files:
```
WARNING - property createInternal already defined on superclass module$contents$..$core$src$linker$ng_module_factory_NgModuleInjector; use @override to override it
```
PR Close#16137
Fixed capitalization in sidenav menu items
Add min height property to sidenav-content for better viewing on short pages or high resolution screens
Add dividier between change log items as before to h2
Table adjustments to reduce off-screen items
Update home page banner text and icon change, and fix banner img and mobile alignment
Fix and add links in doc landing page and change card footer text to reflect correct name
Removed docs landing page to rebase with master
PR Close#16138
Angular change detection bug -> no page update on resize.
Reverting to `@HostListener('window:resize', ['$event.target.innerWidth'])` cures it.
Delete DeviceService which no longer serves a purpose.
Adjusted affected AppComponent and LiveExample tests.
PR Close#16143
There are external resources that link to the old URLs. In order to avoid
breaking them, the old URLs are redirected to the new ones.
Fixes#15795Closes#16133
PR Close#16162
Previously, due ot a limitation/bug in AoT compilation and `useValue`, the
`global` injected into `SwUpdateNotificationsService` was always undefined,
which prevented it from actually reloading the page after activating a
ServiceWorker update.
This commit fixes it by switching to `useFactory`, which works correctly with
AoT.
Aligned padding to fit beneath the top nav
Add scroll bar styling inside sidenav menu
Increased font size of h2 to be different from h3 for better legibility
Now if you specifically provide an empty `@title` tag
for a contents file, the doc-gen will not complain and
the browser will just display a reasonable default.
Add visually hidden class and apply to h2 in search results
Changed h2 group headers to h3s
Add roles to main and content
Fix API material icon placement
Image alt additions where needed
Add lang attribute to html tag
Add aria-label on search input
If a document provided a title jsdoc tag then its h1
element was being rendered incorrectly as a markdown
paragraph.
This change renders the title as a markdown h1 tag
directly.
Fixes#16099
Previously, the `AppComponent.pageId` was set via the current URL, rather than
the document being displayed. This is only really noticeable when the URL does not
match a valid doc and we are actually displaying a 404 page.
Now we compute the `pageId` from the URL of the document being viewed,
which is returned from the `DocumentService.currentDocument` observable instead.
I found that VS Code was taking an age to bring up the intellisense
for TypeScript source files in the `aio/src` folder.
I believe that this is because it was trying to parse all the files in
the `aio/content/examples` folder as well, which is not relevant to the
web app development.
This change restricts the root `aio/tsconfig.json` to only the entry points
for the app, the unit tests and e2e tests.
Documents can specify their title via the `title` or `name` jsdoc tags.
This change adds that, if neither are provided, the first `<h1>` element
is removed from the `renderedContent` and used for the title.
If there is still no title then it is set to the empty string and a warning
is logged.
contributor fix
contributor card styling updates
button styling and container size fix
remove button and add image border
selection filter for buttons
header only show when group selected and styles
initial flip card funcitonality and data change
selected buttons styling
complete flip func and card style
flip feature
contributor group changes
fixes
This only shows up in the language service. Calls to symbols
that are not resolve resulted in null instead of being resolved
causing the language service to see exceptions when the null
was not expected such as in the animations array.
Fixes#15969
- always have a value for `angular`, even if no angular is on the page
- use `const` instead of `function` to allow to export a variable `module`
without breaking tsickle / closure.
Language service was treating some alias TypeScript symbols as if
they where the canonical symbol. If the symbol in scope is an alias
of another symbol the symbol should be converted to the canonical
symbol.
This task is suitable for day to day docs authoring.
This task cuts corners, which makes it much faster than a full `yarn docs`
run but it does not produce completely valid output.
In general this isgood enough for authors to see their changes as they make them.
The task is triggered by a call to
```
yarn docs-watch
```
This sets up watchers on the `aio/contents` and `packages` folders.
Any changes to files below these folders new doc generation run to start.
The input to the generation is confined to a collection of files related
to the changed file. For example:
* a change to a file in `aio/content/marketing` will generate all the
marketing files.
* a change to a file in `aio/content/tutorial` or `aio/examples/toh-*`
will generate all the tutorial files (and their embedded examples).
* a change to a file in `aio/guide` or `aio/examples` (but not a `toh-`
example) will generate the appropriate guide and its embedded examples
* a change to a file in `packages` or `packages/examples` will generate
the appropriate API doc and its embedded examples.
Be aware that the mapping between docs and its examples are based on doc file
and example folder structure being equivalent. Sometimes a doc will reference
an example in a different folder, in which case the generated doc will be
inaccurate. Mostly this is not a big problem.
When content pages were short, the footer would take up a large part
of the display area and the side nav would look like it was shorter than
it really was.
This change moves the footer into the main content area so that the
nav always extends to the full length the browser.
Regular plunker is unusable on narrow screen
Refactors LiveExampleComponent and adds tests.
Refactor width detection to `DeviceService` because need to know width change in 2 places.
Keep “disable” option add in earlier spikes because simple and potentially useful in future.
Currently, running `yarn test-pwa-score` right after deploying to staging fails
with the error:
```
{ Error: Unable to load the page: timeout reached ... code: 'PAGE_LOAD_ERROR' }
```
As a temporary fix, this commit prevents the build from failing because of PWA
score errors (until we identify the cause and fix it).
Display area names in all caps
Exclude results with no title because they don’t show & can’t be clicked.
Should find these and give their docs a title.
- Ensure that the result passes OASIS XLIFF 2.0 schema validation
- Use <ph/> for self-closing placeholder tags
- Use <pc></pc> for other placeholder tags
- Check for the correct XLIFF file version
- Add ICU support
fixes#11735
This only shows up in the language service. Calls to symbols
that are not resolve resulted in null instead of being resolved
causing the language service to see exceptions when the null
was not expected such as in the animations array.
Fixes#15969
Previously, only a few characters of the SHA would appear on the preview link
comment posted on the PR. This was usually enough for GitHub to create a link to
the corresponding commit, but it was possible to have collisions with other
commits with the same first characters (which prevented GitHub from identifying
the correct commit and create a link.)
This commit fixes this issue by including the full SHA on the commentso GitHub
can identify the correct commit and create the link. GitHub will automatically
truncate the link text (by default to 7 chars unless more are necessary to
uniquely identify the commit).
Previously, when trying to upload the build artifacts for a PR/SHA that was
already successfully deployed (e.g. when re-running a Travis job), the preview
server would return a 403 and the build would fail.
Since we have other mechanisms to verify that the PR author is trusted and the
artifacts do indeed come from the specified PR and since the new artifacts
should be the same with the already deployed ones (same SHA), there is no reason
to fail the build. The preview server will reject the request with a special
HTTP status code (409 - Conflict), which the `deploy-preview` script will
recognize and exit with 0.
Don’t show the side nav in mobile (not side-by-side) view when arriving or navigating.
Only show it by request.
The side nav should continue to appear in wide mode (side-by-side) when navigating from a marketing page to a guide page.
The implementation adds three plugins to the remark processor:
* remove support for code blocks triggered by indented
text - only gfm triple backticks are supported; and also adds support for
dgeni inline tags.
* ignore content within `code-example` and `code-tabs` elements. This prevents
the content being accidentally treated as markdown
* ignore dgeni inline tags, e.g. `{@link ... }` to prevent the content of
the links from being accidentally treated as markdown
* Fixes that `tsc-wrapped` stores invalid path separators in the bundled metadata files. Previous errors could have been: `Cannot find module '.corecoordinationnique-selection-dispatcher'.` (See https://github.com/angular/material2/issues/3834)
* Fixes failing tests on Windows. Now all tooling tests are green on Windows.
Related to #15403
Sometimes, depending on the length of lines, anchor elements would be formatted
incorrectly by `html.prettyPrint` and the space right after the element was
removed.
This was apparently caused by a bug in `html.prettyPrint` in combination with
its default behavior of wrapping lines at a specific limit (70 chars). Since the
output is only meant to be used as JSON string data, wrapping the lines makes it
less readable by adding unnecessary `\n`.
This commit disables the line wrapping, which effectively avoids the bug that
was responsible for incorrectly formatting anchor elements and surrounding
space.
Related to #15681.
This version changes the expected syntax for emphasis.
The original Rho renderer uses `*` for strong an `_` for em.
But it is more standard in markdown to use `**` or `__` for bold
and `*` or `_` for em.
Allows to inherit ctor args, lifecycle hooks and statics from a class
in another compilation unit.
Will error if trying to inherit from a class in another compilation unit
that has an `@Component` / `@Directive` / `@Pipe` / `@NgModule`.
DebugServices is parsing false atributes values incorrectly.
Parse5 expects a string value for attributes, but currently boolean is being sent.
Closes#15494
The markdown renderer passes its output through an HTML pretty printer.
While this is good in most cases, it makes a mess of elements that expect
their content to be left untouched.
The pretty printer already ignores `pre` tags (and other built-ins) by
default. This fix allows us to specify other tags that should be left
alone.
Further it actually specifies this option for `code-example` and `code-pane`
tags, which expect to contain preformatted content.
Fixes#15528
What is the current behavior?
The language service access TypeScript's Symbol.members without checking for null or undefined.
What is the new behavior?
The access is guarded.
This processor will eventually replace the `{@example}` inline tags
because it provides a cleaner approach that also supports tabbed examples
straight out of the box.
The idea is that authors will simply add a `path` and (optionally) a `region`
attribute to `<code-example>` or `<code-pane>` elements in their docs.
This indicates to dgeni that the relevant example needs to be injected
into the content of this element.
For example, assume that there is an example file `toh-pt1/index.hml` with
a region called `title`, which looks like:
```
<h1>Tour of Heroes</h1>
```
Then the document author could get this to appear in the docs as a
standalone example:
```
<code-example path="toh-pt1" region="title"></code-example>
```
Or as part of a tabbed group:
```
<code-tabs>
<code-pane path="toh-pt1" region="title"></code-pane>
</code-tabs>
```
If no `path` attribute is provided then the element is ignored, which
enables authors to provide inline code instead:
```
<code-example>
Some <html> escaped code
</code-example>
```
Also all attributes other than `path` and `region` are ignored and passed
through to the final rendered output allowing the author to provide
styling hints:
```
<code-example path="toh-pt1" region="title" linenums"15" class="important">
</code-example>
```
Fixes#14417
Updated example to illustrate @ContentChildren default behavior (only query direct children), and how to query for nested elements/all descendants.
This has the side effect of allowing `@Input` and `@ContentChild`
on the same property if the query is static (see the bug description
for details).
Fixes#15417
Previously, all URLs were rewritten to `index.html` in order to support
deep-linking. This works when navigating to URLs that correspond to existing
resources. E.g. navigating to `/tutorial` returns `index.html` and then the
`DocViewer` takes over and requests `tutorial.json`.
Navigating to a non-existent URL (e.g. `/foo`), will return `index.html`, which
in turn requests (the non-existent) `foo.json` and throws an error when trying
to parse the returned `index.html` as JSON.
This commit fixes it by only rewriting URLs that do not request a file (i.e. do
not include a `.` in the last path segment).
Fixes#15398
To generate XLF files with ng-xi18n we could use the format parameter "xlf" or "xlif". The real name is "xliff" not "xlif", so this probably was a typo. This PR adds "xliff" as can be expected
This reverts commit d0bc83ca27.
Protractor-based prerendering is flakey on Travis and takes several minutes to
complete, slowing down the build. Prerendering has a lower impact now that we
use a ServiceWorker. We will revisit in the future (probably using a
`PlatformServer`-based approach).
PR Close#15346
`ngc` would look for flat module resources relative to the flat module index.
`ngc` now looks for flat module resources relative to the `.d.ts` file that declarates
the component.
Fixes#15221
PR Close#15367
Added an "origins" section to the flat module `.metadata.json` files
that records where the original symbols was declared. This allows
correctly calculating relative path references recorded in metadata.
This commit fixes a regression where `ngModel` no longer syncs
letter by letter on Android devices, and instead syncs at the
end of every word. This broke when we introduced buffering of
IME events so IMEs like Pinyin keyboards or Katakana keyboards
wouldn't display composition strings. Unfortunately, iOS devices
and Android devices have opposite event behavior. Whereas iOS
devices fire composition events for IME keyboards only, Android
fires composition events for Latin-language keyboards. For
this reason, languages like English don't work as expected on
Android if we always buffer. So to support both platforms,
composition string buffering will only be turned on by default
for non-Android devices.
However, we have also added a `COMPOSITION_BUFFER_MODE` token
to make this configurable by the application. In some cases, apps
might might still want to receive intermediate values. For example,
some inputs begin searching based on Latin letters before a
character selection is made.
As a provider, this is fairly flexible. If you want to turn
composition buffering off, simply provide the token at the top
level:
```ts
providers: [
{provide: COMPOSITION_BUFFER_MODE, useValue: false}
]
```
Or, if you want to change the mode based on locale or platform,
you can use a factory:
```ts
import {shouldUseBuffering} from 'my/lib';
....
providers: [
{provide: COMPOSITION_BUFFER_MODE, useFactory: shouldUseBuffering}
]
```
Closes#15079.
PR Close#15256
This shouldn't change anything. But it's interesting that we used to have this import
that seemed bogus, but there were no compilation or rutime errors.
Content pages like `tutorial/index.md` were being mapped to `tutorial.index.json`,
which meant that they could only be rendered if you browsed to `/tutorial/index`.
This didn't sit well so now these pages are mapped to `tutorial.json`, which
means that you browser to them via `/tutorial/` or just `/tutorial`.
Fixed#15335
The navigation.json is now passed through the dgeni pipeline.
The source file has been moved to `aio/content/navigation.json`
but the generated file will now appear where the original source file
was found, `aio/src/content/navigation.json`.
Everything inside `aio/src/content` is now generated and ignored by git.
The `processNavigationMap` processor in this commit adds the current version
information to the navigation.json file and verifies the relative urls in
the file map to real documents.
The navigationService exposes the versionInfo as an observable, which the
AppComponent renders at the top of the sidenav.
The navigation.json is now passed through the dgeni pipeline.
The source file has been moved to `aio/content/navigation.json`
but the generated file will now appear where the original source file
was found, `aio/src/content/navigation.json`.
Everything inside `aio/src/content` is now generated and ignored by git.
The `processNavigationMap` processor in this commit adds the current version
information to the navigation.json file and verifies the relative urls in
the file map to real documents.
The navigationService exposes the versionInfo as an observable, which the
AppComponent renders at the top of the sidenav.
The original Rho is too strict when it comes to markdown headings.
It requires that there be a blank line separating the heading and the
next paragraph. The forked version here fixes that; but the Rho project
will not merge it as it goes against there basic rules.
Unlike in the browser, on the server there is no concept of a document origin.
Thus, it is illegal to make requests for relative URLs against Http on platform-server.
Currently this fails with a vague error:
Error: Uncaught (in promise): Error at resolvePromise
This change adds explicit validation and a friendlier error message:
Error: URLs requested via Http on the server must be absolute. URL: /testing
Another option considered was to track the concept of an origin for the platform
and automatically prepend it to relative URLs. This would cause automatic "local
RPCs" to be made, though, which would be an unexpected and undesirable default
behavior.
Fixes#15349
PR Close#15357
This change reduces the amount of generated code by only adding `log`
calls for elements and text nodes.
We need the `log` calls to allow users to jump to the right place
in the template via source maps. However, we only need it for element
and text nodes, but not for directives, queries, … as for them we
first locate the corresponding element or text node.
Related to #15239
PR Close#15350
This is needed to support the corner cases:
- usage of a `ComponentFactory` that was created on the fly via `Compiler`
- overwriting of the `NgModuleRef` that is associated to a
`ComponentFactory` by the `ComponentFactoryResolver` from
which it was read.
Fixes#15241
We extracted ids from i18n attributes but forgot to use them when merging the translations, resulting in an error about missing translations even when they were correctly defined.
Fixes#15234
PR Close#15302
If a directive has not bindings nor has a `ngDoCheck` / `ngOnInit`
lifecycle hook, don’t generate a `check` call.
This does not have an impact on the behavior, but produces
less code.
PR Close#15322
This reverts commit 8b5c6b2732.
This feature is not compatible with the `Injector.get` which now only
takes `Type` or `InjectableToken`. `Symbol` is not a valid type.
Closes#15183
PR Close#15319
The Router use the type `Params` for all of:
- position parameters,
- matrix parameters,
- query parameters.
`Params` is defined as follow `type Params = {[key: string]: any}`
Because parameters can either have single or multiple values, the type should
actually be `type Params = {[key: string]: string | string[]}`.
The client code often assumes that parameters have single values, as in the
following exemple:
```
class MyComponent {
sessionId: Observable<string>;
constructor(private route: ActivatedRoute) {}
ngOnInit() {
this.sessionId = this.route
.queryParams
.map(params => params['session_id'] || 'None');
}
}
```
The problem here is that `params['session_id']` could be `string` or `string[]`
but the error is not caught at build time because of the `any` type.
Fixing the type as describe above would break the build because `sessionId`
would becomes an `Observable<string | string[]>`.
However the client code knows if it expects a single or multiple values. By
using the new `ParamMap` interface the user code can decide when it needs a
single value (calling `ParamMap.get(): string`) or multiple values (calling
`ParamMap.getAll(): string[]`).
The above exemple should be rewritten as:
```
class MyComponent {
sessionId: Observable<string>;
constructor(private route: ActivatedRoute) {}
ngOnInit() {
this.sessionId = this.route
.queryParamMap
.map(paramMap => paramMap.get('session_id') || 'None');
}
}
```
Added APIs:
- `interface ParamMap`,
- `ActivatedRoute.paramMap: ParamMap`,
- `ActivatedRoute.queryParamMap: ParamMap`,
- `ActivatedRouteSnapshot.paramMap: ParamMap`,
- `ActivatedRouteSnapshot.queryParamMap: ParamMap`,
- `UrlSegment.parameterMap: ParamMap`
Previously, a pipe that returned a `WrappedValue` would force the change
of the next bound property, independent of the binding in which the pipe
was used.
Now only the binding in which the `WrappedValue` is used will be assumed
as changed.
Fixes#15116
PR Close#15257
This is so that server side rendering does not throw an exception when it encounters animations on the server side and does not need the user to explicitly setup NoopAnimationsModule in their app server module.
Fixes#15098, #14784.
PR Close#15131
Closure compiler is very sensitive to top level function calls.
This commit makes the function calls `createComponentFactory`
and `createRendererTypeV2` logic-less.
Fixes#15181
PR Close#15214
DEPRECATION:
- the arguments `inputs` / `outputs` / `ngContentSelectors` of `downgradeComponent`
are no longer used as Angular calculates these automatically now.
- Compiler.getNgContentSelectors is deprecated. Use
ComponentFactory.ngContentSelectors instead.
E.g. for a component like this:
```
@Component({
template: ‘<ng-content select=“child”></ng-content>’
})
class MyComp {
@Input(‘aInputName’)
aInputProp: string;
@Output(‘aEventName’)
aOuputProp: EventEmitter<any>;
}
```
the `ComponentFactory` will now contain the following:
- `inputs = {aInputProp: ‘aInputName’}`
- `outputs = {aOutputProp: ‘aOutputName’}`
- `ngContentSelectors = [‘child’]`
Fixes:
- In G3, filePaths don’t start with a `/` and therefore became relative.
- Always using the `ng://` prefix groups angular resources in the same
way for AOT and JIT.
ErrorHandler can not throw errors because it will unsubscribe itself from
the error stream.
Zones captures errors and feed it into NgZone, which than has a Rx Observable
to feed it into ErrorHandler. If the ErroHandler throws, then Rx will teardown
the observable which in essence causes the ErrorHandler to be removed from the
error handling. This implies that the ErrorHandler can never throw errors.
Closes#14949Closes#15182Closes#14316
Inlcuded fixes:
- include preamble in generated source map
- always add a mapping for line/col 0 so that the
generated sourcemap is not sparse
- use a uniue sourceUrl for inline templates even
in the AOT case
Update tsickle to version 0.21.6 which fixes a bug where input source maps which specified filenames differently than the names supplied to tsc didn't get composed with tsc's source maps. Also adds a test that the bug was fixed.
Previous to 2.x there were some source maps distrubted, but they didn't go
all the way back to the TypeScript sources and they weren't available for
all JavaScript distrubted to NPM.
With this change source maps will be available for FESM distributions as
well as UMD and will go all the way back to TypeScript sources.
Fixes#15184
Observable subscriptions from previous validation runs should be canceled
before a new subscription is created for the next validation run.
Currently the subscription that sets the errors is canceled properly,
but the source observable created by the validator is not. While this
does not affect validation status or error setting, the source
observables will incorrectly continue through the pipeline until they
complete. This change ensures that the whole stream is canceled.
AsyncValidatorFn previously had an "any" return type, but now it more
explicitly requires a Promise or Observable return type. We don't
anticipate this causing problems given that any other return type
would have caused a runtime error already.
Previously, style values were parsed with a regex that split on /:+/.
This causes errors for CSS such as
div {
background-url: url(http://server.com/img.png);
}
since the regex would split the background-url line into 3 values instead of 2.
Now, the : character is detected with indexOf, avoiding this error.
A test was added to verify the behavior is correct.
Implemented style guide elements to top header bar, side hamburger nav menu, content and search. Consolidated SCSS files to styles folder. Fixed PWA test.
The input may still have focus when the user hits ESC,
causing the search to be hidden.
If the user then clicks on the input again, they would expect
it to reopen the results.
DEPRECATION:
- the arguments `inputs` / `outputs` / `ngContentSelectors` of `downgradeComponent`
are no longer used as Angular calculates these automatically now.
- Compiler.getNgContentSelectors is deprecated. Use
ComponentFactory.ngContentSelectors instead.
E.g. for a component like this:
```
@Component({
template: ‘<ng-content select=“child”></ng-content>’
})
class MyComp {
@Input(‘aInputName’)
aInputProp: string;
@Output(‘aEventName’)
aOuputProp: EventEmitter<any>;
}
```
the `ComponentFactory` will now contain the following:
- `inputs = {aInputProp: ‘aInputName’}`
- `outputs = {aOutputProp: ‘aOutputName’}`
- `ngContentSelectors = [‘child’]`
In order for tsickle's new support for input source maps to work, the tsickleCompilerHost must be used for the initial load of source files, since that's when the inline source maps are read and stripped.
* feat(common): support `as` syntax in template/* bindings
Closes#15020
Showing the new and the equivalent old syntax.
- `*ngIf="exp as var1”`
=> `*ngIf="exp; let var1 = ngIf”`
- `*ngFor="var item of itemsStream |async as items”`
=> `*ngFor="var item of itemsStream |async; let items = ngForOf”`
* feat(common): convert ngIf to use `*ngIf="exp as local“` syntax
* feat(common): convert ngForOf to use `*ngFor=“let i of exp as local“` syntax
* feat(common): expose NgForOfContext and NgIfContext
In v2.x, users had to annotate classes that they intended to use as tokens with `@Injectable`. This is no longer required in v4.x for tokens,
and we now require the constructor parameters of classes annotated
with `@Injectable` to be statically analyzable by ngc.
This commit reduces the error into a warning
if the constructor parameters do not meet this condition.
DEPRECATION:
- Classes annotated with `@Injectable` but whose constructor’s parameter types
are not statically analyzable by ngc will produce a warning.
Closes#15003
Throwing on query changes would be a breaking change compared to v2.
Also discovers a bug with querying manually projected content, see #15117.
Related to #14748Closes#14925
Currently, it says:
Unexpected value 'FuzzyTimePipe in
javascript/angular2/example/search/fuzzy_time.ts' declared by the module
'SearchModule in javascript/angular2/example/search/search_module.ts'
The new error message also suggests: 'Please add a @Pipe/@Directive/@Component annotation.'
fixes#12869fixes#12889fixes#13885fixes#13870
Before this change there was a single injector tree.
Now we have 2 injector trees, one for the modules and one for the components.
This fixes lazy loading modules.
See the design docs for details:
https://docs.google.com/document/d/1OEUIwc-s69l1o97K0wBd_-Lth5BBxir1KuCRWklTlI4
BREAKING CHANGES
`ComponentFactory.create()` takes an extra optional `NgModuleRef` parameter.
No change should be required in user code as the correct module will be used
when none is provided
DEPRECATIONS
The following methods were used internally and are no more required:
- `RouterOutlet.locationFactoryResolver`
- `RouterOutlet.locationInjector`
This API was introduced only in a beta release, and is being removed because we found it to be incorrect prior to launch. For more information about why this is being removed, see https://github.com/angular/angular/pull/15050.
BREAKING CHANGE:
Perviously, any provider that had an ngOnDestroy lifecycle hook would be created eagerly.
Now, only classes that are annotated with @Component, @Directive, @Pipe, @NgModule are eager. Providers only become eager if they are either directly or transitively injected into one of the above.
This also makes all `useValue` providers eager, which
should have no observable impact other than code size.
EXPECTED IMPACT:
Making providers eager was an incorrect behavior and never documented.
Also, providers that are used by a directive / pipe / ngModule stay eager.
So the impact should be rather small.
Fixes#14552
The main use case for the generated source maps is to give
errors a meaningful context in terms of the original source
that the user wrote.
Related changes that are included in this commit:
* renamed virtual folders used for jit:
* ng://<module type>/module.ngfactory.js
* ng://<module type>/<comp type>.ngfactory.js
* ng://<module type>/<comp type>.html (for inline templates)
* error logging:
* all errors that happen in templates are logged
from the place of the nearest element.
* instead of logging error messages and stacks separately,
we log the actual error. This is needed so that browsers apply
source maps to the stack correctly.
* error type and error is logged as one log entry.
Note that long-stack-trace zone has a bug that
disables source maps for stack traces,
see https://github.com/angular/zone.js/issues/661.
BREAKING CHANGE:
- DebugNode.source no more returns the source location of a node.
Closes 14013
The migrator was updated to automatically fix these links.
See fca5fb0280
and 3927b7a038
The result of this is that, going forward, we should ask
authors to include the path from the base href to the thing
being linked. E.g. guide/architecture#intro
* Ensure that all indexed documents are displayed in the search results.
(Previously the guide documents were not appearing because we only showed
results that had a `name` property, rather than a `name` or `title`.)
* Group the results by their containing folder (e.g. api, guide, tutorial, etc).
* Hide the results when the user hits the ESC key.
* Hide the results when the user clicks on a search result
Closes#14852
Adds tests and fixes corners cases for both `search()` and `setSearc()`
for things like empty queries and param keys that need encoding.
This commit refactors the `LocationService` to rely upon the `PlatformLocation`
rather than using `window.history` directly. This makes testing easier but also
makes the code simpler since `PlatformLocation` deals with platforms that
do not support history for us.
This can be used to e.g. add the NoopAnimationsModule by default:
```
TestBed.initTestEnvironment([
BrowserDynamicTestingModule,
NoopAnimationsModule
], platformBrowserDynamicTesting());
```
<!-- Check whether this is still an issue in the most recent Angular version -->
* **Browser:** [all | Chrome XX | Firefox XX | IE XX | Safari XX | Mobile Chrome XX | Android X.X Web Browser | iOS XX Safari | iOS XX UIWebView | iOS XX WKWebView ]
<!-- All browsers where this could be reproduced -->
@ -17,15 +17,15 @@ Help us keep Angular open and inclusive. Please read and follow our [Code of Con
## <a name="question"></a> Got a Question or Problem?
Please, do not open issues for the general support questions as we want to keep GitHub issues for bug reports and feature requests. You've got much better chances of getting your question answered on [StackOverflow](https://stackoverflow.com/questions/tagged/angular) where the questions should be tagged with tag `angular`.
Do not open issues for general support questions as we want to keep GitHub issues for bug reports and feature requests. You've got much better chances of getting your question answered on [StackOverflow](https://stackoverflow.com/questions/tagged/angular) where the questions should be tagged with tag `angular`.
StackOverflow is a much better place to ask questions since:
StackOverflow is a much better place to ask questions since:
- there are thousands of people willing to help on StackOverflow
- there are thousands of people willing to help on StackOverflow
- questions and answers stay available for public viewing so your question / answer might help someone else
- StackOverflow's voting system assures that the best answers are prominently visible.
- StackOverflow's voting system assures that the best answers are prominently visible.
To save your and our time we will be systematically closing all the issues that are requests for general support and redirecting people to StackOverflow.
To save your and our time, we will systematically close all issues that are requests for general support and redirect people to StackOverflow.
If you would like to chat about the question in real-time, you can reach out via [our gitter channel][gitter].
@ -147,7 +147,7 @@ To ensure consistency throughout the source code, keep these rules in mind as yo
* All public API methods **must be documented**. (Details TBC).
* We follow [Google's JavaScript Style Guide][js-style-guide], but wrap all code at
**100 characters**. An automated formatter is available, see
* **perf**: A code change that improves performance
* **refactor**: A code change that neither fixes a bug nor adds a feature
* **style**: Changes that do not affect the meaning of the code (white-space, formatting, missing
semi-colons, etc)
* **style**: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
* **test**: Adding missing tests or correcting existing tests
### Scope
@ -207,6 +206,7 @@ The scope should be the name of the npm package affected (as perceived by person
The following is the list of supported scopes:
* **animations**
* **common**
* **compiler**
* **compiler-cli**
@ -223,7 +223,7 @@ The following is the list of supported scopes:
* **upgrade**
* **tsc-wrapped**
There is currently few exception to the "use package name" rule:
There are currently a few exceptions to the "use package name" rule:
* **packaging**: used for changes that change the npm package layout in all of our packages, e.g. public path changes, package.json changes done to all packages, d.ts file/format changes, changes to bundles, etc.
* **changelog**: used for updating the release notes in CHANGELOG.md
@ -263,7 +263,7 @@ changes to be accepted, the CLA must be signed. It's a quick process, we promise
[](https://gitter.im/angular/angular?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
This project was generated with [angular-cli](https://github.com/angular/angular-cli) version 1.0.0-beta.26.
Everything in this folder is part of the documentation project. This includes
## Development server
Run `ng serve` for a dev server. Navigate to `http://localhost:4200/`. The app will automatically reload if you change any of the source files.
* the web site for displaying the documentation
* the dgeni configuration for converting source files to rendered files thatcan be viewed in the web site.
* the tooling for setting up examples for development; and generating plunkers and zip files from the examples.
## Code scaffolding
## Developer tasks
Run `ng generate component component-name` to generate a new component. You can also use `ng generate directive/pipe/service/class/module`.
We use `yarn` to manage the dependencies and to run build tasks.
You should run all these tasks from the `angular/aio` folder.
Here are the most important tasks you might need to use:
## Build
*`yarn` - install all the dependencies.
*`yarn setup` - Install all the dependencies, boilerplate, plunkers, zips and runs dgeni on the docs.
Run `ng build` to build the project. The build artifacts will be stored in the `dist/` directory. Use the `--prod` flag for a production build.
*`yarn start` - run a development web server that watches the files; then builds the doc-viewer and reloads the page, as necessary.
*`yarn serve-and-sync` - run both the `docs-watch` and `start` in the same console.
*`yarn lint` - check that the doc-viewer code follows our style rules.
*`yarn test` - watch all the source files, for the doc-viewer, and run all the unit tests when any change.
*`yarn e2e` - run all the e2e tests for the doc-viewer.
## Running unit tests
*`yarn docs` - generate all the docs from the source files.
*`yarn docs-watch` - watch the Angular source and the docs files and run a short-circuited doc-gen for the docs that changed.
*`yarn docs-lint` - check that the doc gen code follows our style rules.
*`yarn docs-test` - run the unit tests for the doc generation code.
Run `ng test` to execute the unit tests via [Karma](https://karma-runner.github.io).
*`yarn boilerplate:add` - generate all the boilerplate code for the examples, so that they can be run locally.
*`yarn boilerplate:remove` - remove all the boilerplate code that was added via `yarn boilerplate:add`.
*`yarn generate-plunkers` - generate the plunker files that are used by the `live-example` tags in the docs.
*`yarn generate-zips` - generate the zip files from the examples. Zip available via the `live-example` tags in the docs.
## Running end-to-end tests
*`yarn example-e2e` - run all e2e tests for examples
-`yarn example-e2e -- --setup` - force webdriver update & other setup, then run tests
-`yarn example-e2e -- --filter=foo` - limit e2e tests to those containing the word "foo"
Run `ng e2e` to execute the end-to-end tests via [Protractor](http://www.protractortest.org/).
Before running the tests make sure you are serving the app via `ng serve`.
*`yarn build-ie-polyfills` - generates a js file of polyfills that can be loaded in Internet Explorer.
## Deploying to GitHub Pages
## Using ServiceWorker locally
Run `ng github-pages:deploy` to deploy to GitHub Pages.
Since abb36e3cb, running `yarn start -- --prod` will no longer set up the ServiceWorker, which
would require manually running `yarn sw-manifest` and `yarn sw-copy` (something that is not possible
with webpack serving the files from memory).
## Further help
If you want to test ServiceWorker locally, you can use `yarn build` and serve the files in `dist/`
with `yarn http-server -- dist -p 4200`.
To get more help on the `angular-cli` use `ng help` or go check out the [Angular-CLI README](https://github.com/angular/angular-cli/blob/master/README.md).
For more details see #16745.
## Guide to authoring
There are two types of content in the documentatation:
* **API docs**: descriptions of the modules, classes, interfaces, decorators, etc that make up the Angular platform.
API docs are generated directly from the source code.
The source code is contained in TypeScript files, located in the `angular/packages` folder.
Each API item may have a preceding comment, which contains JSDoc style tags and content.
The content is written in markdown.
* **Other content**: guides, tutorials, and other marketing material.
All other content is written using markdown in text files, located in the `angular/aio/content` folder.
More specifically, there are sub-folders that contain particular types of content: guides, tutorial and marketing.
We use the [dgeni](https://github.com/angular/dgeni) tool to convert these files into docs that can be viewed in the doc-viewer.
The [Authors Style Guide](https://angular.io/guide/docs-style-guide) prescribes guidelines for
writing guide pages, explains how to use the documentation classes and components, and how to markup sample source code to produce code snippets.
### Generating the complete docs
The main task for generating the docs is `yarn docs`. This will process all the source files (API and other),
extracting the documentation and generating JSON files that can be consumed by the doc-viewer.
### Partial doc generation for editors
Full doc generation can take up to one minute. That's too slow for efficient document creation and editing.
You can make small changes in a smart editor that displays formatted markdown:
>In VS Code, _Cmd-K, V_ opens markdown preview in side pane; _Cmd-B_ toggles left sidebar
You also want to see those changes displayed properly in the doc viewer
with a quick, edit/view cycle time.
For this purpose, use the `yarn docs-watch` task, which watches for changes to source files and only
re-processes the the files necessary to generate the docs that are related to the file that has changed.
Since this task takes shortcuts, it is much faster (often less than 1 second) but it won't produce full
fidelity content. For example, links to other docs and code examples may not render correctly. This is
most particularly noticed in links to other docs and in the embedded examples, which may not always render
correctly.
The general setup is as follows:
* Open a terminal, ensure the dependencies are installed; run an initial doc generation; then start the doc-viewer:
```bash
yarn
yarn docs
yarn start
```
* Open a second terminal and start watching the docs
```bash
yarn docs-watch
```
* Open a browser at https://localhost:4200/ and navigate to the document on which you want to work.
You can automatically open the browser by using `yarn start -- -o` in the first terminal.
* Make changes to the page's associated doc or example files. Every time a file is saved, the doc will
be regenerated, the app will rebuild and the page will reload.
Bootstraps the app, using the root component from the specified `NgModule`. {@target js}Must be wrapped in the event listener to fire when the page loads.{@endtarget}
Binds the presence of CSS classes on the element to the truthiness of the associated map values. The right-hand expression should return {class-name: true/false} map.
{@target ts}Declares that a class has dependencies that should be injected into the constructor when the dependency injector is creating an instance of this class.
{@endtarget}
{@target js}
Declares a service to inject into a class by providing an array with the services, with the final item being the function to receive the injected services.
Creates a link to a different view based on a route instruction consisting of a route path, required and optional parameters, query parameters, and a fragment. To navigate to a root route, use the `/` prefix; for a child route, use the `./`prefix; for a sibling or parent, use the `../` prefix.
An interface for defining a class that the router should call first to determine if it should activate this component. Should return a boolean or an Observable/Promise that resolves to a boolean.
An interface for defining a class that the router should call first to determine if it should deactivate this component after a navigation. Should return a boolean or an Observable/Promise that resolves to a boolean.
An interface for defining a class that the router should call first to determine if it should activate the child route. Should return a boolean or an Observable/Promise that resolves to a boolean.
@cheatsheetItem
syntax(ts):
`class ResolveGuard implements Resolve<T> {
resolve(
route: ActivatedRouteSnapshot,
state: RouterStateSnapshot
): Observable<any>|Promise<any>|any { ... }
}
{ path: ..., resolve: [ResolveGuard] }`|`Resolve`
syntax(js):
`var ResolveGuard = ng.core.Class({
resolve: function(route, state) {
// return Observable/Promise value or value
}
});
{ path: ..., resolve: [ResolveGuard] }`|`Resolve`
description:
An interface for defining a class that the router should call first to resolve route data before rendering the route. Should return a value or an Observable/Promise that resolves to a value.
An interface for defining a class that the router should call first to check if the lazy loaded module should be loaded. Should return a boolean or an Observable/Promise that resolves to a boolean.
Calls method `readRainbow` when a click event is triggered on this button element (or its children) and passes in the event object.
@cheatsheetItem
syntax:
`<div title="Hello {{ponyName}}">`|`{{ponyName}}`
description:
Binds a property to an interpolated string, for example, "Hello Seabiscuit". Equivalent to:
`<div [title]="'Hello ' + ponyName">`
@cheatsheetItem
syntax:
`<p>Hello {{ponyName}}</p>`|`{{ponyName}}`
description:
Binds text content to an interpolated string, for example, "Hello Seabiscuit".
@cheatsheetItem
syntax:
`<my-cmp [(title)]="name">`|`[(title)]`
description:
Sets up two-way data binding. Equivalent to: `<my-cmp [title]="name" (titleChange)="name=$event">`
@cheatsheetItem
syntax:
`<video #movieplayer ...>
<button (click)="movieplayer.play()">
</video>`|`#movieplayer`|`(click)`
description:
Creates a local variable `movieplayer` that provides access to the `video` element instance in data-binding and event-binding expressions in the current template.
@cheatsheetItem
syntax:
`<p *myUnless="myExpression">...</p>`|`*myUnless`
description:
The `*` symbol turns the current element into an embedded template. Equivalent to:
<aid="parent-to-child-on-changes"></a>## Intercept input property changes with *ngOnChanges*
Detect and act upon changes to input property values with the `ngOnChanges` method of the `OnChanges` lifecycle hook interface.
May prefer this approach to the property setter when watching multiple, interacting input properties.
Learn about `ngOnChanges` in the [LifeCycle Hooks](../guide/lifecycle-hooks.html) chapter.This `VersionChildComponent` detects changes to the `major` and `minor` input properties and composes a log message reporting these changes:
The first provider is the *de-sugared*, expanded form of the most typical case in which the
class to be created (`HeroService`) is also the provider's injection token.
We wrote it in this long form to de-mystify the preferred short form.
The second provider substitutes the `DateLoggerService` for the `LoggerService`.
The `LoggerService` is already registered at the `AppComponent` level.
When _this component_ requests the `LoggerService`, it receives the `DateLoggerService` instead.
This component and its tree of child components receive the `DateLoggerService` instance.
Components outside the tree continue to receive the original `LoggerService` instance.The `DateLoggerService` inherits from `LoggerService`; it appends the current date/time to each message:
`AdDirective` injects `ViewContainerRef` to gain access to the view container of the element that will become the host of the dynamically added component.
`AdBanner` takes an array of `AdItem` objects as input. `AdItem` objects specify the type of component to load and any data to bind to the component.
The ad components making up the ad campaign are returned from `AdService`.
Passing an array of components to `AdBannerComponent` allows for a dynamic list of ads without static elements in the template.
`AdBannerComponent` cycles through the array of `AdItems` and loads the corresponding components on an interval. Every 3 seconds a new component is loaded.
`ComponentFactoryResolver` is used to resolve a `ComponentFactory` for each specific component. The component factory is need to create an instance of the component.
`ComponentFactories` are generated by the Angular compiler.
Generally the compiler will generate a component factory for any component referenced in a template.
With dynamically loaded components there are no selector references in the templates since components are loaded at runtime. In order to ensure that the compiler will still generate a factory, dynamically loaded components have to be added to their `NgModule`'s `entryComponents` array.
Components are added to the template by calling `createComponent` on the `ViewContainerRef` reference.
`createComponent` returns a reference to the loaded component. The component reference can be used to pass input data or call methods to interact with the component.
In the Ad banner, all components implement a common `AdComponent` interface to standardize the api for passing data to the components.
Two sample components and the `AdComponent` interface are shown below:
We can't always justify the cost and time to build handcrafted forms,
especially if we'll need a great number of them, they're similar to each other, and they change frequently
to meet rapidly changing business and regulatory requirements.
It may be more economical to create the forms dynamically, based on metadata that describe the business object model.
In this cookbook we show how to use `formGroup` to dynamically render a simple form with different control types and validation.
It's a primitive start.
It might evolve to support a much richer variety of questions, more graceful rendering, and superior user experience.
All such greatness has humble beginnings.
In our example we use a dynamic form to build an online application experience for heroes seeking employment.
The agency is constantly tinkering with the application process.
We can create the forms on the fly *without changing our application code*.
<aid="toc"></a>## Table of contents
[Bootstrap](#bootstrap)
[Question Model](#object-model)
[Form Component](#form-component)
[Questionnaire Metadata](#questionnaire-metadata)
[Dynamic Template](#dynamic-template)
**See the <live-example name="cb-dynamic-form"></live-example>**.
<aid="bootstrap"></a>## Bootstrap
We start by creating an `NgModule` called `AppModule`.
In our example we will be using Reactive Forms.
Reactive Forms belongs to a different `NgModule` called `ReactiveFormsModule`, so in order to access any Reactive Forms directives, we have to import `ReactiveFormsModule` from the `@angular/forms` library.
Notice this component can present any type of question in our model.
We only have two types of questions at this point but we can imagine many more.
The `ngSwitch` determines which type of question to display.
In both components we're relying on Angular's **formGroup** to connect the template HTML to the
underlying control objects, populated from the question model with display and validation rules.
`formControlName` and `formGroup` are directives defined in `ReactiveFormsModule`. Our templates can can access these directives directly since we imported `ReactiveFormsModule` from `AppModule`.
<aid="questionnaire-metadata"></a>## Questionnaire data`DynamicFormComponent` expects the list of questions in the form of an array bound to `@Input() questions`.
The set of questions we have defined for the job application is returned from the `QuestionService`.
In a real app we'd retrieve these questions from storage.
The key point is that we control the hero job application questions entirely through the objects returned from `QuestionService`.
Questionnaire maintenance is a simple matter of adding, updating, and removing objects from the `questions` array.
- we call a `buildForm` method in the `ngOnInit` [lifecycle hook method](../guide/lifecycle-hooks.html#hooks-overview)
because that's when we'll have the hero data. We'll call it again in the `addHero` method.
A real app would retrieve the hero asynchronously from a data service, a task best performed in the `ngOnInit` hook.- the `buildForm` method uses the `FormBuilder` (`fb`) to declare the form control model.
Then it attaches the same `onValueChanged` handler (there's a one line difference)
to the form's `valueChanged` event and calls it immediately
to set error messages for the new control model.
#### _FormBuilder_ declaration
The `FormBuilder` declaration object specifies the three controls of the sample's hero form.
Each control spec is a control name with an array value.
The first array element is the current value of the corresponding hero field.
The (optional) second value is a validator function or an array of validator functions.
Most of the validator functions are stock validators provided by Angular as static methods of the `Validators` class.
Angular has stock validators that correspond to the standard HTML validation attributes.
The `forbiddenNames` validator on the `"name"` control is a custom validator,
discussed in a separate [section below](#custom-validation).
Learn more about `FormBuilder` in a _forthcoming_ chapter on reactive forms.
#### Committing hero value changes
In two-way data binding, the user's changes flow automatically from the controls back to the data model properties.
Reactive forms do not use data binding to update data model properties.
The developer decides _when and how_ to update the data model from control values.
This sample updates the model twice:
1. when the user submits the form
1. when the user chooses to add a new hero
The `onSubmit` method simply replaces the `hero` object with the combined values of the form:
Consider adding a convenience shortcut to the `scripts` section of the `package.json`
to make the command easier to remember and run:
<code-exampleformat='.'language='sh'>
"scripts": {
"i18n": "ng-xi18n",
...
}
</code-example>
Now you can issue command variations such as these:
<code-examplelanguage="sh"class="code-shell">
npm run i18n
npm run i18n -- -p path/to/tsconfig.json
npm run i18n -- --i18nFormat=xmb -p path/to/tsconfig.json
</code-example>
Note the `--` flag before the options.
It tells _npm_ to pass every flag thereafter to `ng-xi18n`.
{@a translate}
## Translate text messages
The `ng-xi18n` command generates a translation source file
in the project root folder named `messages.xlf`.
The next step is to translate the English language template
text into the specific language translation
files. The cookbook sample creates a Spanish translation file.
{@a localization-folder}
### Create a localization folder
You will probably translate into more than one other language so it's a good idea
for the project structure to reflect your entire internationalization effort.
One approach is to dedicate a folder to localization and store related assets
(for example, internationalization files) there.
Localization and internationalization are
<ahref="https://en.wikipedia.org/wiki/Internationalization_and_localization"target="_blank">different but closely related terms</a>.This cookbook follows that suggestion. It has a `locale` folder under the `src/`.
Assets within the folder carry a filename extension that matches a language-culture code from a
Setting the document or window title using the Title service.
@description
{@a top}
Our app should be able to make the browser title bar say whatever we want it to say.
This cookbook explains how to do it.**See the <live-examplename="cb-set-document-title"></live-example>**.
<table>
<tr>
<td>
To see the browser title bar change in the live example,
open it again in the Plunker editor by clicking the icon in the upper right,
then pop out the preview window by clicking the blue 'X' button in the upper right corner.
</td>
<td>
<imgsrc='assets/images/devguide/plunker-switch-to-editor-button.png'width="200px"height="70px"alt="pop out the window"align="right"></img><br></br><imgsrc='assets/images/devguide/plunker-separate-window-button.png'width="200px"height="47px"alt="pop out the window"align="right"></img>
</td>
</tr>
</table>
## The problem with *<title>*
The obvious approach is to bind a property of the component to the HTML `<title>` like this:
<code-exampleformat=''>
<title>{{This_Does_Not_Work}}</title>
</code-example>
Sorry but that won't work.
The root component of our application is an element contained within the `<body>` tag.
The HTML `<title>` is in the document `<head>`, outside the body, making it inaccessible to Angular data binding.
We could grab the browser `document` object and set the title manually.
That's dirty and undermines our chances of running the app outside of a browser someday.
Running your app outside a browser means that you can take advantage of server-side
pre-rendering for near-instant first app render times and for SEO. It means you could run from
inside a Web Worker to improve your app's responsiveness by using multiple threads. And it
means that you could run your app inside Electron.js or Windows Universal to deliver it to the desktop.
## Use the *Title* service
Fortunately, Angular bridges the gap by providing a `Title` service as part of the *Browser platform*.
The [Title](../api/platform-browser/index/Title-class.html) service is a simple class that provides an API
for getting and setting the current HTML document title:
*`getTitle() : string`— Gets the title of the current HTML document.
*`setTitle( newTitle : string )`— Sets the title of the current HTML document.
Let's inject the `Title` service into the root `AppComponent` and expose a bindable `setTitle` method that calls it:
## Why we provide the *Title* service in *bootstrap*
We generally recommended providing application-wide services in the root application component, `AppComponent`.
Here we recommend registering the title service during bootstrapping,
a location we reserve for configuring the runtime Angular environment.
That's exactly what we're doing.
The `Title` service is part of the Angular *browser platform*.
If we bootstrap our application into a different platform,
we'll have to provide a different `Title` service that understands the concept of a "document title" for that specific platform.
Ideally the application itself neither knows nor cares about the runtime environment.[Back to top](#top)
Some files were not shown because too many files have changed in this diff
Show More
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
