Skip to content

Commit

Permalink
Deconstruct library tour (#5367)
Browse files Browse the repository at this point in the history
This PR breaks up the library tour to facilitate more content living
under "Core libraries" in the future and users being able to access what
is important to them more easily.

The change is implemented in a similar fashion to the language tour
split up. The following work was completed:

- Introduced a new top-level `/libraries` folder
- Combined the index at `/guides/libraries` and the intro to the library
tour at `/libraries/index`.
- Split each section of the library tour in to their own page
- Add each new page to the sidenav under "Core libraries"
- Add a redirector on the old page to redirect accesses to specific
headings to the correct new page and heading
- Add previous and next buttons to the various pages
- Update links across the entire website
- Add and update redirects where necessary

Fixes #4610

---------

Co-authored-by: Parker Lougheed <[email protected]>
  • Loading branch information
MaryaBelanger and parlough authored Dec 18, 2023
1 parent cbfa713 commit 14ef584
Show file tree
Hide file tree
Showing 41 changed files with 2,271 additions and 1,781 deletions.
15 changes: 8 additions & 7 deletions firebase.json
Original file line number Diff line number Diff line change
Expand Up @@ -56,9 +56,9 @@
{ "source": "/articles/language/await-async", "destination": "/codelabs/async-await", "type": 301 },
{ "source": "/articles/language/mixins", "destination": "/language/mixins", "type": 301 },
{ "source": "/articles/language/optional-types", "destination": "/resources/faq#types", "type": 301 },
{ "source": "/articles/libraries", "destination": "/guides/libraries/library-tour", "type": 301 },
{ "source": "/articles/libraries", "destination": "/libraries", "type": 301 },
{ "source": "/articles/libraries/converters-and-codecs", "destination": "/articles/archive/converters-and-codecs", "type": 301 },
{ "source": "/articles/libraries/dart-io", "destination": "/guides/libraries/library-tour#dartio", "type": 301 },
{ "source": "/articles/libraries/dart-io", "destination": "/libraries/dart-io", "type": 301 },
{ "source": "/articles/libraries/zones", "destination": "/articles/archive/zones", "type": 301 },
{ "source": "/articles/m*{,/**}", "destination": "/guides/language/evolution", "type": 301 },
{ "source": "/articles/mixins", "destination": "/language/mixins", "type": 301 },
Expand Down Expand Up @@ -103,7 +103,7 @@
{ "source": "/docs/api{,/**}", "destination": "https://api.dart.dev", "type": 301 },
{ "source": "/docs/cookbook", "destination": "/language", "type": 301 },
{ "source": "/docs/dart-up-and-running/**/ch02?(.html)", "destination": "/language", "type": 301 },
{ "source": "/docs/dart-up-and-running/**/ch03?(.html)", "destination": "/guides/libraries/library-tour", "type": 301 },
{ "source": "/docs/dart-up-and-running/**/ch03?(.html)", "destination": "/libraries", "type": 301 },
{ "source": "/docs/dart-up-and-running/contents/ch04-tools-dart2js?(.html)", "destination": "/tools/dart-compile#js", "type": 301 },
{ "source": "/docs/dart-up-and-running/contents/ch04-tools-dart_analyzer?(.html)", "destination": "/tools/dart-analyze", "type": 301 },
{ "source": "/docs/dart-up-and-running/contents/ch04-tools-dartium?(.html)", "destination": "/tools#ides-and-editors", "type": 301 },
Expand All @@ -112,7 +112,7 @@
{ "source": "/docs/editor/getting-started?(.html)", "destination": "/overview", "type": 301 },
{ "source": "/docs/getting-started{,/**}", "destination": "/overview", "type": 301 },
{ "source": "/docs/language-tour", "destination": "/language", "type": 301 },
{ "source": "/docs/library-tour", "destination": "/guides/libraries/library-tour", "type": 301 },
{ "source": "/docs/library-tour", "destination": "/libraries", "type": 301 },
{ "source": "/docs/pub-package-manager", "destination": "/tools/pub", "type": 301 },
{ "source": "/docs/pub-package-manager/pubspec{,/**}", "destination": "/tools/pub/pubspec", "type": 301 },
{ "source": "/docs/serverguide?(.html)", "destination": "/server", "type": 301 },
Expand Down Expand Up @@ -193,10 +193,11 @@
{ "source": "/guides/language/effective-dart/:page*", "destination": "/effective-dart/:page*", "type": 301 },
{ "source": "/guides/language/extension-methods", "destination": "/language/extension-methods", "type": 301 },
{ "source": "/guides/language/formatting", "destination": "/tools/dart-format", "type": 301 },
{ "source": "/guides/language/library-tour", "destination": "/guides/libraries/library-tour", "type": 301 },
{ "source": "/guides/language/library-tour", "destination": "/libraries", "type": 301 },
{ "source": "/guides/language/sound-dart", "destination": "/language/type-system", "type": 301 },
{ "source": "/guides/language/sound-faq", "destination": "/language/type-system", "type": 301 },
{ "source": "/guides/language/type-system", "destination": "/language/type-system", "type": 301 },
{ "source": "/guides/libraries", "destination": "/libraries", "type": 301 },
{ "source": "/guides/libraries/create-library-packages", "destination": "/guides/libraries/create-packages", "type": 301 },
{ "source": "/guides/libraries/java-interop", "destination": "/interop/java-interop", "type": 301 },
{ "source": "/guides/libraries/objective-c-interop", "destination": "/interop/objective-c-interop", "type": 301 },
Expand Down Expand Up @@ -240,7 +241,7 @@
{ "source": "/server/app-engine{,/**}", "destination": "/server/google-cloud", "type": 301 },
{ "source": "/server/c-interop", "destination": "/interop/c-interop", "type": 301 },
{ "source": "/server/google-cloud-platform{,/**}", "destination": "/server/google-cloud", "type": 301 },
{ "source": "/server/io-library-tour", "destination": "/guides/libraries/library-tour#dartio", "type": 301 },
{ "source": "/server/io-library-tour", "destination": "/libraries/dart-io", "type": 301 },
{ "source": "/server/tls-ssl?(.html)", "destination": "https://api.dart.dev/stable/dart-io/SecurityContext-class.html", "type": 301 },
{ "source": "/server/tools", "destination": "/tools", "type": 301 },
{ "source": "/server/tools/dart-vm", "destination": "/tools/dart-run", "type": 301 },
Expand Down Expand Up @@ -287,7 +288,7 @@
{ "source": "/tutorials/dart-vm", "destination": "/tutorials/server", "type": 301 },
{ "source": "/tutorials/dart-vm/:page*", "destination": "/tutorials/server/:page*", "type": 301 },
{ "source": "/tutorials/language/futures", "destination": "/codelabs/async-await", "type": 301 },
{ "source": "/tutorials/libraries", "destination": "/guides/libraries", "type": 301 },
{ "source": "/tutorials/libraries", "destination": "/libraries", "type": 301 },
{ "source": "/tutorials/libraries/shared-pkgs", "destination": "/guides/packages", "type": 301 },
{ "source": "/tutorials/web/fetch-data", "destination": "/tutorials/server/fetch-data", "type": 301 },
{ "source": "/web-ui/observables{,/**}", "destination": "https://pub.dev/packages/observable", "type": 301 },
Expand Down
4 changes: 2 additions & 2 deletions src/_data/docs_cards.yml
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,9 @@
- name: Effective Dart
description: Best practices for building consistent, maintainable, efficient Dart code.
url: /effective-dart
- name: Library tour
- name: Library documentation
description: An example-based introduction to the major features in the Dart SDK's core libraries.
url: /guides/libraries/library-tour
url: /libraries
- name: Dart SDK
description: What's in the SDK, and how to install it.
url: /tools/sdk
Expand Down
29 changes: 20 additions & 9 deletions src/_data/side-nav.yml
Original file line number Diff line number Diff line change
Expand Up @@ -137,13 +137,26 @@
children:
- title: Overview
match-page-url-exactly: true
permalink: /guides/libraries
- title: Tour
permalink: /guides/libraries/library-tour
- title: Articles
children:
- title: Creating streams
permalink: /articles/libraries/creating-streams
permalink: /libraries
- title: dart:core
permalink: /libraries/dart-core
- title: dart:async
permalink: /libraries/dart-async
- title: dart:math
permalink: /libraries/dart-math
- title: dart:convert
permalink: /libraries/dart-convert
- title: dart:io
permalink: /libraries/dart-io
- title: dart:html
permalink: /libraries/dart-html
- divider
- title: Using streams
permalink: /tutorials/language/streams
- title: Creating streams
permalink: /articles/libraries/creating-streams
- title: Futures and error handling
permalink: /guides/libraries/futures-error-handling

- title: Packages
expanded: false
Expand Down Expand Up @@ -183,8 +196,6 @@
children:
- title: Futures, async, await
permalink: /codelabs/async-await
- title: Streams
permalink: /tutorials/language/streams
- title: JSON
permalink: /guides/json
- title: Number representation
Expand Down
6 changes: 3 additions & 3 deletions src/_includes/known-issues/compile-ki.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,11 +8,11 @@ No cross-compilation support ([issue 28617][])

No support for `dart:mirrors` and `dart:developer`
: For a complete list of the core libraries you can use,
see the **All** and **AOT** entries in the
[table of core Dart libraries](/guides/libraries).
see the [Multi-platform][] and [Native platform][] library tables.

[Multi-platform]: /libraries#multi-platform-libraries
[Native platform]: /libraries#native-platform-libraries
[issue 28617]: https://github.com/dart-lang/sdk/issues/28617
[issue 39106]: https://github.com/dart-lang/sdk/issues/39106

{{site.alert.tip}}
If one of these issues is important to you,
Expand Down
135 changes: 135 additions & 0 deletions src/assets/js/library-tour-redirector.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,135 @@
const oldToNew = {
'dartcore---numbers-collections-strings-and-more': '/libraries/dart-core',
'dartcore': '/libraries/dart-core',
'printing-to-the-console': '/libraries/dart-core#printing-to-the-console',
'strings-and-regular-expressions': '/libraries/dart-core#strings-and-regular-expressions',
'searching-inside-a-string': '/libraries/dart-core#searching-inside-a-string',
'extracting-data-from-a-string': '/libraries/dart-core#extracting-data-from-a-string',
'converting-to-uppercase-or-lowercase': '/libraries/dart-core#converting-to-uppercase-or-lowercase',
'trimming-and-empty-strings': '/libraries/dart-core#trimming-and-empty-strings',
'replacing-part-of-a-string': '/libraries/dart-core#replacing-part-of-a-string',
'building-a-string': '/libraries/dart-core#building-a-string',
'regular-expressions': '/libraries/dart-core#regular-expressions',
'collections': '/libraries/dart-core#collections',
'lists': '/libraries/dart-core#lists',
'sets': '/libraries/dart-core#sets',
'maps': '/libraries/dart-core#maps',
'common-collection-methods': '/libraries/dart-core#common-collection-methods',
'uris': '/libraries/dart-core#uris',
'encoding-and-decoding-fully-qualified-uris': '/libraries/dart-core#encoding-and-decoding-fully-qualified-uris',
'encoding-and-decoding-uri-components': '/libraries/dart-core#encoding-and-decoding-uri-components',
'parsing-uris': '/libraries/dart-core#parsing-uris',
'building-uris': '/libraries/dart-core#building-uris',
'dates-and-times': '/libraries/dart-core#dates-and-times',
'utility-classes': '/libraries/dart-core#utility-classes',
'comparing-objects': '/libraries/dart-core#comparing-objects',
'implementing-map-keys': '/libraries/dart-core#implementing-map-keys',
'iteration': '/libraries/dart-core#iteration',
'exceptions': '/libraries/dart-core#exceptions',
'weak-references-and-finalizers': '/libraries/dart-core#weak-references-and-finalizers',

'dartasync---asynchronous-programming': '/libraries/dart-async',
'dartasync': '/libraries/dart-async',
'futures': '/libraries/dart-async#futures',
'using-await': '/libraries/dart-async#using-await',
'basic-usage': '/libraries/dart-async#basic-usage',
'chaining-multiple-asynchronous-methods': '/libraries/dart-async#chaining-multiple-asynchronous-methods',
'waiting-for-multiple-futures': '/libraries/dart-async#waiting-for-multiple-futures',
'handling-errors-for-multiple-futures': '/libraries/dart-async#handling-errors-for-multiple-futures',
'streams': '/libraries/dart-async#streams',
'using-an-asynchronous-for-loop': '/libraries/dart-async#using-an-asynchronous-for-loop',
'listening-for-stream-data': '/libraries/dart-async#listening-for-stream-data',
'transforming-stream-data': '/libraries/dart-async#transforming-stream-data',
'handling-errors-and-completion': '/libraries/dart-async#handling-errors-and-completion',

'dartmath---math-and-random': '/libraries/dart-math',
'dartmath': '/libraries/dart-math',
'trigonometry': '/libraries/dart-math#trigonometry',
'maximum-and-minimum': '/libraries/dart-math#maximum-and-minimum',
'math-constants': '/libraries/dart-math#math-constants',
'random-numbers': '/libraries/dart-math#random-numbers',

'dartconvert---decoding-and-encoding-json-utf-8-and-more': '/libraries/dart-convert',
'dartconvert': '/libraries/dart-convert',
'decoding-and-encoding-json': '/libraries/dart-convert#decoding-and-encoding-json',
'decoding-and-encoding-utf-8-characters': '/libraries/dart-convert#decoding-and-encoding-utf-8-characters',
'other-functionality': '/libraries/dart-convert#other-functionality',

'darthtml-browser-based-apps': '/libraries/dart-html',
'darthtml': '/libraries/dart-html',
'manipulating-the-dom': '/libraries/dart-html#manipulating-the-dom',
'finding-elements': '/libraries/dart-html#finding-elements',
'manipulating-elements': '/libraries/dart-html#manipulating-elements',
'creating-elements': '/libraries/dart-html#creating-elements',
'adding-replacing-and-removing-nodes': '/libraries/dart-html#adding-replacing-and-removing-nodes',
'manipulating-css-styles': '/libraries/dart-html#manipulating-css-styles',
'handling-events': '/libraries/dart-html#handling-events',
'using-http-resources-with-httprequest': '/libraries/dart-html#using-http-resources-with-httprequest',
'sending-and-receiving-real-time-data-with-websockets': '/libraries/dart-html#sending-and-receiving-real-time-data-with-websockets',
'sending-data': '/libraries/dart-html#sending-data',
'receiving-data': '/libraries/dart-html#receiving-data',
'handling-websocket-events': '/libraries/dart-html#handling-websocket-events',

'dartio-io-for-servers-and-command-line-apps': '/libraries/dart-io',
'dartio': '/libraries/dart-io',
'files-and-directories': '/libraries/dart-io#files-and-directories',
'reading-a-file-as-text': '/libraries/dart-io#reading-a-file-as-text',
'reading-a-file-as-binary': '/libraries/dart-io#reading-a-file-as-binary',
'handling-errors': '/libraries/dart-io#handling-errors',
'streaming-file-contents': '/libraries/dart-io#streaming-file-contents',
'writing-file-contents': '/libraries/dart-io#writing-file-contents',
'listing-files-in-a-directory': '/libraries/dart-io#listing-files-in-a-directory',
'other-common-functionality': '/libraries/dart-io#other-common-functionality',
'http-clients-and-servers': '/libraries/dart-io#http-clients-and-servers',
'http-server': '/libraries/dart-io#http-server',
'http-client': '/libraries/dart-io#http-client',
};

function toDefault() {
window.location.replace('/libraries');
}

function handleRedirect() {
const rawOldFragment = window.location.hash;

// If no fragment was specified, go to 'Dart introduction' page.
if (!rawOldFragment) {
toDefault();
return;
}

const oldFragmentWithHash = rawOldFragment.trim().toLowerCase();

// If the fragment is empty, go to 'Dart library overview' page.
if (oldFragmentWithHash.length === 0) {
toDefault();
return;
}

const oldFragment = oldFragmentWithHash.substring(1);

// If the fragment did not exist, go to 'Dart library overview' page.
if (!(oldFragment in oldToNew)) {
toDefault();
return;
}

const newDestination = oldToNew[oldFragment];

// If the desired destination exists, go there.
// Otherwise, go to 'Dart library overview' page.
fetch(newDestination)
.then((response) => {
if (response.status === 200) {
window.location.replace(newDestination);
} else {
toDefault();
}
}).catch((_) => toDefault());
}

const currentLocation = window.location.href;

if (currentLocation.includes('library-tour')) {
handleRedirect();
}
2 changes: 1 addition & 1 deletion src/get-dart/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -114,7 +114,7 @@ by [downloading the SDK as a zip file][].

[SDK constraints]: /tools/pub/pubspec#sdk-constraints
[build the SDK from source]: https://github.com/dart-lang/sdk/wiki/Building
[Dart libraries]: /guides/libraries/library-tour
[Dart libraries]: /libraries
[Dart Docker image]: https://hub.docker.com/_/dart
[downloading the SDK as a zip file]: /get-dart/archive
[Debian stable]: https://www.debian.org/releases
Expand Down
8 changes: 4 additions & 4 deletions src/guides/json.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ converting Dart objects to and from JSON.

The following libraries and packages are useful across Dart platforms:

* [dart:convert](/guides/libraries/library-tour#dartconvert---decoding-and-encoding-json-utf-8-and-more)<br>
* [dart:convert](/libraries/dart-convert)<br>
Converters for both JSON and UTF-8
(the character encoding that JSON requires).

Expand All @@ -36,9 +36,9 @@ The following libraries and packages are useful across Dart platforms:

## Web app resources

[Using HTTP resources with HttpRequest](/guides/libraries/library-tour#using-http-resources-with-httprequest)
: Demonstrates how to use HttpRequest to exchange data with a web server.
Part of the [dart:html library tour.](/guides/libraries/library-tour#darthtml)
[Fetch data from the internet](/tutorials/server/fetch-data)
: Demonstrates how to use `package:http` to retrieve data with a web server.



{% comment %}
Expand Down
8 changes: 4 additions & 4 deletions src/guides/language/coming-from/js-to-dart.md
Original file line number Diff line number Diff line change
Expand Up @@ -2771,12 +2771,12 @@ language and practical ways of getting started.
Some possible next steps:

* [Language tour][] to learn more about the Dart language
* [Library tour][] to learn about Dart's core libraries
* [Core library documentation][] to learn about Dart's core libraries
* [Dart codelabs][] for hands-on experience learning a variety of topics
* [Effective Dart][] to learn about common conventions
and guidelines when writing Dart code

[Language tour]: /language
[Library tour]: /guides/libraries/library-tour
[Dart codelabs]: /codelabs
[Language tour]: /language
[Core library documentation]: /libraries
[Dart codelabs]: /codelabs
[Effective Dart]: /effective-dart
4 changes: 3 additions & 1 deletion src/guides/libraries/futures-error-handling.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,8 @@
---
title: Futures and error handling
description: Everything you wanted to know about handling errors and exceptions when writing asynchronous code. And then some.
description: >-
Everything you wanted to know about handling errors and exceptions
when writing asynchronous code. And then some.
---

The Dart language has native
Expand Down
Loading

0 comments on commit 14ef584

Please sign in to comment.