diff --git a/.github/workflows/pr-check-lint_content.yml b/.github/workflows/pr-check-lint_content.yml index d9ee293eb809f54..0efe5924c0be468 100644 --- a/.github/workflows/pr-check-lint_content.yml +++ b/.github/workflows/pr-check-lint_content.yml @@ -39,14 +39,14 @@ jobs: echo "DIFF_DOCUMENTS=${DIFF_DOCUMENTS}" >> $GITHUB_ENV - name: Checkout HEAD - if: ${{ env.DIFF_DOCUMENTS }} + if: env.DIFF_DOCUMENTS uses: actions/checkout@v4 with: ref: ${{ github.event.pull_request.head.sha }} path: pr_head - name: Get changed content from HEAD - if: ${{ env.DIFF_DOCUMENTS }} + if: env.DIFF_DOCUMENTS run: | git config --global user.email "108879845+mdn-bot@users.noreply.github.com" git config --global user.name "mdn-bot" @@ -62,21 +62,21 @@ jobs: git commit -m "Code from PR head" - name: Setup Node.js environment - if: ${{ env.DIFF_DOCUMENTS }} + if: env.DIFF_DOCUMENTS uses: actions/setup-node@v4 with: node-version-file: ".nvmrc" cache: yarn - name: Install all yarn packages - if: ${{ env.DIFF_DOCUMENTS }} + if: env.DIFF_DOCUMENTS run: yarn --frozen-lockfile env: # https://github.com/microsoft/vscode-ripgrep#github-api-limit-note GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - name: Lint and format markdown files - if: ${{ env.DIFF_DOCUMENTS }} + if: env.DIFF_DOCUMENTS run: | # Generate random delimiter # https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#multiline-strings @@ -120,13 +120,13 @@ jobs: git diff - name: Setup reviewdog - if: ${{ env.FILES_MODIFIED == 'true' || env.MD_LINT_FAILED == 'true' }} + if: env.FILES_MODIFIED == 'true' || env.MD_LINT_FAILED == 'true' uses: reviewdog/action-setup@v1 with: reviewdog_version: latest - name: Suggest changes using diff - if: ${{ env.FILES_MODIFIED == 'true' }} + if: env.FILES_MODIFIED == 'true' env: REVIEWDOG_GITHUB_API_TOKEN: ${{ secrets.GITHUB_TOKEN }} run: | @@ -141,7 +141,7 @@ jobs: -reporter=github-pr-review < "${TMPFILE}" - name: Add reviews for markdownlint errors - if: ${{ env.MD_LINT_FAILED == 'true' }} + if: env.MD_LINT_FAILED == 'true' env: REVIEWDOG_GITHUB_API_TOKEN: ${{ secrets.GITHUB_TOKEN }} run: | @@ -154,7 +154,7 @@ jobs: -reporter="github-pr-review" - name: Fail if any issues pending - if: ${{ env.FILES_MODIFIED == 'true' || env.MD_LINT_FAILED == 'true' || env.FM_LINT_FAILED == 'true' }} + if: env.FILES_MODIFIED == 'true' || env.MD_LINT_FAILED == 'true' || env.FM_LINT_FAILED == 'true' env: MD_LINT_FAILED: ${{ env.MD_LINT_FAILED }} FM_LINT_FAILED: ${{ env.FM_LINT_FAILED }} diff --git a/.github/workflows/pr-review-companion.yml b/.github/workflows/pr-review-companion.yml index 00a204522776507..13b3122ee88106d 100644 --- a/.github/workflows/pr-review-companion.yml +++ b/.github/workflows/pr-review-companion.yml @@ -7,14 +7,14 @@ name: PR review companion on: workflow_run: - workflows: ["PR Test", "PR Test - new CI"] + workflows: ["PR Test", "PR Test Legacy"] types: - completed jobs: review: runs-on: ubuntu-latest - if: ${{ github.event.workflow_run.conclusion == 'success' }} + if: github.event.workflow_run.conclusion == 'success' steps: - name: "Download artifact" uses: actions/download-artifact@v4 @@ -26,18 +26,18 @@ jobs: run-id: ${{ github.event.workflow_run.id }} - name: Check for artifacts - if: ${{ hashFiles('build/') != '' }} + if: hashFiles('build/') != '' run: | echo "HAS_ARTIFACT=true" >> "$GITHUB_ENV" - uses: actions/checkout@v4 - if: ${{ env.HAS_ARTIFACT }} + if: env.HAS_ARTIFACT with: repository: mdn/yari path: yari - name: Install Python - if: ${{ env.HAS_ARTIFACT }} + if: env.HAS_ARTIFACT id: setup-python uses: actions/setup-python@v5 with: @@ -45,7 +45,7 @@ jobs: # See https://www.peterbe.com/plog/install-python-poetry-github-actions-faster - name: Load cached ~/.local - if: ${{ env.HAS_ARTIFACT }} + if: env.HAS_ARTIFACT uses: actions/cache@v4 with: path: ~/.local @@ -54,14 +54,14 @@ jobs: key: dotlocal-${{ runner.os }}-${{ steps.setup-python.outputs.python-version }}-0 - name: Install Python poetry - if: ${{ env.HAS_ARTIFACT }} + if: env.HAS_ARTIFACT uses: snok/install-poetry@v1.4 with: virtualenvs-create: true virtualenvs-in-project: true - name: Load cached venv - if: ${{ env.HAS_ARTIFACT }} + if: env.HAS_ARTIFACT id: cached-poetry-dependencies uses: actions/cache@v4 with: @@ -71,19 +71,19 @@ jobs: key: venv-${{ runner.os }}-${{ hashFiles('**/poetry.lock') }}-${{ steps.setup-python.outputs.python-version }}-0 - name: Install poetry dependencies - if: ${{ env.HAS_ARTIFACT && steps.cached-poetry-dependencies.outputs.cache-hit != 'true' }} + if: env.HAS_ARTIFACT && steps.cached-poetry-dependencies.outputs.cache-hit != 'true' run: | cd yari/deployer poetry install --no-interaction --no-root - name: Install Deployer - if: ${{ env.HAS_ARTIFACT }} + if: env.HAS_ARTIFACT run: | cd yari/deployer poetry install --no-interaction - name: Deploy and analyze built content - if: ${{ env.HAS_ARTIFACT }} + if: env.HAS_ARTIFACT env: BUILD_OUT_ROOT: ${{ github.workspace }}/build diff --git a/.github/workflows/pr-test-new-ci.yml b/.github/workflows/pr-test-legacy.yml similarity index 86% rename from .github/workflows/pr-test-new-ci.yml rename to .github/workflows/pr-test-legacy.yml index 40456d39df87508..e390e19231b95bc 100644 --- a/.github/workflows/pr-test-new-ci.yml +++ b/.github/workflows/pr-test-legacy.yml @@ -4,7 +4,7 @@ # This way, if the tests passed, you'll be able to review the built # pages on a public URL. -name: PR Test - new CI +name: PR Test Legacy on: pull_request: @@ -13,7 +13,7 @@ on: jobs: tests: - if: github.repository == 'mdn/content' && startsWith(github.event.pull_request.title, '[new-ci]') + if: github.repository == 'mdn/content' runs-on: ubuntu-latest # Set the permissions to `read-all`, preventing the workflow from # any accidental write access to the repository. @@ -48,14 +48,14 @@ jobs: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - name: Setup Node.js environment - if: ${{ env.GIT_DIFF_CONTENT }} || ${{ env.GIT_DIFF_FILES }} + if: env.GIT_DIFF_CONTENT || env.GIT_DIFF_FILES uses: actions/setup-node@v4 with: node-version-file: ".nvmrc" cache: yarn - name: Install all yarn packages - if: ${{ env.GIT_DIFF_CONTENT }} || ${{ env.GIT_DIFF_FILES }} + if: env.GIT_DIFF_CONTENT || env.GIT_DIFF_FILES run: yarn --frozen-lockfile env: # https://github.com/microsoft/vscode-ripgrep#github-api-limit-note @@ -63,7 +63,7 @@ jobs: - name: Build changed content id: build-content - if: ${{ env.GIT_DIFF_CONTENT }} + if: env.GIT_DIFF_CONTENT env: CONTENT_ROOT: ${{ github.workspace }}/files @@ -92,19 +92,12 @@ jobs: # Playground REACT_APP_PLAYGROUND_BASE_HOST: mdnyalp.dev - # rari - LIVE_SAMPLES_BASE_URL: https://live.mdnyalp.dev - INTERACTIVE_EXAMPLES_BASE_URL: https://interactive-examples.mdn.allizom.net - run: | # The reason this script isn't in `package.json` is because # you don't need that script as a writer. It's only used in CI # and it can't use the default CONTENT_ROOT that gets set in # package.json. - echo Y|yarn rari update - ARGS=$(echo $GIT_DIFF_CONTENT | sed -E -e "s#(^| )files#\1-f $PWD/files#g") - yarn rari build --no-basic --json-issues --data-issues $ARGS - yarn yari-render-html + yarn build $GIT_DIFF_CONTENT echo "Disk usage size of the build" du -sh $BUILD_OUT_ROOT @@ -119,7 +112,7 @@ jobs: wget https://github.com/${{ github.repository }}/compare/${BASE_SHA}...${HEAD_SHA}.diff -O ${BUILD_OUT_ROOT}/DIFF - name: Merge static assets with built documents - if: ${{ env.GIT_DIFF_CONTENT }} + if: env.GIT_DIFF_CONTENT run: | # Exclude the .map files, as they're used for debugging JS and CSS. rsync -a --exclude "*.map" node_modules/@mdn/yari/client/build/ $BUILD_OUT_ROOT @@ -127,13 +120,13 @@ jobs: du -sh $BUILD_OUT_ROOT - uses: actions/upload-artifact@v4 - if: ${{ env.GIT_DIFF_CONTENT }} + if: env.GIT_DIFF_CONTENT with: name: build path: ${{ env.BUILD_OUT_ROOT }} - name: Check changed files - if: ${{ env.GIT_DIFF_FILES }} + if: env.GIT_DIFF_FILES run: | echo $GIT_DIFF_FILES diff --git a/.github/workflows/pr-test.yml b/.github/workflows/pr-test.yml index f3e8d2e5817b9c5..68f3dc5cd3dba5a 100644 --- a/.github/workflows/pr-test.yml +++ b/.github/workflows/pr-test.yml @@ -13,7 +13,7 @@ on: jobs: tests: - if: github.repository == 'mdn/content' && !startsWith(github.event.pull_request.title, '[new-ci]') + if: github.repository == 'mdn/content' runs-on: ubuntu-latest # Set the permissions to `read-all`, preventing the workflow from # any accidental write access to the repository. @@ -48,14 +48,14 @@ jobs: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - name: Setup Node.js environment - if: ${{ env.GIT_DIFF_CONTENT }} || ${{ env.GIT_DIFF_FILES }} + if: env.GIT_DIFF_CONTENT || env.GIT_DIFF_FILES uses: actions/setup-node@v4 with: node-version-file: ".nvmrc" cache: yarn - name: Install all yarn packages - if: ${{ env.GIT_DIFF_CONTENT }} || ${{ env.GIT_DIFF_FILES }} + if: env.GIT_DIFF_CONTENT || env.GIT_DIFF_FILES run: yarn --frozen-lockfile env: # https://github.com/microsoft/vscode-ripgrep#github-api-limit-note @@ -63,7 +63,7 @@ jobs: - name: Build changed content id: build-content - if: ${{ env.GIT_DIFF_CONTENT }} + if: env.GIT_DIFF_CONTENT env: CONTENT_ROOT: ${{ github.workspace }}/files @@ -92,12 +92,19 @@ jobs: # Playground REACT_APP_PLAYGROUND_BASE_HOST: mdnyalp.dev + # rari + LIVE_SAMPLES_BASE_URL: https://live.mdnyalp.dev + INTERACTIVE_EXAMPLES_BASE_URL: https://interactive-examples.mdn.allizom.net + run: | # The reason this script isn't in `package.json` is because # you don't need that script as a writer. It's only used in CI # and it can't use the default CONTENT_ROOT that gets set in # package.json. - yarn build $GIT_DIFF_CONTENT + echo Y|yarn rari update + ARGS=$(echo $GIT_DIFF_CONTENT | sed -E -e "s#(^| )files#\1-f $PWD/files#g") + yarn rari build --no-basic --json-issues --data-issues $ARGS + yarn yari-render-html echo "Disk usage size of the build" du -sh $BUILD_OUT_ROOT @@ -112,7 +119,7 @@ jobs: wget https://github.com/${{ github.repository }}/compare/${BASE_SHA}...${HEAD_SHA}.diff -O ${BUILD_OUT_ROOT}/DIFF - name: Merge static assets with built documents - if: ${{ env.GIT_DIFF_CONTENT }} + if: env.GIT_DIFF_CONTENT run: | # Exclude the .map files, as they're used for debugging JS and CSS. rsync -a --exclude "*.map" node_modules/@mdn/yari/client/build/ $BUILD_OUT_ROOT @@ -120,13 +127,13 @@ jobs: du -sh $BUILD_OUT_ROOT - uses: actions/upload-artifact@v4 - if: ${{ env.GIT_DIFF_CONTENT }} + if: env.GIT_DIFF_CONTENT with: name: build path: ${{ env.BUILD_OUT_ROOT }} - name: Check changed files - if: ${{ env.GIT_DIFF_FILES }} + if: env.GIT_DIFF_FILES run: | echo $GIT_DIFF_FILES diff --git a/files/en-us/glossary/time_to_first_byte/index.md b/files/en-us/glossary/time_to_first_byte/index.md index af1e0a5afb123b5..76f6eccbcc6fede 100644 --- a/files/en-us/glossary/time_to_first_byte/index.md +++ b/files/en-us/glossary/time_to_first_byte/index.md @@ -8,14 +8,17 @@ page-type: glossary-definition **Time to First Byte** (TTFB) refers to the time between the browser requesting a page and when it receives the first byte of information from the server. This time includes {{Glossary("DNS")}} lookup and establishing the connection using a {{Glossary("TCP")}} handshake and {{Glossary("TLS")}} handshake if the request is made over {{Glossary("HTTPS")}}. -TTFB is the time it takes between the start of the request and the start of the response, in milliseconds: +TTFB is the time it takes between the start of the request and the start of the response, in milliseconds. This can be measured using the `{{domxref("PerformanceResourceTiming.requestStart", "requestStart")}}` attribute of {{domxref("PerformanceNavigationTiming")}}: -```plain -TTFB = responseStart - navigationStart +```javascript +const ttfb = performance.getEntriesByType("navigation")[0].responseStart; ``` +> [!NOTE] +> For sites using {{HTTPStatus("103", "103 Early Hints")}}, TTFB is typically the _first bytes_ (after any redirects) — and so, the 103 interim response. Site owners wishing to measure the time until the final response should use `{{domxref("PerformanceResourceTiming.finalResponseHeadersStart", "finalResponseHeadersStart")}}`, where supported. + ## See also - [A typical HTTP session](/en-US/docs/Web/HTTP/Session) - [PerformanceResourceTiming](/en-US/docs/Web/API/PerformanceResourceTiming) -- [PerformanceTiming](/en-US/docs/Web/API/PerformanceTiming) +- [PerformanceNavigationTiming](/en-US/docs/Web/API/PerformanceNavigationTiming) diff --git a/files/en-us/learn_web_development/core/accessibility/html/index.md b/files/en-us/learn_web_development/core/accessibility/html/index.md index 347f10138095f12..080ea658d3043c6 100644 --- a/files/en-us/learn_web_development/core/accessibility/html/index.md +++ b/files/en-us/learn_web_development/core/accessibility/html/index.md @@ -497,9 +497,9 @@ This highlights the importance of not only using meaningful file names in case s Note that the contents of the `alt` attribute should always provide a direct representation of the image and what it conveys visually. The alt should be brief and concise and include all the information conveyed in the image that is not duplicated in the surrounding text. -The content of the `alt` attribute for a single image differs based on the context. For example, if the photo of Fluffy is an avatar next to a review for Yuckymeat dog food, `alt="Fluffy"` is appropriate. If the photo is part of Fluffy's adoption page for the animal rescue society, information conveyed in the image that is relevant for a prospective dog parent that is not duplicated in the surrounding text should be included. A longer description, such as `alt="Fluffy, a tri-color terrier with very short hair, with a tennis ball in her mouth."` is appropriate. As the surrounding text likely has Fluffy's size and breed, that is not included in the `alt`. However, as the dog's biography likely doesn't include hair length, colors, or toy preferences, which the potential parent needs to know, it is included. Is the image outdoors, or does Fluffy have a red collar with a blue leash? Not important in terms of adopting the pet and therefore not included. All information image conveys that a sited user can access and is relevant to the context is what needs to be conveyed; nothing more. Keep it short, precise, and useful. +The content of the `alt` attribute for a single image differs based on the context. For example, if the photo of Fluffy is an avatar next to a review for Yuckymeat dog food, `alt="Fluffy"` is appropriate. If the photo is part of Fluffy's adoption page for the animal rescue society, information conveyed in the image that is relevant for a prospective dog parent that is not duplicated in the surrounding text should be included. A longer description, such as `alt="Fluffy, a tri-color terrier with very short hair, with a tennis ball in her mouth."` is appropriate. As the surrounding text likely has Fluffy's size and breed, that is not included in the `alt`. However, as the dog's biography likely doesn't include hair length, colors, or toy preferences, which the potential parent needs to know, it is included. Is the image outdoors, or does Fluffy have a red collar with a blue leash? Not important in terms of adopting the pet and therefore not included. All information image conveys that a sighted user can access and is relevant to the context is what needs to be conveyed; nothing more. Keep it short, precise, and useful. -Any personal knowledge or extra description shouldn't be included here, as it is not useful for people who have not seen the image before. If the ball is Fluffy's favorite toy or if the sited user can't know that from the image, then don't include it. +Any personal knowledge or extra description shouldn't be included here, as it is not useful for people who have not seen the image before. If the ball is Fluffy's favorite toy or if a sighted user can't know that from the image, then don't include it. One thing to consider is whether your images have meaning inside your content, or whether they are purely for visual decoration, and thus have no meaning. If they are decorative, it is better to write an empty text as a value for `alt` attribute (see [Empty alt attributes](#empty_alt_attributes)) or to just include them in the page as CSS background images. diff --git a/files/en-us/learn_web_development/core/scripting/functions/index.md b/files/en-us/learn_web_development/core/scripting/functions/index.md index de9bb13e58fd42f..bcf8de7975872bf 100644 --- a/files/en-us/learn_web_development/core/scripting/functions/index.md +++ b/files/en-us/learn_web_development/core/scripting/functions/index.md @@ -356,7 +356,9 @@ function greeting() { } ``` -Both functions you want to call are called `greeting()`, but you can only ever access the `first.js` file's `greeting()` function (the second one is ignored). In addition, an error results when attempting (in the `second.js` file) to assign a new value to the `name` variable — because it was already declared with `const`, and so can't be reassigned. +You will see that the second script does not load and run at all, and an error is printed in the console: `Uncaught SyntaxError: Identifier 'name' has already been declared`. This is because the `name` constant is already declared in `first.js`, and you can't declare the same constant twice in the same scope. Because the second script did not load, the `greeting()` function from `second.js` is not available to be called. Therefore, you will see an alert box displaying `Hello Chris: welcome to our company.`. + +Try removing the second `const name = "Zaptec";` line from `second.js` and reloading the page. Now both scripts execute, and the alert box says `Our company is called Chris.`. Functions are allowed to be redeclared, and the last declaration gets used. The previous declarations are effectively overwritten. > [!NOTE] > You can see this example [running live on GitHub](https://mdn.github.io/learning-area/javascript/building-blocks/functions/conflict.html) (see also the [source code](https://github.com/mdn/learning-area/tree/main/javascript/building-blocks/functions)). diff --git a/files/en-us/learn_web_development/core/scripting/index.md b/files/en-us/learn_web_development/core/scripting/index.md index 356a33666ad4a13..7122a2b90620b08 100644 --- a/files/en-us/learn_web_development/core/scripting/index.md +++ b/files/en-us/learn_web_development/core/scripting/index.md @@ -12,7 +12,7 @@ JavaScript is a huge topic, with so many different features, styles, and techniq ## Prerequisites -Before starting this module, you don't need any previous JavaScript knowledge, but you should have worked through the previous modules in the course. You should have at least know [HTML](/en-US/docs/Learn_web_development/Core/Structuring_content) and the [basic fundamentals of CSS](/en-US/docs/Learn_web_development/Core/Styling_basics). +Before starting this module, you don't need any previous JavaScript knowledge, but you should have worked through the previous modules in the course. You should at least know [HTML](/en-US/docs/Learn_web_development/Core/Structuring_content) and the [basic fundamentals of CSS](/en-US/docs/Learn_web_development/Core/Styling_basics). > [!NOTE] > If you are working on a computer/tablet/other device where you don't have the ability to create your own files, you could try out (most of) the code examples in an online coding program such as [JSBin](https://jsbin.com/) or [Glitch](https://glitch.com/). diff --git a/files/en-us/learn_web_development/core/scripting/what_went_wrong/index.md b/files/en-us/learn_web_development/core/scripting/what_went_wrong/index.md index 1ef1a9a2ae1cfbe..b62bb416046297d 100644 --- a/files/en-us/learn_web_development/core/scripting/what_went_wrong/index.md +++ b/files/en-us/learn_web_development/core/scripting/what_went_wrong/index.md @@ -34,7 +34,7 @@ When you built up the "Guess the number" game in the previous article, you may h Generally speaking, when you do something wrong in code, there are two main types of error that you'll come across: -- **Syntax errors**: These are spelling errors in your code that actually cause the program not to run at all, or stop working part way through — you will usually be provided with some error messages too. These are usually okay to fix, as long as you are familiar with the right tools and know what the error messages mean! +- **Syntax errors**: These are spelling errors in your code that actually cause the program not to run at all, or stop working part way through — you will usually be provided with some error messages too. These are usually not too hard to fix, as long as you are familiar with the right tools and know what the error messages mean! - **Logic errors**: These are errors where the syntax is actually correct but the code is not what you intended it to be, meaning that program runs successfully but gives incorrect results. These are often harder to fix than syntax errors, as there usually isn't an error message to direct you to the source of the error. Okay, so it's not quite _that_ simple — there are some other differentiators as you drill down deeper. But the above classifications will do at this early stage in your career. We'll look at both of these types going forward. diff --git a/files/en-us/learn_web_development/extensions/server-side/django/development_environment/index.md b/files/en-us/learn_web_development/extensions/server-side/django/development_environment/index.md index 94392fb9ee045e5..0436dcd9942771e 100644 --- a/files/en-us/learn_web_development/extensions/server-side/django/development_environment/index.md +++ b/files/en-us/learn_web_development/extensions/server-side/django/development_environment/index.md @@ -426,8 +426,7 @@ In addition to branches, it is possible to create `tags` on any branch and later ### Create an account and repository on GitHub -First we will create a free account on GitHub. -With a free account you can't create private repos, but you can create as many _public_ repositories ("repos") as you like. +First we will create an account on GitHub (this is free). Then we create and configure a repository named "django_local_library" for storing the [Local library website](/en-US/docs/Learn_web_development/Extensions/Server-side/Django/Tutorial_local_library_website) as we evolve it in the rest of this tutorial. The steps are: diff --git a/files/en-us/learn_web_development/getting_started/environment_setup/browsing_the_web/index.md b/files/en-us/learn_web_development/getting_started/environment_setup/browsing_the_web/index.md index b5f77efc4962c13..62c37f3bc54d5a3 100644 --- a/files/en-us/learn_web_development/getting_started/environment_setup/browsing_the_web/index.md +++ b/files/en-us/learn_web_development/getting_started/environment_setup/browsing_the_web/index.md @@ -144,7 +144,7 @@ When you access the web, quite a lot happens between your first interaction (for 2. When that file is received by the browser, it will start to parse it, and will probably find instructions to make more requests. As discussed above, these might be for files to embed such as images, style information, scripts, and so on. 4. When all of the resources have been requested, the web browser parses and renders them as required, before displaying the result to the user. -This description of how the web works is heavily simplified, but it is all you really need to know at this point. You will find a more detailed account of how web pages and requested and rendered by a web browser in our [Web standards](/en-US/docs/Learn_web_development/Getting_started/Web_standards) module, slightly later on. +This description of how the web works is heavily simplified, but it is all you really need to know at this point. You will find a more detailed account of how web pages are requested and rendered by a web browser in our [Web standards](/en-US/docs/Learn_web_development/Getting_started/Web_standards) module, slightly later on. For now, try opening a web browser and loading up a couple of your favorite sites, thinking about the above steps as you do so. @@ -208,7 +208,7 @@ As a result, you need to be careful to check the answers they give you, and not - Typing in `"ant fish cheese"` (with the quotes) will only return results that contain that exact phrase. - `"ant cheese" -fish` will return results that contain `ant` and/or `cheese` but not `fish`. - - `and OR cheese` will only return results with one term or the other, not both. From our testing, this one only seemed to work effectively in Google. + - `ant OR cheese` will only return results with one term or the other, not both. From our testing, this one only seemed to work effectively in Google. - `intitle:cheese` will only return results that have "cheese" in the main title of the page. > [!NOTE] diff --git a/files/en-us/learn_web_development/getting_started/web_standards/the_web_standards_model/index.md b/files/en-us/learn_web_development/getting_started/web_standards/the_web_standards_model/index.md index 18a7515962b12b7..7cc3aa8a6eb6348 100644 --- a/files/en-us/learn_web_development/getting_started/web_standards/the_web_standards_model/index.md +++ b/files/en-us/learn_web_development/getting_started/web_standards/the_web_standards_model/index.md @@ -8,10 +8,7 @@ page-type: tutorial-chapter {{PreviousMenuNext("Learn_web_development/Getting_started/Web_standards/How_the_web_works", "Learn_web_development/Getting_started/Web_standards/How_browsers_load_websites", "Learn_web_development/Getting_started/Web_standards")}} -> [!NOTE] -> The content in this article is currently incomplete, sorry about that! We are working hard to improve the MDN Learn Web Development section, and we will have places marked as incomplete ("TODO") finished soon. - -This article provides some useful background on the web and web standards — how they came about, what web standard technologies are, and how they work together. +This article provides some useful background on the web and web standards — how they came about, what web standards technologies are, and how they work together. @@ -25,9 +22,8 @@ This article provides some useful background on the web and web standards — ho
Learning outcomes:
    +
  • Web standards, and the key principles they are built on.
  • How standards bodies operate — for example the W3C, WHATWG, TC39, and Khronos Group; the process of standards creation.
    • -
  • The lifecycle of web standards features.
    • -
  • The key principles web standards are built on.
  • The main web standards technologies, and how they work together.
  • Web best practices.
@@ -38,64 +34,98 @@ This article provides some useful background on the web and web standards — ho ## Brief history of the web -We'll keep this very brief, as there are many (more) detailed accounts of the web's history out there, which we'll link to later on (also try searching for "history of the web" in your favorite search engine and see what you get, if you are interested in more detail.) +In the late 1960s, the US military developed a communication network called [ARPANET](/en-US/docs/Glossary/Arpanet). This can be considered a forerunner of the **internet**, as it worked on [packet switching](https://en.wikipedia.org/wiki/Packet_switching), and featured the first implementation of the [TCP/IP](https://en.wikipedia.org/wiki/Internet_protocol_suite) protocol suite. These two technologies form the basis of the infrastructure that the internet is built on. -In the late 1960s, the US military developed a communication network called [ARPANET](/en-US/docs/Glossary/Arpanet). This can be considered a forerunner of the Web, as it worked on [packet switching](https://en.wikipedia.org/wiki/Packet_switching), and featured the first implementation of the [TCP/IP](https://en.wikipedia.org/wiki/Internet_protocol_suite) protocol suite. These two technologies form the basis of the infrastructure that the internet is built on. - -In 1980, Tim Berners-Lee (often referred to as TimBL) wrote a notebook program called ENQUIRE, which featured the concept of links between different nodes. Sound familiar? +In 1980, [Tim Berners-Lee](https://en.wikipedia.org/wiki/Tim_Berners-Lee) (often referred to as TimBL) wrote a notebook program called ENQUIRE, which featured the concept of links between different nodes. Sound familiar? Fast forward to 1989, and TimBL wrote [Information Management: A Proposal](https://www.w3.org/History/1989/proposal.html) and HyperText at CERN; these two publications together provided the background for how the web would work. They received a fair amount of interest, enough to convince TimBL's bosses to allow him to go ahead and create a global hypertext system. -By late 1990, TimBL had created all the things needed to run the first version of the web — [HTTP](/en-US/docs/Web/HTTP), [HTML](/en-US/docs/Web/HTML), the first web browser, which was called [WorldWideWeb](https://en.wikipedia.org/wiki/WorldWideWeb), an HTTP server, and some web pages to look at. +By 1990-91, TimBL had created all the things needed to run the first version of the **World Wide Web** (generally referred to as the **web**) — [HTTP](/en-US/docs/Web/HTTP), [HTML](/en-US/docs/Web/HTML), the first web browser, which was called [WorldWideWeb](https://en.wikipedia.org/wiki/WorldWideWeb), a web server, and some web pages to look at. + +> [!NOTE] +> People sometimes use "the web" and "the internet" interchangeably, but they are different things. The internet is the infrastructure that enables information to be transported around the world between different servers and clients, whereas the web is a system built on top of the internet. The web defines types of information (content and code) that are transported via the internet and communications protocols to manage that transport. + +In 1994, TimBL founded the [World Wide Web Consortium](https://en.wikipedia.org/wiki/World_Wide_Web_Consortium) (W3C), an organization that brings together representatives from many different companies to work together on the creation of web technologies. The W3C worked on standardizing and improving existing web technologies such as HTML and HTTP, and creating new technologies such as [CSS](/en-US/docs/Web/CSS) and [JavaScript](/en-US/docs/Web/JavaScript). CSS and JavaScript in particular were vital for giving the web styling and interactivity, making it look more like the web we know today. -In the next few years that followed, the web exploded, with multiple browsers being released, thousands of web servers being set up, and millions of web pages being created. OK, that's a very simple summary of what happened, but we did promise you a brief summary. +In the next few years that followed, the web exploded, with multiple browsers being released, thousands of web servers being set up, and millions of web pages being created. Other standards organizations also appeared to help standardize different aspects of web technologies. -One last significant data point to share is that in 1994, TimBL founded the [World Wide Web Consortium](https://en.wikipedia.org/wiki/World_Wide_Web_Consortium) (W3C), an organization that brings together representatives from many different technology companies to work together on the creation of web technology specifications. After that other technologies followed such as [CSS](/en-US/docs/Web/CSS) and [JavaScript](/en-US/docs/Web/JavaScript), and the web started to look more like the web we know today. +> [!NOTE] +> If you are interested in reading a more detailed account of web history, try searching for "history of the web" in your favorite [search engine](/en-US/docs/Learn_web_development/Getting_started/Environment_setup/Browsing_the_web#search_engine) and see what you can find. ## Web standards -**Web standards** are the technologies we use to build websites. These standards exist as long technical documents called specifications, which detail exactly how the technology should work. These documents are not very useful for learning how to use the technologies they describe (this is why we have sites like MDN Web Docs), but instead are intended to be used by software engineers to implement these technologies (usually in web browsers). +**Web standards** are the technologies we use to build websites. These standards exist as long technical documents called specifications, which detail exactly how the technology should work. These documents are not very useful for learning how to use the technologies they describe (this is why we have sites like MDN Web Docs). Instead, they are intended to be used by software engineers to implement these technologies (usually in web browsers). + +### Standards bodies and processes + +Web standards are created by standards bodies — institutions that invite groups of people from different technology companies to come together and agree on how the technologies should work in the best way to fulfill all of their use cases. + +The W3C is the best known web standards body, but there are others. For example: + +- [WHATWG](https://whatwg.org/) maintains the [HTML Living Standard](https://html.spec.whatwg.org/multipage/), which describes exactly how HTML (all the HTML elements, and their associated APIs, and other surrounding technologies) should be implemented. +- [TC39](https://tc39.es/) and [ECMA](https://ecma-international.org/) specify and publish the standard for ECMAScript, which modern JavaScript is based on. +- [Khronos](https://www.khronos.org/) publish technologies for 3D graphics, such as WebGL. + +The full processes by which standards are created can get deep and complex. However, unless you want to create your own web technology features, you don't need to understand most of it. If you want to contribute to the discussion around new technologies and provide feedback, it is usually a matter of joining the relevant mailing list or other discussion mechanism. Standards discussions are carried out in public, hence the term ["Open" standards](#open_standards). + +For now, we'll give you a general, high-level understanding of how standards processes work: + +1. Someone notices the need for a new web standard feature that will make developers' lives easier. For example, maybe there is a common pattern that is commonly used in web user interfaces, but it is a pain to implement. A dedicated CSS feature would make it much easier. The someone could be anyone — an individual developer, or an engineer working for a big tech company. +2. The person discusses this feature with other developers, browser engineers, etc., and starts to create interest in implementing the feature. Usually they write an explainer document that explains the need for the feature and how it will work, and a code demo that shows what the feature would look like in action. +3. If there is enough interest in the feature, it is formally discussed inside the relevant standards body working group. For example, CSS features are usually discussed by the [CSS Working Group](https://www.w3.org/groups/wg/css/) (WG) (see also the [CSS Working Group Wikipedia page](https://en.wikipedia.org/wiki/CSS_Working_Group) for a bit more description and history). Before a new web technology is accepted, it must be rigorously evaluated to make sure it is good for the web — for example, it doesn't introduce any security problems, it is [accessible and compatible](#accessible_and_interoperable) with other web technologies, and it doesn't rely on patents. +4. To prove out the feature, several things happen. These points can all happen around the same time as Point 3., or even before (browser vendors sometimes implement proprietary/non-standard features and then attempt to standardize them afterwards): + + 1. One or more browser vendors will implement an experimental version of the new feature, often disabled by default, but which can be enabled by people who want to test it and provide feedback. + 2. A working group member will also add it to a technology specification so that browser vendors are able to implement it consistently. + 3. They will also seek out feedback from other browser vendors to see what issues they have with the proposal, and how likely they are to implement it. These are called Standards positions. See for example [Mozilla Standards Positions](https://mozilla.github.io/standards-positions/). + 4. Involved individuals will also write an extensive suite of tests to demonstrate that the feature works as described. -For example, the [HTML Living Standard](https://html.spec.whatwg.org/multipage/) describes exactly how HTML (all the HTML elements, and their associated APIs, and other surrounding technologies) should be implemented. +5. Eventually, if all is well, the feature will be implemented across all browsers and can start being used when creating websites. -Web standards are created by standards bodies — institutions that invite groups of people from different technology companies to come together and agree on how the technologies should work in the best way to fulfill all of their use cases. The W3C is the best known web standards body, but there are others such as the [WHATWG](https://whatwg.org/) (who maintain the living standards for the HTML language), [ECMA](https://ecma-international.org/) (who publish the standard for ECMAScript, which JavaScript is based on), [Khronos](https://www.khronos.org/) (who publish technologies for 3D graphics, such as WebGL), and others. +> [!NOTE] +> It is perfectly possible that the people suggesting the feature, implementing it in a browser, creating the specification, writing tests, and collecting feedback on it, are the same person/people. + +You can find more information on specific standards body processes. See for example: -### Web standards key principles +- [W3C Process Document](https://www.w3.org/policies/process/) +- [WHATWG — Working Mode](https://whatwg.org/working-mode) +- [The TC39 Process](https://tc39.es/process-document/) -The basic principles of the web: +## Web standards key principles -- Open to contribute and use. -- Not patent-encumbered or controlled by a single private entity. +The key principles of the web, which make the web a unique and exciting industry to get involved in, are as follows: + +- Open to contribute and use, and therefore not patent-encumbered or controlled by a single private entity. - Accessible and interoperable. - They don't break the web. -This basis means that the web is a unique and exciting industry to get involved in. +Let's look at each of these in a little more detail. ### "Open" standards -One of the key aspects of web standards, which TimBL and the W3C agreed on from the start, is that the web (and web technologies) should be free to both contribute and use, and not encumbered by patents/licensing. Therefore anyone can write the code to build a website for free, and anyone can contribute to the standards creation process, where the specs are written. - -Because web technologies are created openly, in collaboration between many different companies, it means that no one company gets to control them, which is a really good thing. You wouldn't want a single company suddenly deciding to put the entire web behind a paywall, or releasing a new version of HTML that everyone has to buy to continue making websites, or worse still, just deciding they aren't interested any more and just turning it off. +One of the key aspects of web standards, which TimBL and the W3C agreed on from the start, is that the web (and web technologies) should be **open**. This means they free to both contribute to and use, and not encumbered by patents/licensing. This is important — if a web technology relies on patented/licensed technologies to function, the patent/owner can then charge implementing browser vendors potentially large amounts of of money, and those costs would then be passed onto the browser users. -This allows the web to remain a freely-available public resource. +In addition, because web technologies are created openly, in collaboration between many different companies, it means that no one company gets to control them, which is a really good thing. You wouldn't want a single company suddenly deciding to put the entire web behind a paywall, or releasing a new version of HTML that everyone has to buy to continue making websites, or worse still, deciding they aren't interested any more and just turning it off. -### Don't break the web +Open standards enable the web to remain a freely-available public resource, where anyone can write the code to build a website for free, and anyone can contribute to the standards creation process. -Another phrase you'll hear around open web standards is "don't break the web" — the idea is that any new web technology that is introduced should be backwards compatible with what went before it (i.e. old websites will still continue to work), and forwards compatible (future technologies in turn will be compatible with what we currently have). As you go through the learning material presented here, you'll start to learn how this is made possible with some very clever design and implementation work. +### Accessible and interoperable -## Standards bodies +The web and web browsers are fundamentally designed so that web content is **accessible** to people with disabilities. It was originally envisaged as a great leveller, enabling people to access information regardless of circumstance. This means that, for example: -[W3C](https://www.w3.org/), [WHATWG](https://whatwg.org/), [TC39](https://tc39.es/), and [Khronos Group](https://www.khronos.org/) +- People who are unable to use a mouse or pointing device can use the keyboard to navigate the web. +- People who are visually impaired can magnify content, or use a program called a **screen reader** to read content out to them and describe controls in a way that makes sense. -The full W3C standards process is deep and academic. For now, you should understand how different individuals and companies get involved in the standards process. +> [!NOTE] +> You'll learn more about [Accessibility](/en-US/docs/Learn_web_development/Core/Accessibility) later on in the learning pathway. - +In addition, web technologies are intended to be **interoperable**. Because web technologies are implemented according to published standards, browsers should provide the same rendered output for a given input (for example, HTML, CSS, or JS code) — in other words, a website should work consistently across multiple browsers. -## The web standards lifecycle +### Don't break the web -The different maturity stages are designed to weed out issues (e.g. interoperability issues, patent issues). +Another phrase you'll hear around open web standards is "don't break the web". The idea behind this is that any new web technology should be backwards compatible with what went before it, so existing websites will continue to work in the same way as they did before. - +Web browser vendors should be able to implement new web technologies without causing a difference in rendering or functionality that would cause their users to think a website is broken and try another browser as a result. ## Overview of modern web technologies @@ -107,7 +137,7 @@ There are a number of technologies to learn if you want to be a front-end web de - HTML is for structure and semantics (meaning). - CSS is for styling and layout. -- JavaScript is for controlling dynamic behavior. +- JavaScript and APIs are for controlling dynamic behavior. #### HTML @@ -125,7 +155,7 @@ If we adopted a house-building analogy, HTML would be like the foundations and w #### CSS -Cascading Style Sheets (**CSS**) is a rule-based language used to apply styles to your HTML — for example, setting text and background colors, adding borders, animating things, or laying out a page in a certain way. As a simple example, the following code would turn our HTML paragraph red: +Cascading Style Sheets (**CSS**) is a rule-based language used to apply styles to your HTML — for example, setting text and background colors, adding borders, animating things, or laying out a page in a certain way. As a simple example, the following code would turn all HTML paragraphs red: ```css p { @@ -135,30 +165,32 @@ p { In the house analogy, CSS is like the paint, wallpaper, carpets and paintings you'd use to make the house look nice. -#### JavaScript +#### JavaScript (and APIs) -**JavaScript** is the programming language we use to add interactivity to websites, from dynamic style switching, to fetching updates from the server, right through to complex 3D graphics. The following simple JavaScript will store a reference to our paragraph in memory and change the text inside it: +**JavaScript** is the programming language we use to add interactivity to websites, from dynamic style switching, to fetching updates from the server, right through to complex 3D graphics. The following simple JavaScript store a reference to a paragraph in memory and change the text inside it: ```js let pElem = document.querySelector("p"); pElem.textContent = "We changed the text!"; ``` -In the house analogy, JavaScript is like the cooker, TV, Microwave, or hairdryer — the things that give your house useful functionality. +You'll also hear the term **APIs** along with JavaScript. API stands for **Application Programming Interface**. In general terms, an API is a bit of code that allows you to control other more complex bits of code or other functionality on your computer (such as hardware devices like your webcam or microphone) in a manageable way. -#### Separating the layers +For example, writing your own interface to communicate with your webcam and capture a video stream from it, but the JavaScript [`getUserMedia()`](/en-US/docs/Web/API/MediaDevices/getUserMedia#examples) API method allows you to do this fairly easily. It does all the hard work for you, behind the scenes, so you don't need to reinvent the wheel each time. -Separating the technology layers is a good idea, for: +The simple code snippet above also uses an API. [`querySelector()`](/en-US/docs/Web/API/Document/querySelector) and [`textContent`](/en-US/docs/Web/API/Node/textContent) are both parts of the [Document Object Model (DOM)](/en-US/docs/Learn_web_development/Core/Scripting/DOM_scripting) family of APIs, which allow you to use JavaScript to manipulate web documents. -- Code management and comprehension. -- Teamwork/separation of roles. -- Performance. +In the house analogy, JavaScript is like the cooker, TV, Microwave, or hairdryer — the things that give your house useful functionality. + +### Other web technologies -In reality, the separation is not always clear. It is an ideal to aim for where possible rather than an absolute. +There are other technologies used on the web, for example: -- A prime example is the case of using JavaScript to dynamically update CSS styling on-the-fly in response to app state changes, user choices, etc. -- Often this is done by modifying the Element.style.x properties, which results in inline CSS being injected into HTML. A better strategy is to add/change classes on elements to avoid inline CSS. -- Much more severe is the case of JavaScript frameworks that use various HTML-in-JavaScript or CSS-in-JavaScript custom syntax, which results in a lot of mixing of syntax types. +- [HTTP](/en-US/docs/Web/HTTP) for communicating between clients and servers, as mentioned earlier. +- [SVG](/en-US/docs/Web/SVG) for creating and manipulating vector graphics. +- [MathML](/en-US/docs/Web/MathML) for describing mathematical formulae. + +However, HTML, CSS, and JavaScript by far the most important technologies to learn, so we will focus mainly on those in our learning pathway. ### Tools @@ -166,44 +198,45 @@ Once you've learned the "raw" technologies that can be used to build web pages ( - The [developer tools](/en-US/docs/Learn_web_development/Howto/Tools_and_setup/What_are_browser_developer_tools) inside modern browsers that can be used to debug your code. - [Testing tools](/en-US/docs/Learn_web_development/Extensions/Testing) that can be used to run tests to show whether your code is behaving as you intended it to. -- Libraries and frameworks built on top of JavaScript that allow you to build certain types of website much more quickly and effectively. -- So-called "Linters", which take a set of rules, look at your code, and highlight places where you haven't followed the rules properly. -- Minifiers, which remove all the whitespace from your code files to make it so that they are smaller and therefore download from the server more quickly. +- [Frameworks and libraries](/en-US/docs/Learn_web_development/Core/Frameworks_libraries) built on top of JavaScript that allow you to build certain types of website much more quickly and effectively. +- So-called **Linters** and **formatters**, which take a set of rules for coding style, look at your code, and update your code to follow those rules. Prettier, which you [met earlier in the course](/en-US/docs/Learn_web_development/Getting_started/Environment_setup/Code_editors#enhancing_your_code_editor_with_extensions), is an example of a formatter. ### Server-side languages and frameworks HTML, CSS, and JavaScript are front-end (or client-side) languages, which means they are run by the browser to produce a website front-end that your users can use. -There are another class of languages called back-end (or server-side) languages, meaning that they are run on the server before the result is then sent to the browser to be displayed. A typical use for a server-side language is to get some data out of a database and generate some HTML to contain the data, before then sending the HTML over to the browser to display it to the user. +There are another class of languages called back-end (or server-side) languages, meaning that they are run on the server before the result is then sent to the browser to be displayed. A typical use for a server-side language is to get some data out of a database, generate some HTML to contain the data, then send the HTML over to the browser to display it to the user. -Example server-side frameworks include ASP.NET (in C#), Django (in Python), Laravel (in PHP), and Next.js (in JavaScript). +Example server-side frameworks include ASP.NET (C#), Django (Python), Laravel (PHP), and Next.js (JavaScript). ## Web best practices -We have briefly talked about the technologies that you'll use to build websites. Now let's discuss the best practices you should employ to make sure you are using those technologies in the best way that you can. +We have briefly talked about the technologies that you'll use to build websites. Now let's discuss the best practices that web developers generally employ to ensure that their websites are usable by as many people as possible. When doing web development, the main cause of uncertainty comes from the fact that you don't know what combination of technology each user will use to view your website: - User 1 might be looking at it on an iPhone, with a small, narrow screen. - User 2 might be looking at it on a Windows laptop with a widescreen monitor attached to it. -- User 3 might be blind, and using a screen reader to read the web page out to them. +- User 3 might be visually impaired, and using a screen reader to read and interact with the web page. - User 4 might be using a really old desktop machine that can't run modern browsers. -Because you don't know exactly what your users will use, you need to design defensively — make your website as flexible as possible, so that all of the above users can make use of it, even if they might not all get the same experience. In short, we are trying to make the web work for all, as much as possible. - -You'll come across the below concepts at some point in your studies. - -- **Progressive enhancement** is the practice of creating a minimal experience that provides the essential functionality to all users, and layering on a better experience and other enhancements in browsers that can support them. Progressive enhancement is often seen as unimportant, because browsers tend to support new features more consistently these days, and people tend to have faster internet connections. However, you should think about examples relevant to the modern day — cutting down on decoration to make a mobile experience smoother and save on data, or providing a simpler, lower-bandwidth experience for users in developing countries who might still pay for home internet by the megabyte. -- **Cross-browser compatibility** is the practice of trying to make sure your webpage works across as many devices as possible. This includes using technologies that all the browsers support, delivering better experiences to browsers that can handle them (progressive enhancement), and/or writing code so that it falls back to a simpler but still usable experience in older browsers (graceful degradation). It also involves a lot of testing to see if anything fails in certain browsers, and then more work to fix those failures. -- **Responsive web design** is the practice of making your functionality and layouts flexible so they can automatically adapt to different browsers. An obvious example is a website that is laid out one way in a widescreen browser on the desktop, but displays as a more compact, single-column layout on mobile phone browsers. Try adjusting the width of your browser window now, and see what happens. -- **Performance** means getting websites to load as quickly as possible, but also making them intuitive and easy to use so that users don't get frustrated and go somewhere else. -- **Accessibility** means making your websites usable by as many different kinds of people as possible (related concepts are diversity and inclusion, and inclusive design). This includes people with visual impairments, hearing impairments, cognitive disabilities, or physical disabilities. It also goes beyond people with disabilities — how about young or old people, people from different cultures, people using mobile devices, or people with unreliable or slow network connections? -- **Internationalization** means making websites usable by people from different cultures, who speak different languages to your own. There are technical considerations here (such as altering your layout so that it still works OK for right-to-left, or even vertical languages), and human ones (such as using simple, non-slang language so that people who have your language as their second or third language are more likely to understand your text). -- **Privacy & Security**. These two concepts are related but different. Privacy refers to allowing people to go about their business privately and not spying on them or collecting more of their data than you absolutely need to. Security refers to constructing your website in a secure way so that malicious users cannot steal information contained on it from you or your users. - -## See also - -- [History of the World Wide Web](https://en.wikipedia.org/wiki/History_of_the_World_Wide_Web) -- [How does the internet work?](/en-US/docs/Learn_web_development/Howto/Web_mechanics/How_does_the_Internet_work) +Because you don't know exactly what your users will use, you need to design defensively — make your website as flexible as possible, so that all of the above users can make use of it, even if they might not all get the same experience. + +You'll come across the below concepts at some point in your studies, which represent best practices your websites should ideally adhere to. Don't worry about these too much for now. Throughout most of the course we try to teach these implicitly, meaning that when we teach you HTML, CSS, and JavaScript, our examples will follow the best practices where possible. Later on in your learning journey you will likely explore explicit teachings in these areas. + +- **Progressive enhancement** + - : Creating a minimal experience that provides the essential functionality to all users, and layering on a better experience and other enhancements in browsers that can support them. Progressive enhancement is often seen as unimportant, because browsers tend to support new features more consistently these days, and people tend to have faster internet connections with higher limits on data usage. However, consider examples like cutting down on decoration to make a mobile experience smoother and save on data or providing a lighter, low-bandwidth experience for users who pay by the megabyte or have metered connections. +- **Cross-browser compatibility** + - : Trying to make sure your webpage works across as many devices as possible. This includes using technologies that all the browsers support, delivering better experiences to browsers that can handle them (progressive enhancement), and/or writing code so that it falls back to a simpler but still usable experience in older browsers (termed **graceful degradation**). It also requires testing to see if anything fails in certain browsers, and then more work to fix those failures. +- **Separating the layers** + - : Putting your content (HTML), styling (CSS), and behavior (JavaScript) in different code files, rather than lumping them all together in the same place. This is a good idea for many reasons, including code management and comprehension and teamwork/separation of roles. In reality, the separation is not always clear. It is an ideal to aim for where possible, rather than an absolute. +- **Responsive web design** + - : Making your functionality and layouts flexible so they can automatically adapt to different browsers. An obvious example is a website that is laid out one way in a widescreen browser on the desktop, but displays as a more compact, single-column layout on mobile phone browsers. Try adjusting the width of your browser window now, and see what happens to the site layout. +- **Performance** + - : Getting websites to load as quickly as possible, but also making them intuitive and easy to use so that users don't get frustrated and go somewhere else. +- **Internationalization** + - : Making websites usable by people from different cultures, who speak different languages to your own. There are technical considerations here (such as altering your layout so that it still works OK for right-to-left or top-to-bottom languages), and human ones (such as using simple, non-slang language so that diverse cultures are more likely to understand your text). +- **Privacy** & **Security** + - : These two concepts are related but different. Privacy refers to allowing people to go about their business privately and not spying on them or collecting more of their data than you absolutely need to. Security refers to constructing your website in a secure way so that malicious users cannot steal information contained on it from you or your users. {{PreviousMenuNext("Learn_web_development/Getting_started/Web_standards/How_the_web_works", "Learn_web_development/Getting_started/Web_standards/How_browsers_load_websites", "Learn_web_development/Getting_started/Web_standards")}} diff --git a/files/en-us/web/api/animation/index.md b/files/en-us/web/api/animation/index.md index 94b574321cc42ca..148b052a41d069a 100644 --- a/files/en-us/web/api/animation/index.md +++ b/files/en-us/web/api/animation/index.md @@ -26,6 +26,8 @@ The **`Animation`** interface of the [Web Animations API](/en-US/docs/Web/API/We - : Returns the current finished Promise for this animation. - {{domxref("Animation.id")}} - : Gets and sets the `String` used to identify the animation. +- {{domxref("Animation.overallProgress")}} {{ReadOnlyInline}} {{experimental_inline}} + - : Returns a number between `0` and `1` indicating the animation's overall progress towards its finished state. - {{domxref("Animation.pending")}} {{ReadOnlyInline}} - : Indicates whether the animation is currently waiting for an asynchronous operation such as initiating playback or pausing a running animation. - {{domxref("Animation.playState")}} {{ReadOnlyInline}} diff --git a/files/en-us/web/api/animation/overallprogress/index.md b/files/en-us/web/api/animation/overallprogress/index.md new file mode 100644 index 000000000000000..bf7214bbf8f8ee2 --- /dev/null +++ b/files/en-us/web/api/animation/overallprogress/index.md @@ -0,0 +1,149 @@ +--- +title: "Animation: overallProgress property" +short-title: overallProgress +slug: Web/API/Animation/overallProgress +page-type: web-api-instance-property +status: + - experimental +browser-compat: api.Animation.overallProgress +--- + +{{APIRef("Web Animations")}}{{seecompattable}} + +The **`overallProgress`** read-only property of the {{domxref("Animation")}} interface returns a number between `0` and `1` indicating the animation's overall progress towards its finished state. This is the overall progress across all of the animation's iterations, not each individual iteration. + +`overallProgress` works consistently across all animations, regardless of the type of {{domxref("AnimationTimeline", "timeline")}}. + +## Value + +A number between `0` and `1`, or `null` if the animation lacks a timeline, is inactive or hasn't been played yet, or if its {{domxref("Animation/currentTime", "currentTime")}} is set to a non-time value. + +If the animation's [`iterations`](/en-US/docs/Web/API/KeyframeEffect/KeyframeEffect#iterations) property is set to `Infinity`, or if its {{domxref("Animation/currentTime", "currentTime")}} is set to a negative value, `overallProgress` will return `0`. + +If the animation's [`duration`](/en-US/docs/Web/API/KeyframeEffect/KeyframeEffect#duration) is set to `0`, `overallProgress` will return `1`. + +## Examples + +### Displaying a percentage progress + +This demo uses `overallProgress` to create a "percentage progress" readout, which is displayed to the screen while an animation runs. + +### HTML + +The HTML contains a {{htmlelement("button")}} to press to start the animation, a {{htmlelement("p")}} element in which to display the percentage progress, and a {{htmlelement("div")}} that will be animated. + +```html + +

Progress: 0%

+
+``` + +The demo's CSS provides some rudimentary styling, which is not important for understanding how the JavaScript works, therefore we have hidden it for brevity. + +```css hidden +* { + box-sizing: border-box; +} + +html { + font-family: Arial, Helvetica, sans-serif; +} + +body { + margin: 0; + width: 500px; + margin: 0 auto; + padding: 20px; +} + +.progress { + font-weight: bold; +} + +.box { + width: 100px; + height: 100px; + border-radius: 40px 20px; + border: 10px solid black; + background: lightseagreen; + margin: 0 auto; +} +``` + +### JavaScript + +In the JavaScript, we start off by grabbing references to the {{htmlelement("button")}}, {{htmlelement("p")}}, and {{htmlelement("div")}} elements. + +We then create: + +- an `animation` variable which will reference the animation, once we've created it +- a [keyframes](/en-US/docs/Web/API/Web_Animations_API/Keyframe_Formats) array +- an options object containing timing properties. + +```js +const btn = document.querySelector("button"); +const progress = document.querySelector(".progress"); +const box = document.querySelector(".box"); + +let animation; + +const keyframes = [{ rotate: "0deg" }, { rotate: "360deg" }]; + +const timingProps = { + duration: 3000, + iterations: 1, +}; +``` + +Next we add a `"click"` event listener to the `
Valid local date and time string - YYYY-MM-DDHH:MM
+ YYYY-MM-DD HH:MM
YYYY-MM-DD HH:MM:SS
YYYY-MM-DD HH:MM:SS.mmm
YYYY-MM-DDTHH:MM
diff --git a/files/en-us/web/http/headers/content-security-policy/index.md b/files/en-us/web/http/headers/content-security-policy/index.md index 5236dfab2603318..3443265a5b127b2 100644 --- a/files/en-us/web/http/headers/content-security-policy/index.md +++ b/files/en-us/web/http/headers/content-security-policy/index.md @@ -207,7 +207,8 @@ If a directive contains a nonce and `unsafe-inline`, then the browser ignores `u See [Nonces](/en-US/docs/Web/HTTP/CSP#nonces) in the CSP guide for more usage information. -> [!NOTE] Nonce source expressions are only applicable to {{htmlelement("script")}} and {{htmlelement("style")}} elements. +> [!NOTE] +> Nonce source expressions are only applicable to {{htmlelement("script")}} and {{htmlelement("style")}} elements. ### '\-' @@ -230,7 +231,8 @@ If a directive contains a hash and `unsafe-inline`, then the browser ignores `un See [Hashes](/en-US/docs/Web/HTTP/CSP#hashes) in the CSP guide for more usage information. -> [!NOTE] Hash source expressions are only applicable to {{htmlelement("script")}} and {{htmlelement("style")}} elements. +> [!NOTE] +> Hash source expressions are only applicable to {{htmlelement("script")}} and {{htmlelement("style")}} elements. ### \ @@ -281,7 +283,8 @@ By default, if a CSP contains a `default-src` or a `script-src` directive, then The `unsafe-eval` keyword can be used to undo this protection, allowing dynamic evaluation of strings as JavaScript. -> [!WARNING] Developers should avoid `'unsafe-eval'`, because it defeats much of the purpose of having a CSP. +> [!WARNING] +> Developers should avoid `'unsafe-eval'`, because it defeats much of the purpose of having a CSP. See [`eval()` and similar APIs](/en-US/docs/Web/HTTP/CSP#eval_and_similar_apis) in the CSP guide for more usage information. @@ -306,7 +309,8 @@ Similarly, if a CSP contains `default-src` or a `style-src` directive, then inli The `unsafe-inline` keyword can be used to undo this protection, allowing all these forms to be loaded. -> [!WARNING] Developers should avoid `'unsafe-inline'`, because it defeats much of the purpose of having a CSP. +> [!WARNING] +> Developers should avoid `'unsafe-inline'`, because it defeats much of the purpose of having a CSP. See [Inline JavaScript](/en-US/docs/Web/HTTP/CSP#inline_javascript) in the CSP guide for more usage information. @@ -322,7 +326,8 @@ script-src 'unsafe-hashes' 'sha256-cd9827ad...' If the hash value matches the hash of an inline event handler attribute value or of a `style` attribute value, then the code will be allowed to execute. -> [!WARNING] The `'unsafe-hashes'` value is unsafe. +> [!WARNING] +> The `'unsafe-hashes'` value is unsafe. > > In particular, it enables an attack in which the content of the inline event handler attribute is injected into the document as an inline `